github

name	github
description	Operate GitHub through the gh CLI — typed github::* functions for pull requests, issues, repos, Actions runs/workflows, releases, and search, plus github::exec / github::api escape hatches for everything else.

github

The github worker wraps the GitHub CLI (gh). Thirty typed functions cover the high-traffic surface (pr, issue, repo, run, workflow, release, search); github::exec runs any other gh command verbatim, and github::api reaches any GitHub REST endpoint. Auth comes from the worker's GH_TOKEN configuration or the host's ambient gh auth login state. There is no local checkout: every repo-scoped call takes an explicit repo: "owner/name".

When to Use

• Check a PR before landing: github::pr::view, github::pr::checks (failing/pending checks are data, not errors), github::pr::diff.
• Open or shepherd a PR: github::pr::create / review / merge.
• File and triage issues: github::issue::create / list / comment / close.
• Watch or poke CI: github::run::list / view / rerun / cancel; dispatch with github::workflow::run.
• Cut or inspect releases: github::release::create / list / view.
• Find things org-wide: github::search::repos / issues / prs / code (qualifiers like repo:o/r is:open go in the query string).
• Anything gh does that has no typed function → github::exec { args: [...] }.
• Any REST endpoint → github::api { path: "repos/o/r/…", jq? }.

Boundaries

• Needs the gh CLI on the worker host; a missing binary errors at call time with code gh_not_found (functions still register without it).
• Mutations (create/edit/merge/comment/review/close/rerun/cancel/workflow run/release create) and both escape hatches are approval-gated by default; the read-only surface is allowed (see iii-permissions.yaml).
• Curated functions error on a non-zero gh exit (the message carries gh's stderr); github::exec returns exit_code/stderr/timed_out as data instead.
• Output is capped per stream (default 1 MiB) with *_truncated flags; per-call timeout_ms clamps to max_timeout_ms (default 120 s; 30 s when omitted).
• github::api paths take concrete owner/repo values — {owner}/{repo} placeholders need a checkout the worker does not have.

Functions

• github::pr::* — list, view, create, edit, merge, comment, review, diff, checks.
• github::issue::* — list, view, create, edit, comment, close.
• github::repo::* — view, list.
• github::run::* — list, view, rerun, cancel (Actions runs).
• github::workflow::* — list, run (workflow_dispatch).
• github::release::* — list, view, create.
• github::search::* — repos, issues, prs, code.
• github::exec — { args, stdin?, timeout_ms? } → the full outcome as data (stdout, stderr, exit_code, timed_out, truncation flags).
• github::api — { path, method?, fields?, body?, jq?, paginate?, timeout_ms? } → parsed JSON.