`github` Provider¶

runtime github <operation> [args...]

Auth provider: github — one token (RUNTIME_GITHUB_TOKEN) serves every operation, whatever transport it uses.

runtime github --help      # the authoritative, live operation surface

Operations¶

Operation	Transport
`repo list [org] [key=value...]`	rest
`repo view <owner>/<repo>`	rest
`repo create <key=value...>`	rest
`repo summary <owner>/<repo>`	graphql
`issue list [key=value...]`	rest
`issue create`	cli (`gh`)
`org list`	rest
`team list`	rest
`user get`	rest
`notification list`	rest
`pr list` / `pr view` / `pr create`	cli (`gh`)
`workflow list` / `workflow run`	cli (`gh`)
`run list` / `run view`	cli (`gh`)
`api <METHOD> <path> [key=value...]`	rest
`graphql <query> [key=value...]`	graphql

repo summary is GraphQL because it answers in one round trip what REST needs four calls for. That is the provider's stated rule for choosing GraphQL — and it is the provider's decision, not yours.

The table can't drift

A test asserts that every declared operation actually resolves, so the published surface always matches the implementation. Still prefer runtime github --help — it describes the binary you have installed.

Argument conventions¶

Convention	Meaning
`key=value`	Query parameters on GET/DELETE; JSON body fields on POST/PUT/PATCH. `true`/`false` and integers are coerced to real types
`{org}`	Auto-substituted from the active Runtime Context
`{owner}`, `{repo}`, `{branch}`	Literal placeholders — substitute them yourself

Operations that fall back to Runtime Context when no org is given: repo list, issue list, team list.

runtime context use staging
runtime github repo list           # defaults to staging's github.organization
runtime github repo list acme      # explicit argument wins

CLI-backed operations forward flags verbatim¶

runtime github pr list --state open --limit 100
runtime github pr list --repo cli/cli --json number,title,author,reviewDecision
runtime github run view 1234567890 --log-failed

gh's own flags — including --json — reach it untouched, because provider commands disable flag parsing. gh auth login is never needed: the runtime forwards the validated token as GH_TOKEN.

Combine with the runtime's own output flag by putting it first:

runtime --output json github pr list --json number,title

The escape hatches¶

When no curated operation covers what you need:

# any REST endpoint
runtime github api GET /repos/cli/cli/community/profile
runtime github api PATCH /repos/{owner}/{repo} default_branch=main delete_branch_on_merge=true
runtime github api PUT /repos/{owner}/{repo}/topics names[]=service names[]=go

# any GraphQL query
runtime github graphql 'query($org:String!){ organization(login:$org){ repositories(first:100){ nodes{ nameWithOwner isPrivate } } } }' org=my-org

# anything gh does that the provider doesn't expose
runtime command run gh secret set DEPLOY_KEY --repo {owner}/{repo} --body "value"
runtime command run gh release create v1.2.0 --generate-notes

These are escape hatches, not a default style. Prefer a curated operation when one exists — it is the stable contract.

api DELETE is denied by the seeded policy

The api escape hatch can reach any REST endpoint, including destructive ones the curated operations deliberately don't expose. There is no repo delete operation — the escape hatch was the only way to reach it, so denying the DELETE method closes that path.

runtime github api DELETE /repos/owner/repo    # refused before any network request

Loosen it in policy-config.yaml if you genuinely need it, and expect the denial in the audit log either way.

Common use cases¶

The Runtime Home ships a full use-case reference — organized by what engineers are trying to achieve rather than by API surface:

cat ~/.engineering-runtime/commands/github_commands.txt

It covers golden-path service onboarding, repository inventory and standards audits, access review, branch protection compliance, review throughput, CI/CD health, releases, security posture, dependency hygiene, incident forensics, secrets configuration, onboarding/offboarding, DORA-shaped metrics, issue triage, and repository lifecycle.

A few representative starting points:

InventoryAccess reviewCI healthSecurity posture

runtime github repo list
runtime github repo list acme per_page=100 sort=pushed direction=desc
runtime github repo summary cli/cli
runtime github api GET /repos/{owner}/{repo}/community/profile

runtime github team list
runtime github api GET /orgs/{org}/members role=admin per_page=100
runtime github api GET /orgs/{org}/outside_collaborators per_page=100
runtime github api GET /orgs/{org}/invitations

runtime github workflow list
runtime github run list --limit 20 --status failure
runtime github run view 1234567890 --log-failed
runtime github api POST /repos/{owner}/{repo}/actions/runs/{run_id}/rerun-failed-jobs

runtime github api GET /orgs/{org}/dependabot/alerts state=open severity=critical
runtime github api GET /orgs/{org}/code-scanning/alerts state=open
runtime github api GET /orgs/{org}/secret-scanning/alerts state=open

What doesn't work, and why¶

Endpoint / pattern	Why
`/app`, `/app/installations`, `/marketplace_listing/*`, `/user/installations`	Need a GitHub App JWT, not a personal access token. Expect 401
`api GET /search/issues` with no `q=`	Returns 422. Quote the whole pair: `'q=repo:cli/cli is:open'`
`/user/packages` with no `package_type=`	Requires `container`, `npm`, `maven`, …
Org audit log	Enterprise Cloud only, absent from the public REST description. Use the Enterprise API or a UI export
Reading a secret's value	Never readable by design — only names and metadata
Setting a secret via raw REST	Needs libsodium encryption. Use `command run gh secret set`
403 on org security endpoints	Usually means GitHub Advanced Security isn't enabled for that org

The runtime percent-encodes query values, so spaces and colons in a search query are safe once the shell keeps the pair as one token.

In capabilities¶

workflow:
  - provider: github
    args: [repo, list, "${organization}", per_page=100]

  - provider: github
    args: [repo, summary, "${repository}"]

  - provider: github
    args: [api, GET, "/repos/${repository}/community/profile"]

Declare inputs; never hardcode an org, repo or environment. Never name a transport. See the Authoring Reference, and ~/.engineering-runtime/specs/github/capability-spec-github.md for the GitHub-specific contract.

github Provider¶