skip to content
iii / worker
$worker

github

v0.2.1

GitHub 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.

iiiverified
41 installs6 in 7d0 today
install
$iii worker add github@0.2.1
binarygithubghgitpull-requestsissuesactionsreleases
  • macOS: arm64 · x64
  • Linux: arm64 · armv7 · x64
  • Windows: arm64 · x64 · x86
33functions0triggers1skills0depsv0.2.1version
repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

functions

33

github::api

function

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.

request
  • bodyunknown

    Raw JSON request body, piped to gh via `--input -`. Mutually exclusive with fields (gh rejects the combination).

  • fieldsobject

    Form fields, each passed as `-f key=value` (string-typed on the wire).

  • jqstring

    jq expression gh applies to the response (`--jq`); keeps large responses small.

  • methodstring

    HTTP method. gh defaults to GET, or POST when fields/body are present.

  • paginateboolean

    Follow pagination to the end (`--paginate`); combine with jq.

  • pathstringrequired

    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.

  • timeout_msinteger· uint64min 0

    Per-call timeout in ms, clamped to the configured max_timeout_ms.

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::exec

function

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.

request
  • argsstring[]required

    gh argv, without the leading `gh` (e.g. ["pr", "status", "-R", "o/r"]).

  • stdinstring

    Bytes piped to gh's stdin (for flags like `--body-file -`).

  • timeout_msinteger· uint64min 0

    Per-call timeout in ms, clamped to the configured max_timeout_ms.

response
  • duration_msinteger· uint64requiredmin 0

    Wall-clock duration of the invocation, in ms.

  • exit_codeinteger· int32

    Process exit code; null when the process was killed (timeout).

  • stderrstringrequired

    Captured stderr (UTF-8 lossy), capped at `max_output_bytes`.

  • stderr_truncatedbooleanrequired

    True when stderr exceeded `max_output_bytes` and was truncated.

  • stdoutstringrequired

    Captured stdout (UTF-8 lossy), capped at `max_output_bytes`.

  • stdout_truncatedbooleanrequired

    True when stdout exceeded `max_output_bytes` and was truncated.

  • timed_outbooleanrequired

    True when the timeout expired and the process group was killed.

github::issue::close

function

Close an issue: { repo, number, comment?, reason?: completed|not-planned } -> { output }.

request
  • commentstring

    Closing comment.

  • numberinteger· uint64requiredmin 0

    Issue number.

  • reasonany of

    Close reason.

    any of (2)
    variant 1
    valuestringenum: completed, not-planned
    variant 2
    valuenull
  • repostringrequired

    Target repository, "owner/name".

response
  • outputstringrequired

    gh's stdout, trimmed.

github::issue::comment

function

Comment on an issue: { repo, number, body } -> { output: <comment url> }.

request
  • bodystringrequired

    Comment body (markdown).

  • numberinteger· uint64requiredmin 0

    Issue number.

  • repostringrequired

    Target repository, "owner/name".

response
  • outputstringrequired

    gh's stdout, trimmed.

github::issue::create

function

Open an issue: { repo: "owner/name", title, body, labels?, assignees? } -> { output: <issue url> }.

request
  • assigneesstring[]

    Assignee logins.

  • bodystringrequired

    Issue body (markdown).

  • labelsstring[]

    Labels to apply.

  • repostringrequired

    Target repository, "owner/name".

  • titlestringrequired

    Issue title.

response
  • outputstringrequired

    gh's stdout, trimmed.

github::issue::edit

function

Edit an issue's title/body/labels/assignees: { repo, number, title?, body?, add_labels?, remove_labels?, add_assignees? } -> { output }.

request
  • add_assigneesstring[]

    Assignee logins to add.

  • add_labelsstring[]

    Labels to add.

  • bodystring

    New body (markdown).

  • numberinteger· uint64requiredmin 0

    Issue number.

  • remove_labelsstring[]

    Labels to remove.

  • repostringrequired

    Target repository, "owner/name".

  • titlestring

    New title.

response
  • outputstringrequired

    gh's stdout, trimmed.

github::issue::list

function

List issues: { repo: "owner/name", state?, limit?, author?, labels?, assignee?, search? } -> { value: [{number, title, state, url, author, labels, assignees, milestone, createdAt, updatedAt}] }.

request
  • assigneestring

    Filter by assignee login.

  • authorstring

    Filter by author login.

  • labelsstring[]

    Filter by labels (all must match).

  • limitinteger· uint32min 0

    Maximum number of results (gh default: 30).

  • repostringrequired

    Target repository, "owner/name".

  • searchstring

    Search query narrowing the list further (GitHub search syntax).

  • stateany of

    Filter by state (gh default: open).

    any of (2)
    variant 1
    valuestringenum: open, closed, all
    variant 2
    valuenull
response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::issue::view

function

View one issue with body and comments: { repo: "owner/name", number } -> { value }.

request
  • numberinteger· uint64requiredmin 0

    Issue number.

  • repostringrequired

    Target repository, "owner/name".

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::on-config-change

function

Internal: reload github configuration when it changes.

request
empty object
response
  • okboolean

github::pr::checks

function

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.

request
  • numberinteger· uint64requiredmin 0

    Pull request number.

  • repostringrequired

    Target repository, "owner/name".

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::pr::comment

function

Comment on a pull request: { repo, number, body } -> { output: <comment url> }.

request
  • bodystringrequired

    Comment body (markdown).

  • numberinteger· uint64requiredmin 0

    Pull request number.

  • repostringrequired

    Target repository, "owner/name".

response
  • outputstringrequired

    gh's stdout, trimmed.

github::pr::create

function

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.

request
  • basestring

    Base branch to merge into (gh default: the repo default branch).

  • bodystringrequired

    Pull request body (markdown).

  • draftboolean

    Open as draft.

  • headstringrequired

    Head branch the PR ships. Required: the worker runs outside any checkout, so gh cannot infer a current branch.

  • repostringrequired

    Target repository, "owner/name".

  • titlestringrequired

    Pull request title.

response
  • outputstringrequired

    gh's stdout, trimmed.

github::pr::diff

function

Unified diff of a pull request: { repo, number } -> { diff, truncated }. truncated is true when the diff exceeded the capture cap.

request
  • numberinteger· uint64requiredmin 0

    Pull request number.

  • repostringrequired

    Target repository, "owner/name".

response
  • diffstringrequired

    The unified diff as printed by `gh pr diff`.

  • truncatedbooleanrequired

    True when the diff exceeded the capture cap and was cut off.

github::pr::edit

function

Edit a pull request's title/body/base/labels: { repo, number, title?, body?, base?, add_labels?, remove_labels? } -> { output }.

request
  • add_labelsstring[]

    Labels to add.

  • basestring

    New base branch.

  • bodystring

    New body (markdown).

  • numberinteger· uint64requiredmin 0

    Pull request number.

  • remove_labelsstring[]

    Labels to remove.

  • repostringrequired

    Target repository, "owner/name".

  • titlestring

    New title.

response
  • outputstringrequired

    gh's stdout, trimmed.

github::pr::list

function

List pull requests: { repo: "owner/name", state?, limit?, author?, labels?, base?, search? } -> { value: [{number, title, state, url, author, headRefName, baseRefName, isDraft, labels, createdAt, updatedAt}] }.

request
  • authorstring

    Filter by author login.

  • basestring

    Filter by base branch.

  • labelsstring[]

    Filter by labels (all must match).

  • limitinteger· uint32min 0

    Maximum number of results (gh default: 30).

  • repostringrequired

    Target repository, "owner/name".

  • searchstring

    Search query narrowing the list further (GitHub search syntax).

  • stateany of

    Filter by state (gh default: open).

    any of (2)
    variant 1
    valuestringenum: open, closed, merged, all
    variant 2
    valuenull
response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::pr::merge

function

Merge a pull request: { repo, number, method: merge|squash|rebase, delete_branch?, auto? } -> { output }. auto enables auto-merge once requirements pass.

request
  • autoboolean

    Enable auto-merge: merge automatically once requirements pass.

  • delete_branchboolean

    Delete the head branch after merging.

  • methodall ofrequired

    Merge method.

    all of (1)
    variant 1
    valuestringenum: merge, squash, rebase
  • numberinteger· uint64requiredmin 0

    Pull request number.

  • repostringrequired

    Target repository, "owner/name".

response
  • outputstringrequired

    gh's stdout, trimmed.

github::pr::review

function

Review a pull request: { repo, number, event: approve|request-changes|comment, body? } -> { output }. gh requires body for request-changes and comment reviews.

request
  • bodystring

    Review body (gh requires it for request-changes and comment).

  • eventall ofrequired

    Review event.

    all of (1)
    variant 1
    valuestringenum: approve, request-changes, comment
  • numberinteger· uint64requiredmin 0

    Pull request number.

  • repostringrequired

    Target repository, "owner/name".

response
  • outputstringrequired

    gh's stdout, trimmed.

github::pr::view

function

View one pull request with body, mergeability, review decision, and diff stats: { repo: "owner/name", number } -> { value }.

request
  • numberinteger· uint64requiredmin 0

    Pull request number.

  • repostringrequired

    Target repository, "owner/name".

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::release::create

function

Create a release: { repo, tag, title?, notes?, generate_notes?, draft?, prerelease?, target? } -> { output: <release url> }. generate_notes autogenerates from merged PRs.

request
  • draftboolean

    Create as draft.

  • generate_notesboolean

    Autogenerate notes from merged PRs since the last release.

  • notesstring

    Release notes body (markdown).

  • prereleaseboolean

    Mark as prerelease.

  • repostringrequired

    Target repository, "owner/name".

  • tagstringrequired

    Tag to release (created at target if it does not exist).

  • targetstring

    Target branch or commit SHA for the tag (gh default: the default branch).

  • titlestring

    Release title.

response
  • outputstringrequired

    gh's stdout, trimmed.

github::release::list

function

List releases: { repo: "owner/name", limit? } -> { value: [{tagName, name, isDraft, isLatest, isPrerelease, createdAt, publishedAt}] }.

request
  • limitinteger· uint32min 0

    Maximum number of results (gh default: 30).

  • repostringrequired

    Target repository, "owner/name".

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::release::view

function

View one release including body and assets: { repo: "owner/name", tag } -> { value }.

request
  • repostringrequired

    Target repository, "owner/name".

  • tagstringrequired

    Release tag (e.g. "v1.2.0").

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::repo::list

function

List repositories of an owner: { owner?, limit? } -> { value: [{name, nameWithOwner, description, url, visibility, ...}] }. owner defaults to the authenticated user.

request
  • limitinteger· uint32min 0

    Maximum number of results (gh default: 30).

  • ownerstring

    User or organization login (default: the authenticated user).

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::repo::view

function

View a repository's metadata (description, default branch, visibility, stars, language, topics, latest release): { repo: "owner/name" } -> { value }.

request
  • repostringrequired

    Target repository, "owner/name".

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::run::cancel

function

Cancel an in-progress workflow run: { repo, run_id } -> { output }.

request
  • repostringrequired

    Target repository, "owner/name".

  • run_idinteger· uint64requiredmin 0

    Workflow run id.

response
  • outputstringrequired

    gh's stdout, trimmed.

github::run::list

function

List GitHub Actions workflow runs: { repo: "owner/name", workflow?, branch?, status?, limit? } -> { value: [{databaseId, displayTitle, workflowName, headBranch, event, status, conclusion, url, ...}] }.

request
  • branchstring

    Filter by branch.

  • limitinteger· uint32min 0

    Maximum number of results (gh default: 20).

  • repostringrequired

    Target repository, "owner/name".

  • statusstring

    Filter by status (e.g. completed, in_progress, queued, failure, success).

  • workflowstring

    Filter by workflow (file name, e.g. "ci.yml").

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::run::rerun

function

Rerun a workflow run: { repo, run_id, failed? } -> { output }. failed reruns only the failed jobs.

request
  • failedboolean

    Rerun only the failed jobs.

  • repostringrequired

    Target repository, "owner/name".

  • run_idinteger· uint64requiredmin 0

    Workflow run id.

response
  • outputstringrequired

    gh's stdout, trimmed.

github::run::view

function

View one workflow run including its jobs and their steps: { repo: "owner/name", run_id } -> { value }.

request
  • repostringrequired

    Target repository, "owner/name".

  • run_idinteger· uint64requiredmin 0

    Workflow run id (databaseId from github::run::list).

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::search::code

function

Search code: { query, limit? } -> { value: [{path, repository, sha, url, textMatches}] }. Use qualifiers like "repo:o/r language:rust symbol".

request
  • limitinteger· uint32min 0

    Maximum number of results (gh default: 30).

  • querystringrequired

    Search query (GitHub search syntax, qualifiers included).

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::search::issues

function

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".

request
  • limitinteger· uint32min 0

    Maximum number of results (gh default: 30).

  • querystringrequired

    Search query (GitHub search syntax, qualifiers included).

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::search::prs

function

Search pull requests across repositories: { query, limit? } -> { value }. Use qualifiers like "repo:o/r is:open review:required".

request
  • limitinteger· uint32min 0

    Maximum number of results (gh default: 30).

  • querystringrequired

    Search query (GitHub search syntax, qualifiers included).

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::search::repos

function

Search repositories: { query, limit? } -> { value: [{fullName, description, url, visibility, stargazersCount, language, updatedAt, ...}] }. GitHub search syntax (e.g. "language:rust stars:>100 topic:cli").

request
  • limitinteger· uint32min 0

    Maximum number of results (gh default: 30).

  • querystringrequired

    Search query (GitHub search syntax, qualifiers included).

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::workflow::list

function

List workflows in a repo: { repo: "owner/name", all? } -> { value: [{id, name, path, state}] }. all includes disabled workflows.

request
  • allboolean

    Include disabled workflows.

  • repostringrequired

    Target repository, "owner/name".

response
  • valueunknownrequired

    The JSON gh printed for the requested `--json` fields.

github::workflow::run

function

Dispatch a workflow (workflow_dispatch): { repo, workflow: <file name or id>, ref?, inputs? } -> { output }. inputs become -f key=value pairs.

request
  • inputsobject

    workflow_dispatch inputs, each passed as `-f key=value`.

  • refstring

    Branch or tag to run on (gh default: the repo default branch).

  • repostringrequired

    Target repository, "owner/name".

  • workflowstringrequired

    Workflow file name (e.g. "release.yml") or numeric id.

response
  • outputstringrequired

    gh's stdout, trimmed.

triggers

0
no triggers registered