Skip to content

GitHub Authentication

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.

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 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.

gh auth login is never needed

When the Command Engine runs gh, the runtime forwards the already validated token as GH_TOKEN and GITHUB_TOKEN. That covers both runtime command run gh … and the github provider's CLI-backed operations (pr list, workflow run, run view, …).

runtime command run gh repo list --limit 5      # works with no gh auth login

GH_TOKEN and GITHUB_TOKEN are therefore outputs of the runtime, not inputs to it. Export RUNTIME_GITHUB_TOKEN.

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.