Skip to content

Connect GitHub

Version boundary

This page describes the pre-0.12 authentication contract. See Governed authority for v0.12.0 sources, separate ENGRT session, raw gh compatibility change and proof model. The candidate local/CI/GKE GitHub setup guide provides practical instructions for v0.12.0 and later.

Runtime v0.9.9 keeps GitHub identity independent from GCP and Kubernetes in the same process. HTTP credentials use an internal single-use request binding; native gh retains its reviewed contract. This does not make an Actions job token a supported /user credential, or make CI environment hints authentication.

Goal: authenticate the runtime against GitHub so engrt github operations work.

The github authentication service reads a configured user token (a personal access token or user OAuth token) from an environment variable and validates it against GET <base_url>/user.

One token serves everything — the github Runtime Provider's REST, GraphQL and CLI operations, plus engrt command run gh.

v0.9.9 credential contract

Classic/fine-grained PATs, OAuth user tokens and GitHub App user tokens require successful /user proof. Installation/Actions job tokens (ghs_, including variable-length formats), App refresh tokens and App JWTs are unsupported on this brokered user path and refuse before HTTP. A native gh session is a separate path; it reports readiness without a principal.

Prerequisites

Must be true Check
The runtime is installed engrt version prints a version
Runtime is installed engrt version (prepares Runtime Home automatically)

Inputs

Input Example Notes
A GitHub personal access token ghp_… Scopes below. Classic or fine-grained both work

Setup

1. Create a token

Create a personal access token — classic or fine-grained.

2. Export it

# add to ~/.zshrc or ~/.bashrc so it persists
export ENGRT_GITHUB_TOKEN=ghp_your_token_here
env:
  ENGRT_GITHUB_TOKEN: ${{ secrets.ENGRT_GITHUB_TOKEN }}

3. Verify

engrt auth login github
engrt auth status
engrt github user get

Expected output

With no token and no ENGRT session (fresh Home, v0.13.0):

github     ✗ auth_unavailable: github authentication: no ENGRT session; use explicit auth login github

To inspect proof without displaying a subject or token fingerprint, use jq (jq --version checks that it is installed):

engrt --output json auth login github | jq '{provider, proof, credential_class, credential_source}'

Captured from the released v0.9.9 binary, read-only, with an existing OAuth user token:

{
  "provider": "github",
  "proof": "principal_verified",
  "credential_class": "oauth_user_token",
  "credential_source": "runtime_token_environment"
}

A PAT reports its own class instead. This verifies identity, not permission to access every repository or perform a later write.

Common failures

Code or status Cause Fix
auth_unavailable No source is available: no ENGRT session and no token in the configured variable Export a supported user token in the shell/CI environment executing Runtime, or engrt auth login github on a local desktop
auth_store_unavailable The OS secure store is absent or locked (headless Linux, containers, CI) Unlock it, or use a store-free source: ENGRT_GITHUB_TOKEN (source: env), a token file (source: file, also a Kubernetes secret volume) or source: github_app
auth_surface_mismatch An OS-store session was selected on a CI or pod surface (local_session_unavailable_on_surface) Use env, file, github_actions or github_app on that surface
auth_invalid_credential GitHub identity probe returned 401 Check expiry, revocation, token value and trusted endpoint
auth_unsupported_credential Installation/job, refresh or JWT credential supplied to the user-token path Use a supported user token or a separately supported native CLI path; Runtime performs no exchange
auth_malformed_proof Identity response is malformed, incomplete or excessive Check the API endpoint/proxy; do not interpret this as a successful login
403 on an org resource Resource authorization or SSO restrictions See Scopes; identity proof does not grant access

Scopes

Scope requirements come from GitHub, not from the runtime. What you need depends on the operations you intend to run:

Doing this Typically needs
user get, org list, notification list read:user
repo list, repo view, repo summary on public repos no scope, or public_repo
Anything against private repositories repo
repo create repo (plus org permission)
team list, org member and collaborator reads read:org
workflow list / workflow run / run view repo + workflow
Reading org security alerts security_events, and GitHub Advanced Security enabled on the org

Give the token the narrowest set that covers your actual usage. Governance in the runtime is a second layer, not a substitute — a token that cannot do something is the strongest control available.

A 403 on org security endpoints is usually not a scope problem

It generally means GitHub Advanced Security is not enabled for that organization.

Native gh sessions and brokered tokens

The GitHub provider's CLI-backed operations receive the configured, already-validated token in all four slots: GH_TOKEN, GITHUB_TOKEN, GH_ENTERPRISE_TOKEN and GITHUB_ENTERPRISE_TOKEN, with the inspected host bound to GH_HOST.

The direct gh.repo.list mode also supports the way gh repo list already works on your machine. If the configured Runtime token is absent, Runtime runs gh auth status to validate the native session, then gh reads its existing home, config directory, host, and credential store. Runtime does not read or copy the native token.

The native probe receives the prepared executable, narrowed environment and selected host. Its result is credential_ready, not principal_verified, and cannot satisfy a principal allow-list. Runtime does not parse an invented native-gh-session identity out of an exit code.

engrt command run gh repo list --limit 5

Runtime never starts gh auth login during execution. Use gh auth login yourself only to establish a native session, or export ENGRT_GITHUB_TOKEN for the brokered path. Other direct gh modes remain context-unsupported until separately admitted.

Renaming the token variable

config.yaml stores the name of the variable, not the token:

authentication:
  github:
    token_env: ENGRT_GITHUB_TOKEN

If a pipeline already exports a differently named token, point at it instead of duplicating the secret:

export ENGRT_AUTHENTICATION_GITHUB_TOKEN_ENV=MY_EXISTING_PAT
export MY_EXISTING_PAT=ghp_xxx
engrt auth status

GitHub Enterprise Server

authentication:
  github:
    enabled: true
    base_url: https://ghe.example.com/api/v3
    token_env: ENGRT_GITHUB_TOKEN

Or without editing the file:

export ENGRT_AUTHENTICATION_GITHUB_BASE_URL=https://ghe.example.com/api/v3
export ENGRT_GITHUB_TOKEN=ghp_xxx
engrt auth status

In v0.9.9, the provider sends REST and identity checks under /api/v3 and GraphQL to /api/graphql. The configured base must use HTTPS, have no userinfo/query/fragment, and belong to the trusted GitHub instance. HTTP is accepted only for literal loopback/localhost fixtures. Request paths cannot change scheme, hostname or effective port.

All redirects are refused, including same-origin redirects; credentials and mutation bodies are never replayed at the Location target. Verify and configure the final trusted endpoint yourself. TLS verification uses the platform/Go trust store and the standard proxy environment; there is no insecure-TLS flag.

The /user identity response must be HTTP 200 with a usable nonempty login. The auth check shares the HTTP security boundary, with 10 seconds total, 64 KiB decoded response, and earlier caller cancellation. {}, malformed JSON, excessive output and redirected login pages do not establish identity. This validates a user credential, not every GitHub App credential class or every resource permission. See HTTP result limits.

Logout

engrt auth logout github

There is no server-side session to end for a personal access token, so this prints guidance rather than revoking anything. To genuinely revoke, delete the token in GitHub's settings and unset the variable:

unset ENGRT_GITHUB_TOKEN

The logout attempt is still audited.

Troubleshooting

Symptom Cause
auth status shows github failing ENGRT_GITHUB_TOKEN unset in this shell, or the token is expired/revoked
Works in one terminal, not another The export was not added to a shell profile
401 against a GHE host base_url still points at api.github.com, or the token is from the wrong instance
404 on a repo you can see in the browser Token lacks repo scope for private repositories
gh sub-operations fail but REST ones work gh is not installed — check engrt config validate

More: Troubleshooting.

Next

Run Your First Capability

Native identity and narrowed environment (v0.9.9)

For the reviewed native gh mode, removing the selected credential refuses before native auth or operation launch. Public GitHub and ghe.com tenants select GH_TOKEN then GITHUB_TOKEN; other enterprise hosts select GH_ENTERPRISE_TOKEN then GITHUB_ENTERPRISE_TOKEN. Policy cannot silently replace an excluded token with a lower-priority token or stored login. The selected GH_CONFIG_DIR, then XDG_CONFIG_HOME, must also survive narrowing; native OS home/AppData defaults remain available under the gh contract. GH_HOST remains bound to the inspected target. Explicit brokered auth still replaces all four credential slots with its validated token.

Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.