github Provider¶
Auth provider: github — one token
(RUNTIME_GITHUB_TOKEN) serves every operation,
whatever transport it uses.
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 |
file put <owner>/<repo> <path> message=… content=… [branch=…] [sha=…] |
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 |
The organization is always an argument. GitHub has no native context for Runtime to observe, so nothing supplies one on your behalf.
runtime github repo list # your own repositories
runtime github repo list acme # the organization's
runtime github issue list acme # required here
runtime github team list acme # required here
issue list and team list refuse without it. A flag is never mistaken for
an organization: repo list --limit 5 lists your own repositories.
The default text form is a bounded human table rather than the REST response's raw JSON. It ends with the number of repositories returned:
REPOSITORY VISIBILITY UPDATED DESCRIPTION
engineeringruntime/engineering-runtime-agent PUBLIC 2026-09-03T07:10:44Z Vendor-neutral Runtime Agent contract and optio…
1 repository
Use runtime --output json github repo list when automation needs the complete
typed API objects.
file put — create or compare-and-set a repository file¶
This is the decided push route for an authored capability. The provider
UTF-8/base64-encodes content. Callers do not hand-build the Contents API.
runtime github file put owner/repo caps/note.md \
message="Add note" content="hello"
# update: fetch the blob sha, then compare-and-set
runtime github api GET /repos/owner/repo/contents/caps/note.md
runtime github file put owner/repo caps/note.md \
message="Update note" content="hello again" sha=<blob-sha>
Omit sha to create-only: GitHub refuses if the path already exists. A
stale sha fails rather than overwriting newer content. Token needs
contents: write. Audit records the operation and target, never the file
bytes.
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. Provider-chosen gh operations receive the
configured, validated token as GH_TOKEN; Runtime never launches an
interactive login.
Combine with the runtime's own output flag by putting it first:
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
# the first admitted native gh mode
runtime command run gh repo list {org} --limit 100
These are escape hatches, not a default style. Prefer a curated operation when one exists — it is the stable contract.
Direct gh access is not binary-wide. Only gh.repo.list is admitted today;
secret, release, auth, extension and other gh modes remain
context-unsupported until separately reviewed. Run those directly outside
Runtime or use a curated REST/GraphQL operation when available.
api DELETE is denied by the compiled default 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.
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:
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:
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. No admitted Runtime operation exists yet; use gh directly outside Runtime |
| 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.
Operational examples on this site were verified against Runtime 0.9.8. After bootstrap, the version-exact files in Runtime Home win.