Connect GitHub¶

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

The github Auth Engine provider is a REST provider: it reads a personal access 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 runtime command run gh.

Prerequisites¶

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

Inputs¶

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

Expected output¶

Before you export a token, the runtime tells you exactly what is missing:

github     ✗ no token found in $RUNTIME_GITHUB_TOKEN; export it (e.g. in ~/.zshrc: export RUNTIME_GITHUB_TOKEN=ghp_xxx) and open a new shell

After exporting it, runtime auth status reports the authenticated subject and a masked token — the runtime never prints a token in full:

github     ✓ subject=<your-login> token=ghp_...XXXX

Common failures¶

Symptom	Cause	Fix
`✗ no token found in $RUNTIME_GITHUB_TOKEN`	The variable is unset in this shell	Export it and open a new shell — a token exported in another terminal is not visible here
`401 Bad credentials`	Token revoked, expired, or mistyped	Issue a new token and re-export
`403` on an org resource	Token lacks the scope, or SSO is not authorised for the org	See Scopes; authorise the token for the org in GitHub

Setup¶

1. Create a token¶

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

2. Export it¶

macOS / LinuxWindows (PowerShell)CI

# add to ~/.zshrc or ~/.bashrc so it persists
export RUNTIME_GITHUB_TOKEN=ghp_your_token_here

setx RUNTIME_GITHUB_TOKEN "ghp_your_token_here"

env:
  RUNTIME_GITHUB_TOKEN: ${{ secrets.RUNTIME_GITHUB_TOKEN }}

3. Verify¶

runtime auth login github
runtime auth status
runtime github user get

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 as GH_TOKEN and GITHUB_TOKEN.

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.

runtime 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 RUNTIME_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: RUNTIME_GITHUB_TOKEN

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

export RUNTIME_AUTHENTICATION_GITHUB_TOKEN_ENV=MY_EXISTING_PAT
export MY_EXISTING_PAT=ghp_xxx
runtime auth status

GitHub Enterprise Server¶

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

Or without editing the file:

export RUNTIME_AUTHENTICATION_GITHUB_BASE_URL=https://ghe.example.com/api/v3
export RUNTIME_GITHUB_TOKEN=ghp_xxx
runtime auth status

The REST and GraphQL Engines verify that every assembled URL still points at the configured base URL's scheme and host. A crafted path cannot redirect your bearer token to another host.

Logout¶

runtime 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 RUNTIME_GITHUB_TOKEN

The logout attempt is still audited.

Troubleshooting¶

Symptom	Cause
`auth status` shows github failing	`RUNTIME_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 `runtime config validate`

More: Troubleshooting.

Next¶

Run Your First Capability

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