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

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

| 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

When you paste a token, the hub calls GitHub right away to confirm it works and carries the scopes it needs. A bad or under-scoped token is rejected at entry, not silently later.

The hub stores the token encrypted (AES-256-GCM) and never echoes it back in the UI or logs. One token can manage many organizations, so orgs under the same account share a single token.

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.