$worker
github
v0.3.1GitHub CLI (gh) as an iii worker — typed github::pr/issue/repo/run/workflow/release/search functions, github::exec argv passthrough, and github::api for any GitHub REST endpoint.
iiiverifiedinstall
$iii worker add github@0.3.1
- macOS: arm64 · x64
- Linux: arm64 · armv7 · x64
- Windows: arm64 · x64 · x86
repoiii-hq/workers
exact versions are immutable; binary and bundle artifacts are digest-pinned.
agent-ready brief for v0.3.1
install + config + dependencies + readme + api reference, all in one place. fetch as agent-context.md for an llm to consume.
full markdown
the same content rendered as discrete blocks below is exposed as a single markdown document at
/workers/github.md?version=0.3.1. paste it into an llm prompt or pipe it through curl from a worker.install
install
$iii worker add github@0.3.1
configuration
iii-config.yaml
- default_timeout_ms: 30000
gh_executable:
max_output_bytes: 1048576
max_timeout_ms: 120000
token: ${GH_TOKEN}dependencies
no dependencies for v0.3.1
readme
README.md
github
GitHub as iii functions, powered by the GitHub CLI. Typed github::*
functions cover pull requests, issues, repos, Actions runs and workflows,
releases, and search; github::exec runs any other gh command and
github::api reaches any GitHub REST endpoint. Agents get
schema-discoverable GitHub operations with read-vs-mutate permission gating
instead of raw shell.
Install
iii worker add githubiii worker add fetches the binary, writes a config block into
~/.iii/config.yaml, and the engine starts the worker the next time it boots.
The worker shells out to the GitHub CLI — install
a current gh (the typed field sets are validated against gh 2.94) and give
it credentials: either gh auth login on the host, or set GH_TOKEN for
the worker (see Configuration).
Quickstart
use iii_sdk::{register_worker, InitOptions, TriggerRequest};
use serde_json::json;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let iii = register_worker("ws://localhost:49134", InitOptions::default());
// Open PRs in a repo, typed and parsed:
let prs = iii
.trigger(TriggerRequest {
function_id: "github::pr::list".into(),
payload: json!({ "repo": "cli/cli", "state": "open", "limit": 5 }),
action: None,
timeout_ms: Some(60_000),
})
.await?;
println!("{prs:#?}"); // { value: [{ number, title, state, url, … }] }
// Anything else gh can do, verbatim:
let version = iii
.trigger(TriggerRequest {
function_id: "github::exec".into(),
payload: json!({ "args": ["--version"] }),
action: None,
timeout_ms: Some(60_000),
})
.await?;
println!("{version:#?}"); // { stdout, stderr, exit_code, … }
Ok(())
}Configuration
gh_executable: "" # path to gh; empty = `gh` on PATH
token: "${GH_TOKEN}" # env-expanded; empty = ambient `gh auth login`
default_timeout_ms: 30000 # per-call timeout when timeout_ms is omitted
max_timeout_ms: 120000 # upper clamp for any per-call timeout_ms
max_output_bytes: 1048576 # per-stream capture cap (flags *_truncated)Other keys (and their defaults) live in src/config.rs.
api reference (json)
agent-api-reference.json
{
"functions": [
{
"description": "Call any GitHub REST endpoint via gh api: { path: \"repos/OWNER/REPO/issues\", method?, fields?, body?, jq?, paginate?, timeout_ms? } -> { value: <parsed JSON> }. fields become -f key=value form fields (default method flips to POST); body is sent verbatim as the JSON request body. Non-2xx responses are errors carrying gh's stderr.",
"metadata": {},
"name": "github::api",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"description": "Raw JSON request body, piped to gh via `--input -`. Mutually exclusive with fields (gh rejects the combination)."
},
"fields": {
"additionalProperties": {
"type": "string"
},
"description": "Form fields, each passed as `-f key=value` (string-typed on the wire).",
"type": [
"object",
"null"
]
},
"jq": {
"description": "jq expression gh applies to the response (`--jq`); keeps large responses small.",
"type": [
"string",
"null"
]
},
"method": {
"description": "HTTP method. gh defaults to GET, or POST when fields/body are present.",
"type": [
"string",
"null"
]
},
"paginate": {
"description": "Follow pagination to the end (`--paginate`); combine with jq.",
"type": [
"boolean",
"null"
]
},
"path": {
"description": "Endpoint path, with concrete owner/repo values (e.g. \"rate_limit\" or \"repos/cli/cli/issues\") — placeholder expansion needs a checkout the worker does not have.",
"type": "string"
},
"timeout_ms": {
"description": "Per-call timeout in ms, clamped to the configured max_timeout_ms.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"path"
],
"title": "ApiRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "Run any gh command: { args: [\"pr\", \"list\", \"-R\", \"owner/name\"], stdin?, timeout_ms? } -> { stdout, stderr, exit_code, duration_ms, timed_out, stdout_truncated, stderr_truncated }. A non-zero exit or a timeout is DATA here, not an error. The escape hatch for everything without a typed github::* function.",
"metadata": {},
"name": "github::exec",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"args": {
"description": "gh argv, without the leading `gh` (e.g. [\"pr\", \"status\", \"-R\", \"o/r\"]).",
"items": {
"type": "string"
},
"type": "array"
},
"stdin": {
"description": "Bytes piped to gh's stdin (for flags like `--body-file -`).",
"type": [
"string",
"null"
]
},
"timeout_ms": {
"description": "Per-call timeout in ms, clamped to the configured max_timeout_ms.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"args"
],
"title": "ExecRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "A completed `gh` invocation. This is also the `github::exec` response: a non-zero exit or a timeout is DATA here — only failure to run the process at all is a `GhError`.",
"properties": {
"duration_ms": {
"description": "Wall-clock duration of the invocation, in ms.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"exit_code": {
"description": "Process exit code; null when the process was killed (timeout).",
"format": "int32",
"type": [
"integer",
"null"
]
},
"stderr": {
"description": "Captured stderr (UTF-8 lossy), capped at `max_output_bytes`.",
"type": "string"
},
"stderr_truncated": {
"description": "True when stderr exceeded `max_output_bytes` and was truncated.",
"type": "boolean"
},
"stdout": {
"description": "Captured stdout (UTF-8 lossy), capped at `max_output_bytes`.",
"type": "string"
},
"stdout_truncated": {
"description": "True when stdout exceeded `max_output_bytes` and was truncated.",
"type": "boolean"
},
"timed_out": {
"description": "True when the timeout expired and the process group was killed.",
"type": "boolean"
}
},
"required": [
"duration_ms",
"stderr",
"stderr_truncated",
"stdout",
"stdout_truncated",
"timed_out"
],
"title": "GhOutcome",
"type": "object"
}
},
{
"description": "Close an issue: { repo, number, comment?, reason?: completed|not-planned } -> { output }.",
"metadata": {},
"name": "github::issue::close",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"CloseReason": {
"description": "Close reason. The wire value is kebab-case; gh's flag value for `not-planned` is the space-separated \"not planned\".",
"enum": [
"completed",
"not-planned"
],
"type": "string"
}
},
"properties": {
"comment": {
"description": "Closing comment.",
"type": [
"string",
"null"
]
},
"number": {
"description": "Issue number.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"reason": {
"anyOf": [
{
"$ref": "#/definitions/CloseReason"
},
{
"type": "null"
}
],
"description": "Close reason."
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
}
},
"required": [
"number",
"repo"
],
"title": "CloseRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Trimmed stdout of a mutating gh command (gh prints the created/updated URL or a confirmation line; some commands print nothing).",
"properties": {
"output": {
"description": "gh's stdout, trimmed.",
"type": "string"
}
},
"required": [
"output"
],
"title": "TextResponse",
"type": "object"
}
},
{
"description": "Comment on an issue: { repo, number, body } -> { output: <comment url> }.",
"metadata": {},
"name": "github::issue::comment",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"description": "Comment body (markdown).",
"type": "string"
},
"number": {
"description": "Issue number.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
}
},
"required": [
"body",
"number",
"repo"
],
"title": "CommentRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Trimmed stdout of a mutating gh command (gh prints the created/updated URL or a confirmation line; some commands print nothing).",
"properties": {
"output": {
"description": "gh's stdout, trimmed.",
"type": "string"
}
},
"required": [
"output"
],
"title": "TextResponse",
"type": "object"
}
},
{
"description": "Open an issue: { repo: \"owner/name\", title, body, labels?, assignees? } -> { output: <issue url> }.",
"metadata": {},
"name": "github::issue::create",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"assignees": {
"description": "Assignee logins.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"body": {
"description": "Issue body (markdown).",
"type": "string"
},
"labels": {
"description": "Labels to apply.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
},
"title": {
"description": "Issue title.",
"type": "string"
}
},
"required": [
"body",
"repo",
"title"
],
"title": "CreateRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Trimmed stdout of a mutating gh command (gh prints the created/updated URL or a confirmation line; some commands print nothing).",
"properties": {
"output": {
"description": "gh's stdout, trimmed.",
"type": "string"
}
},
"required": [
"output"
],
"title": "TextResponse",
"type": "object"
}
},
{
"description": "Edit an issue's title/body/labels/assignees: { repo, number, title?, body?, add_labels?, remove_labels?, add_assignees? } -> { output }.",
"metadata": {},
"name": "github::issue::edit",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"add_assignees": {
"description": "Assignee logins to add.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"add_labels": {
"description": "Labels to add.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"body": {
"description": "New body (markdown).",
"type": [
"string",
"null"
]
},
"number": {
"description": "Issue number.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"remove_labels": {
"description": "Labels to remove.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
},
"title": {
"description": "New title.",
"type": [
"string",
"null"
]
}
},
"required": [
"number",
"repo"
],
"title": "EditRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Trimmed stdout of a mutating gh command (gh prints the created/updated URL or a confirmation line; some commands print nothing).",
"properties": {
"output": {
"description": "gh's stdout, trimmed.",
"type": "string"
}
},
"required": [
"output"
],
"title": "TextResponse",
"type": "object"
}
},
{
"description": "List issues: { repo: \"owner/name\", state?, limit?, author?, labels?, assignee?, search? } -> { value: [{number, title, state, url, author, labels, assignees, milestone, createdAt, updatedAt}] }.",
"metadata": {},
"name": "github::issue::list",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"IssueState": {
"description": "Issue state filter.",
"enum": [
"open",
"closed",
"all"
],
"type": "string"
}
},
"properties": {
"assignee": {
"description": "Filter by assignee login.",
"type": [
"string",
"null"
]
},
"author": {
"description": "Filter by author login.",
"type": [
"string",
"null"
]
},
"labels": {
"description": "Filter by labels (all must match).",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"limit": {
"description": "Maximum number of results (gh default: 30).",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
},
"search": {
"description": "Search query narrowing the list further (GitHub search syntax).",
"type": [
"string",
"null"
]
},
"state": {
"anyOf": [
{
"$ref": "#/definitions/IssueState"
},
{
"type": "null"
}
],
"description": "Filter by state (gh default: open)."
}
},
"required": [
"repo"
],
"title": "ListRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "View one issue with body and comments: { repo: \"owner/name\", number } -> { value }.",
"metadata": {},
"name": "github::issue::view",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"number": {
"description": "Issue number.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
}
},
"required": [
"number",
"repo"
],
"title": "ViewRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "Internal: reload github configuration when it changes.",
"metadata": {},
"name": "github::on-config-change",
"request_schema": {
"properties": {},
"type": "object"
},
"response_schema": {
"properties": {
"ok": {
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "CI check rollup for a pull request: { repo, number } -> { value: [{bucket, name, state, link, workflow, description, startedAt, completedAt}] }. Failing or pending checks are data, not errors.",
"metadata": {},
"name": "github::pr::checks",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"number": {
"description": "Pull request number.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
}
},
"required": [
"number",
"repo"
],
"title": "ChecksRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "Comment on a pull request: { repo, number, body } -> { output: <comment url> }.",
"metadata": {},
"name": "github::pr::comment",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"body": {
"description": "Comment body (markdown).",
"type": "string"
},
"number": {
"description": "Pull request number.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
}
},
"required": [
"body",
"number",
"repo"
],
"title": "CommentRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Trimmed stdout of a mutating gh command (gh prints the created/updated URL or a confirmation line; some commands print nothing).",
"properties": {
"output": {
"description": "gh's stdout, trimmed.",
"type": "string"
}
},
"required": [
"output"
],
"title": "TextResponse",
"type": "object"
}
},
{
"description": "Open a pull request: { repo: \"owner/name\", title, body, head, base?, draft? } -> { output: <pr url> }. head is required: the worker runs outside any checkout, so gh cannot infer a current branch.",
"metadata": {},
"name": "github::pr::create",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"base": {
"description": "Base branch to merge into (gh default: the repo default branch).",
"type": [
"string",
"null"
]
},
"body": {
"description": "Pull request body (markdown).",
"type": "string"
},
"draft": {
"description": "Open as draft.",
"type": [
"boolean",
"null"
]
},
"head": {
"description": "Head branch the PR ships. Required: the worker runs outside any checkout, so gh cannot infer a current branch.",
"type": "string"
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
},
"title": {
"description": "Pull request title.",
"type": "string"
}
},
"required": [
"body",
"head",
"repo",
"title"
],
"title": "CreateRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Trimmed stdout of a mutating gh command (gh prints the created/updated URL or a confirmation line; some commands print nothing).",
"properties": {
"output": {
"description": "gh's stdout, trimmed.",
"type": "string"
}
},
"required": [
"output"
],
"title": "TextResponse",
"type": "object"
}
},
{
"description": "Unified diff of a pull request: { repo, number } -> { diff, truncated }. truncated is true when the diff exceeded the capture cap.",
"metadata": {},
"name": "github::pr::diff",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"number": {
"description": "Pull request number.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
}
},
"required": [
"number",
"repo"
],
"title": "DiffRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "`github::pr::diff` response.",
"properties": {
"diff": {
"description": "The unified diff as printed by `gh pr diff`.",
"type": "string"
},
"truncated": {
"description": "True when the diff exceeded the capture cap and was cut off.",
"type": "boolean"
}
},
"required": [
"diff",
"truncated"
],
"title": "DiffResponse",
"type": "object"
}
},
{
"description": "Edit a pull request's title/body/base/labels: { repo, number, title?, body?, base?, add_labels?, remove_labels? } -> { output }.",
"metadata": {},
"name": "github::pr::edit",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"add_labels": {
"description": "Labels to add.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"base": {
"description": "New base branch.",
"type": [
"string",
"null"
]
},
"body": {
"description": "New body (markdown).",
"type": [
"string",
"null"
]
},
"number": {
"description": "Pull request number.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"remove_labels": {
"description": "Labels to remove.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
},
"title": {
"description": "New title.",
"type": [
"string",
"null"
]
}
},
"required": [
"number",
"repo"
],
"title": "EditRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Trimmed stdout of a mutating gh command (gh prints the created/updated URL or a confirmation line; some commands print nothing).",
"properties": {
"output": {
"description": "gh's stdout, trimmed.",
"type": "string"
}
},
"required": [
"output"
],
"title": "TextResponse",
"type": "object"
}
},
{
"description": "List pull requests: { repo: \"owner/name\", state?, limit?, author?, labels?, base?, search? } -> { value: [{number, title, state, url, author, headRefName, baseRefName, isDraft, labels, createdAt, updatedAt}] }.",
"metadata": {},
"name": "github::pr::list",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"PrState": {
"description": "PR state filter.",
"enum": [
"open",
"closed",
"merged",
"all"
],
"type": "string"
}
},
"properties": {
"author": {
"description": "Filter by author login.",
"type": [
"string",
"null"
]
},
"base": {
"description": "Filter by base branch.",
"type": [
"string",
"null"
]
},
"labels": {
"description": "Filter by labels (all must match).",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"limit": {
"description": "Maximum number of results (gh default: 30).",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
},
"search": {
"description": "Search query narrowing the list further (GitHub search syntax).",
"type": [
"string",
"null"
]
},
"state": {
"anyOf": [
{
"$ref": "#/definitions/PrState"
},
{
"type": "null"
}
],
"description": "Filter by state (gh default: open)."
}
},
"required": [
"repo"
],
"title": "ListRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "Merge a pull request: { repo, number, method: merge|squash|rebase, delete_branch?, auto? } -> { output }. auto enables auto-merge once requirements pass.",
"metadata": {},
"name": "github::pr::merge",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"MergeMethod": {
"description": "Merge method.",
"enum": [
"merge",
"squash",
"rebase"
],
"type": "string"
}
},
"properties": {
"auto": {
"description": "Enable auto-merge: merge automatically once requirements pass.",
"type": [
"boolean",
"null"
]
},
"delete_branch": {
"description": "Delete the head branch after merging.",
"type": [
"boolean",
"null"
]
},
"method": {
"allOf": [
{
"$ref": "#/definitions/MergeMethod"
}
],
"description": "Merge method."
},
"number": {
"description": "Pull request number.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
}
},
"required": [
"method",
"number",
"repo"
],
"title": "MergeRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Trimmed stdout of a mutating gh command (gh prints the created/updated URL or a confirmation line; some commands print nothing).",
"properties": {
"output": {
"description": "gh's stdout, trimmed.",
"type": "string"
}
},
"required": [
"output"
],
"title": "TextResponse",
"type": "object"
}
},
{
"description": "Review a pull request: { repo, number, event: approve|request-changes|comment, body? } -> { output }. gh requires body for request-changes and comment reviews.",
"metadata": {},
"name": "github::pr::review",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"ReviewEvent": {
"description": "Review event.",
"enum": [
"approve",
"request-changes",
"comment"
],
"type": "string"
}
},
"properties": {
"body": {
"description": "Review body (gh requires it for request-changes and comment).",
"type": [
"string",
"null"
]
},
"event": {
"allOf": [
{
"$ref": "#/definitions/ReviewEvent"
}
],
"description": "Review event."
},
"number": {
"description": "Pull request number.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
}
},
"required": [
"event",
"number",
"repo"
],
"title": "ReviewRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Trimmed stdout of a mutating gh command (gh prints the created/updated URL or a confirmation line; some commands print nothing).",
"properties": {
"output": {
"description": "gh's stdout, trimmed.",
"type": "string"
}
},
"required": [
"output"
],
"title": "TextResponse",
"type": "object"
}
},
{
"description": "View one pull request with body, mergeability, review decision, and diff stats: { repo: \"owner/name\", number } -> { value }.",
"metadata": {},
"name": "github::pr::view",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"number": {
"description": "Pull request number.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
}
},
"required": [
"number",
"repo"
],
"title": "ViewRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "Create a release: { repo, tag, title?, notes?, generate_notes?, draft?, prerelease?, target? } -> { output: <release url> }. generate_notes autogenerates from merged PRs.",
"metadata": {},
"name": "github::release::create",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"draft": {
"description": "Create as draft.",
"type": [
"boolean",
"null"
]
},
"generate_notes": {
"description": "Autogenerate notes from merged PRs since the last release.",
"type": [
"boolean",
"null"
]
},
"notes": {
"description": "Release notes body (markdown).",
"type": [
"string",
"null"
]
},
"prerelease": {
"description": "Mark as prerelease.",
"type": [
"boolean",
"null"
]
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
},
"tag": {
"description": "Tag to release (created at target if it does not exist).",
"type": "string"
},
"target": {
"description": "Target branch or commit SHA for the tag (gh default: the default branch).",
"type": [
"string",
"null"
]
},
"title": {
"description": "Release title.",
"type": [
"string",
"null"
]
}
},
"required": [
"repo",
"tag"
],
"title": "CreateRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Trimmed stdout of a mutating gh command (gh prints the created/updated URL or a confirmation line; some commands print nothing).",
"properties": {
"output": {
"description": "gh's stdout, trimmed.",
"type": "string"
}
},
"required": [
"output"
],
"title": "TextResponse",
"type": "object"
}
},
{
"description": "List releases: { repo: \"owner/name\", limit? } -> { value: [{tagName, name, isDraft, isLatest, isPrerelease, createdAt, publishedAt}] }.",
"metadata": {},
"name": "github::release::list",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"description": "Maximum number of results (gh default: 30).",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
}
},
"required": [
"repo"
],
"title": "ListRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "View one release including body and assets: { repo: \"owner/name\", tag } -> { value }.",
"metadata": {},
"name": "github::release::view",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
},
"tag": {
"description": "Release tag (e.g. \"v1.2.0\").",
"type": "string"
}
},
"required": [
"repo",
"tag"
],
"title": "ViewRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "List repositories of an owner: { owner?, limit? } -> { value: [{name, nameWithOwner, description, url, visibility, ...}] }. owner defaults to the authenticated user.",
"metadata": {},
"name": "github::repo::list",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"description": "Maximum number of results (gh default: 30).",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"owner": {
"description": "User or organization login (default: the authenticated user).",
"type": [
"string",
"null"
]
}
},
"title": "ListRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "View a repository's metadata (description, default branch, visibility, stars, language, topics, latest release): { repo: \"owner/name\" } -> { value }.",
"metadata": {},
"name": "github::repo::view",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
}
},
"required": [
"repo"
],
"title": "ViewRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "Cancel an in-progress workflow run: { repo, run_id } -> { output }.",
"metadata": {},
"name": "github::run::cancel",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
},
"run_id": {
"description": "Workflow run id.",
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"repo",
"run_id"
],
"title": "RunCancelRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Trimmed stdout of a mutating gh command (gh prints the created/updated URL or a confirmation line; some commands print nothing).",
"properties": {
"output": {
"description": "gh's stdout, trimmed.",
"type": "string"
}
},
"required": [
"output"
],
"title": "TextResponse",
"type": "object"
}
},
{
"description": "List GitHub Actions workflow runs: { repo: \"owner/name\", workflow?, branch?, status?, limit? } -> { value: [{databaseId, displayTitle, workflowName, headBranch, event, status, conclusion, url, ...}] }.",
"metadata": {},
"name": "github::run::list",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"branch": {
"description": "Filter by branch.",
"type": [
"string",
"null"
]
},
"limit": {
"description": "Maximum number of results (gh default: 20).",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
},
"status": {
"description": "Filter by status (e.g. completed, in_progress, queued, failure, success).",
"type": [
"string",
"null"
]
},
"workflow": {
"description": "Filter by workflow (file name, e.g. \"ci.yml\").",
"type": [
"string",
"null"
]
}
},
"required": [
"repo"
],
"title": "RunListRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "Rerun a workflow run: { repo, run_id, failed? } -> { output }. failed reruns only the failed jobs.",
"metadata": {},
"name": "github::run::rerun",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"failed": {
"description": "Rerun only the failed jobs.",
"type": [
"boolean",
"null"
]
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
},
"run_id": {
"description": "Workflow run id.",
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"repo",
"run_id"
],
"title": "RunRerunRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Trimmed stdout of a mutating gh command (gh prints the created/updated URL or a confirmation line; some commands print nothing).",
"properties": {
"output": {
"description": "gh's stdout, trimmed.",
"type": "string"
}
},
"required": [
"output"
],
"title": "TextResponse",
"type": "object"
}
},
{
"description": "View one workflow run including its jobs and their steps: { repo: \"owner/name\", run_id } -> { value }.",
"metadata": {},
"name": "github::run::view",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
},
"run_id": {
"description": "Workflow run id (databaseId from github::run::list).",
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"repo",
"run_id"
],
"title": "RunViewRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "Search code: { query, limit? } -> { value: [{path, repository, sha, url, textMatches}] }. Use qualifiers like \"repo:o/r language:rust symbol\".",
"metadata": {},
"name": "github::search::code",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"description": "Maximum number of results (gh default: 30).",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"query": {
"description": "Search query (GitHub search syntax, qualifiers included).",
"type": "string"
}
},
"required": [
"query"
],
"title": "CodeRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "Search issues across repositories: { query, limit? } -> { value: [{number, title, state, url, repository, author, labels, commentsCount, ...}] }. Use qualifiers like \"repo:o/r is:open label:bug\".",
"metadata": {},
"name": "github::search::issues",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"description": "Maximum number of results (gh default: 30).",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"query": {
"description": "Search query (GitHub search syntax, qualifiers included).",
"type": "string"
}
},
"required": [
"query"
],
"title": "IssuesRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "Search pull requests across repositories: { query, limit? } -> { value }. Use qualifiers like \"repo:o/r is:open review:required\".",
"metadata": {},
"name": "github::search::prs",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"description": "Maximum number of results (gh default: 30).",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"query": {
"description": "Search query (GitHub search syntax, qualifiers included).",
"type": "string"
}
},
"required": [
"query"
],
"title": "PrsRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "Search repositories: { query, limit? } -> { value: [{fullName, description, url, visibility, stargazersCount, language, updatedAt, ...}] }. GitHub search syntax (e.g. \"language:rust stars:>100 topic:cli\").",
"metadata": {},
"name": "github::search::repos",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"description": "Maximum number of results (gh default: 30).",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"query": {
"description": "Search query (GitHub search syntax, qualifiers included).",
"type": "string"
}
},
"required": [
"query"
],
"title": "ReposRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "Serve the github worker's injected console UI assets (content function for its console:script / console:style triggers).",
"metadata": {
"internal": true
},
"name": "github::ui-content",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Input of the content function: the console asks for one asset by path.",
"properties": {
"path": {
"description": "The asset path from the trigger config (e.g. `state/page.js`).",
"type": "string"
}
},
"required": [
"path"
],
"title": "UiContentInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Output of the content function.",
"properties": {
"content": {
"description": "The asset source, verbatim.",
"type": "string"
},
"content_type": {
"description": "MIME type the console should serve the asset with.",
"type": "string"
}
},
"required": [
"content",
"content_type"
],
"title": "UiContentResult",
"type": "object"
}
},
{
"description": "List workflows in a repo: { repo: \"owner/name\", all? } -> { value: [{id, name, path, state}] }. all includes disabled workflows.",
"metadata": {},
"name": "github::workflow::list",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"all": {
"description": "Include disabled workflows.",
"type": [
"boolean",
"null"
]
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
}
},
"required": [
"repo"
],
"title": "WorkflowListRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Parsed `--json` output of a gh command.",
"properties": {
"value": {
"description": "The JSON gh printed for the requested `--json` fields."
}
},
"required": [
"value"
],
"title": "ValueResponse",
"type": "object"
}
},
{
"description": "Dispatch a workflow (workflow_dispatch): { repo, workflow: <file name or id>, ref?, inputs? } -> { output }. inputs become -f key=value pairs.",
"metadata": {},
"name": "github::workflow::run",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"inputs": {
"additionalProperties": {
"type": "string"
},
"description": "workflow_dispatch inputs, each passed as `-f key=value`.",
"type": [
"object",
"null"
]
},
"ref": {
"description": "Branch or tag to run on (gh default: the repo default branch).",
"type": [
"string",
"null"
]
},
"repo": {
"description": "Target repository, \"owner/name\".",
"type": "string"
},
"workflow": {
"description": "Workflow file name (e.g. \"release.yml\") or numeric id.",
"type": "string"
}
},
"required": [
"repo",
"workflow"
],
"title": "WorkflowRunRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Trimmed stdout of a mutating gh command (gh prints the created/updated URL or a confirmation line; some commands print nothing).",
"properties": {
"output": {
"description": "gh's stdout, trimmed.",
"type": "string"
}
},
"required": [
"output"
],
"title": "TextResponse",
"type": "object"
}
}
],
"triggers": [
{
"description": "Fires after each github function runs; carries the call + a short result summary.",
"invocation_schema": {},
"metadata": {},
"name": "github::called",
"return_schema": {}
}
]
}