Skip to content

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.

engrt github <operation> [args...]

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

engrt 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 <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:

engrt --output json github pr list --repo cli/cli --json number,title

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.

engrt 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 ~/.engrt/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:

engrt github repo list
engrt github repo list acme per_page=100 sort=pushed direction=desc
engrt github repo summary cli/cli
engrt github api GET /repos/{owner}/{repo}/community/profile
engrt github team list acme
engrt github api GET /orgs/{org}/members role=admin per_page=100
engrt github api GET /orgs/{org}/outside_collaborators per_page=100
engrt github api GET /orgs/{org}/invitations
engrt github workflow list --repo acme/thing
engrt github run list --repo acme/thing --limit 20 --status failure
engrt github run view 1234567890 --repo acme/thing --log-failed
engrt github api POST /repos/{owner}/{repo}/actions/runs/{run_id}/rerun-failed-jobs
engrt github api GET /orgs/{org}/dependabot/alerts state=open severity=critical
engrt github api GET /orgs/{org}/code-scanning/alerts state=open
engrt 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. 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.