github Provider¶
Released v0.14.0
GitHub, native-command and audit changes, recovery guidance and qualification limits are described in the v0.14.0 operations guide.
Auth provider: github — one token
(ENGRT_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 <org> [key=value...] |
rest |
issue create |
cli (gh) |
org list |
rest |
team list <org> |
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 \| key:=<json>...] |
rest |
graphql <query> [key=value \| key:=<json>...] |
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
engrt github --help — it describes the binary you have installed.
Observation reads (v0.11.0)¶
v0.11.0 adds three curated REST reads and an
observation mapping for repo view:
| Operation | Transport | Typical outputs |
|---|---|---|
file get <owner>/<repo> <path> [ref=<branch-or-sha>] |
rest | /sha, /size |
label get <owner>/<repo> <name> |
rest | /color, /description |
release get <owner>/<repo> <tag> |
rest | /tag_name, /prerelease |
Inside a result-grammar capability,
an authoritative 404 from these reads, or from repo view, is the ABSENT
observation, and the step succeeds. Outside such a capability, and in
api/graphql, a 404 stays http_not_found. Authentication, permission,
rate-limit and server failures are never treated as absence.
GraphQL policy classification (v0.9.9)¶
Runtime parses exactly one query or mutation before authentication or POST.
Policy uses graphql query or graphql mutation plus variable arguments,
instead of raw query-text prefixes. Whitespace, comments, named operations and
fragments cannot hide a mutation; shorthand { ... } is a query. Multiple
operations, subscriptions, invalid syntax and the 1 MiB / 10,000-token limits
fail closed. This classification does not validate provider schema or authorize
individual fields. Pass input data as GraphQL variables, not source interpolation.
Direct engrt github graphql and capability steps selecting graphql share
this classifier. Generic github api is REST-only and refuses GraphQL endpoints
before authentication or dispatch for every method, including trailing-slash,
query-string and normalized aliases. Use the dedicated operation for queries
as well as mutations. The fixed read repo summary retains its own policy
operation. Migrate all raw query-text prefix rules to graphql query /
graphql mutation; old content-specific deny prefixes no longer match.
Destructive effects are refused on every transport (v0.13.0)¶
compiled-safety-profile/v4 refuses these whatever the policy says — including an
explicit allow — before authentication or dispatch, on direct, capability and MCP
paths (Refusal: compiled_safety (destructive-effect)):
| Transport | Refused |
|---|---|
REST (github api) |
DELETE /repos/{owner}/{repo}; DELETE …/git/refs/…; PATCH/POST …/git/refs/… with force true (plain or force:=true); DELETE …/branches/{branch}/protection and its parts; DELETE …/rulesets/{id} and /orgs/{org}/rulesets/{id} |
GraphQL (github graphql) |
deleteRef, deleteBranchProtectionRule, deleteRepositoryRuleset; updateRef/updateRefs whose force is true or cannot be resolved — through aliases, inline fragments, fragment spreads and variables |
| Native CLI | git force pushes, ref deletion and history rewriting; raw gh repo delete and destructive gh api (see command run) |
Creating a ruleset or branch protection is ordinary policy; removing one is
refused, because removing a protection opens the destructive paths above. Remove
it deliberately in GitHub if that is really intended. Other delete* operations
(issues, comments, labels, packages, …) remain under ordinary policy. The catalog
is finite; it is not a sandbox.
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 |
key:=<json> |
(v0.13.0) One JSON value — object, array, number, boolean, null or string — as a POST/PUT/PATCH body field or a GraphQL variable. Use it for nested request shapes such as rulesets. Refused in query strings; a key may appear only once; depth ≤ 32; body ≤ 1 MiB |
{org} |
Supply the organization explicitly; there is no Runtime Context substitution |
{owner}, {repo}, {branch} |
Literal placeholders — substitute them yourself |
Nested request bodies (v0.13.0)¶
Plain key=value fields can only carry strings, numbers and booleans. Some
endpoints need nested objects or arrays — a repository ruleset is one. Pass
those with the typed form key:=<json>; quote the JSON for your shell:
engrt github api POST /repos/<owner>/<repo>/rulesets \
name=protect-qualification target=branch enforcement=active \
'conditions:={"ref_name":{"include":["refs/heads/engrt-qual/**"],"exclude":[]}}' \
'rules:=[{"type":"deletion"},{"type":"non_fast_forward"}]'
The value is decoded strictly: exactly one JSON value, no repeated object keys,
and invalid input is refused before anything is sent. Errors name the
field, never its value. GraphQL variables accept the same form — plain
variables stay strings, input:={…} passes an input object.
The organization is always an argument. GitHub has no native context for Runtime to observe, so nothing supplies one on your behalf.
engrt github repo list # your own repositories
engrt github repo list acme # the organization's
engrt github issue list acme # required here
engrt 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 CLI 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
engrt github repo view <owner>/<repo> uses a concise human projection:
repository, visibility, default branch, language, open issues, archived status
and URL. Provider-returned sensitive fields, including temp_clone_token, are
sanitized before either CLI or JSON rendering; JSON retains useful safe fields.
The descriptor uses the generic renderer and cannot exceed its field, row,
label or byte limits. Omitted/truncated projections include JSON guidance.
Use engrt --output json github repo list when automation needs the complete
typed API objects.
HTTP results and limits — v0.9.9 hardening¶
This section describes the v0.9.9 HTTP contract.
Malformed HTTP requests are validated before authentication, so an invalid
method, path or field list does not first validate your token. The same checks
make capability planning report a refused step with all_allowed: false.
HTTP validation retains http_request_invalid and before-dispatch observations;
valid request translation is unchanged.
Provider REST and GraphQL requests have a 20-second total deadline and a 1 MiB decoded success-body limit; HTTP error/redirect bodies are limited to 64 KiB. Earlier caller cancellation also applies. Gzip expansion counts toward the decoded limit. Oversized/incomplete bodies are withheld, not returned as successful truncated JSON.
No redirects are followed, even to the same origin, and no request is automatically retried. Verify and configure a moved endpoint explicitly. Production endpoints require HTTPS; HTTP is limited to loopback test services. See Enterprise endpoint configuration.
With --output json, inspect the top-level status and error_code together
with .data, .result.execution and .result.http:
| Field or response | Meaning |
|---|---|
result.http.status_code |
Received HTTP status; 0 if no response was received |
result.http.request_id |
Bounded sanitized GitHub request ID when present |
result.http.retry_after |
Validated seconds/date hint, not an automatic retry |
result.http.pagination |
more_available for a recognized next-page Link; otherwise not_evaluated, never a completeness guarantee |
REST JSON null |
Present as data: null |
| HEAD / 204 / 205 | no_content: true; data omitted |
GraphQL data + errors |
Safe partial data retained, graphql_errors, unsuccessful status and exit 1—even for HTTP 200 |
| Empty/malformed/text success | http_invalid_json; body withheld |
| HTTP 401 / 403 / 404 / 429 / 5xx | http_unauthorized / http_forbidden / http_not_found / http_rate_limited / http_server_error |
Use GraphQL pageInfo/cursors for connection completeness. One page and a
successful HTTP request do not establish a complete inventory. A failed request
after transmission has unknown effects; inspect the target before deciding to
retry. The shared execution-result guidance
explains the CLI contract.
Results redact recognizable credential formats, the granted token if echoed,
and named sensitive JSON fields such as tokens, passwords, private keys and
cookies. Safe structure is preserved; legitimate token-shaped data may also be
redacted. This is defense in depth, not universal detection of arbitrary secrets.
App installation-token creation and runner registration/removal/JIT credential
endpoints are refused before authentication/dispatch, including via api.
Redirect refusal, strict JSON admission and credential redaction are intentional compatibility corrections. Do not depend on raw failed-response text or parse human-readable messages as an API.
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.
engrt github file put owner/repo caps/note.md \
message="Add note" content="hello"
# update: fetch the blob sha, then compare-and-set
engrt github api GET /repos/owner/repo/contents/caps/note.md
engrt 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 — explicit targets in v0.9.9¶
This contract requires an explicit repository for all eight curated CLI operations. They share the direct Command Engine's preparation and floor; the provider cannot bypass native target or executable checks.
engrt github pr list --repo cli/cli --state open --limit 100
engrt github pr list --repo cli/cli --json number,title,author,reviewDecision
engrt github run view 1234567890 --repo owner/repo --log-failed
Supply exactly one --repo/-R as [HOST/]OWNER/REPO; any host must match the
configured credential host. A pr view URL is also accepted when its host and
repository agree; Runtime normalizes it to repository/number before binary
policy. Other admitted arguments remain literal. Unknown flags and ambiguous or
missing targets refuse before credentials. Use the canonical host without www..
pr create additionally needs --head naming an already-pushed branch; --fill
variants, browser, editor and recovery modes are refused. Runtime executes in a
private directory, not your clone. Native CLI file inputs/helpers are not a
separate File Engine grant or hostile-code sandbox.
The configured, validated token replaces both public and Enterprise gh token
families. GH_HOST is fixed to the prepared host, retaining explicit ports;
ambient host/Enterprise-token changes cannot substitute for the verified
identity. These are synthetic conformance checks, not live Enterprise Server
certification. 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:
# ordinary REST operations, subject to policy and credential-export refusals
engrt github api GET /repos/cli/cli/community/profile
engrt github api PATCH /repos/{owner}/{repo} default_branch=main delete_branch_on_merge=true
engrt github api PUT /repos/{owner}/{repo}/topics 'names:=["service","go"]'
# any GraphQL query
engrt github graphql 'query($org:String!){ organization(login:$org){ repositories(first:100){ nodes{ nameWithOwner isPrivate } } } }' org=my-org
# the first admitted native gh mode
engrt 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 ordinary REST endpoints, 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
~/.engrt/specs/github/capability-spec-github.md for the
GitHub-specific contract.
Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.