Skip to content
runaway

GitHub Permissions

Runaway authenticates to GitHub with a classic personal access token (PAT). You create one token, paste it into the hub when you add an organization or personal account, and Runaway uses it to register and deregister runners on your behalf.

Required scopes

Section titled “Required scopes”

The scopes depend on whether the token manages an organization or a personal account.

| Account type | Scopes | What they enable | |---|---|---| | Organization | repo + admin:org | repo reads workflow runs and jobs to size each pool to real demand; admin:org registers and deregisters runners on the org. | | Personal account | repo | Reads runs and jobs, and registers and deregisters runners on your account. |

The token owner must be an active admin of any org it manages. Both organization-scope and personal-account-scope runners are supported with one token.

Optional scope for webhooks

Section titled “Optional scope for webhooks”

| Scope | What it enables | |---|---| | admin:org_hook | Lets Runaway create and manage the workflow_job webhook for an org. |

Add admin:org_hook only if you want the lower-latency webhook demand signal for an organization. Without it, that org stays on polling and the “Enable webhooks” control is disabled with a tooltip explaining the missing scope. See Webhooks for the full flow.

How the token is handled

Section titled “How the token is handled”
  • Validated live. When you paste a token, the hub calls GitHub immediately to confirm it works and has the scopes it needs. A bad or under-scoped token is rejected at the point of entry, not silently later.
  • Encrypted at rest. The token is stored encrypted in the database (AES-256-GCM) and is never echoed back in the UI or logs.
  • Shared across orgs. One token can manage many organizations, so you don’t need a separate token per org if they’re under the same account.

When a token expires or loses scope

Section titled “When a token expires or loses scope”

A PAT that expires or loses a required scope surfaces as warnings on the events page — look for github warnings there if runners stop appearing. Re-enter the token (or issue a fresh one) to clear the problem. Runaway never silently falls back to a broken token.