github

---
name: "github"
description: "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…"
license: "Apache-2.0"
---

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