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¶
3. Verify¶
Expected output¶
With no token and no ENGRT session (fresh Home, v0.13.0):
To inspect proof without displaying a subject or token fingerprint, use jq
(jq --version checks that it is installed):
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.
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:
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¶
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:
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¶
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.