Set up GitHub integration

This guide covers the GitHub-specific parts of the setup. GitHub is one of three supported code hosts — see Connect a code host for connecting GitLab or Bitbucket, and for how a workspace mixes them.

Prerequisites

A GitHub account with access to the repos you want to work on
Either a GitHub App registered for your server (see Create the GitHub App) so you can sign in, or a personal access token with repo and read:org to paste

A device flow: GitHub shows you a short code, you approve it on github.com, and the server receives the credential — no callback URL, no port, nothing to expose. Available whenever the server has a client id, which an official build already ships.

Go to Settings → You → Profile & identity → Code hosting (or the first step of onboarding)
On the GitHub row, click Sign in with GitHub
A dialog shows an eight-character code and opens github.com/login/device in your browser. The code is already on your clipboard
Paste it, approve the app, and come back. The row flips to “Signed in as your-username” on its own

The dialog can be closed while you finish in the browser — the server keeps polling until the code expires (about 15 minutes), so the sign-in still lands.

Or paste a token

The fallback when the server has no app, when the app is not installed on an account you need, or when you would simply rather use a PAT.

Go to Settings → You → Profile & identity → Code hosting
On the GitHub row, click Add token
Paste a token with repo and read:org and save

The token is probed as it is stored, so the row can name the account it belongs to. Click Disconnect to remove it.

Checkpoint: the GitHub row reads “Signed in as your-username”. A suffix names the source when the credential answering is not yours — “via this server’s app” or “from the environment”.

What the integration gives you

Feature	How
PR list and detail	The GitHub REST API, from the server, on the app identity or your own credential
Check runs	The GitHub Checks API
Review publishing	A user-gated step that posts your review to the PR
Repo registration	A checkout is accepted if its `origin` remote points at github.com — or at gitlab.com / bitbucket.org
Agent GitHub access	The credential broker injects the token as `GH_TOKEN` / `GITHUB_TOKEN`, gated by the agent’s capabilities
Notification pings	A server-side poll of your GitHub notification inbox raises “mentioned in pull request” and “review requested”
User profiles	Profile hover cards and per-author PR filtering

Some paths use the GraphQL API instead of REST where it is cheaper — branch activity for the compose-PR picker and the live review state that decides whether a review-requested notification is still pending.

Watch for GitHub outages

The title bar shows a status chip when a provider is degraded, covering GitHub, Claude, OpenAI and Kimi. It is hidden while everything is healthy — presence reports trouble, not its absence.

Click the chip to open a flyout with each provider’s state and a refresh button. The statuses refresh on their own every two minutes.

Know how agents act on GitHub

An agent gets a GitHub token only if it has Allow GitHub API calls or Allow git push. See Configure sandbox policies
Commits an agent makes are authored as the agent — the display name plus (agent), at a synthetic address keyed by the agent’s id — never as a human. The person who asked is credited with a Co-Authored-By trailer
With a GitHub App configured, the broker mints fine-grained, repo-scoped, roughly one-hour installation tokens per launch instead of handing over a broad token. The installation is resolved from the run’s repo owner, so one app installed on several accounts scopes correctly to whichever one the run touches. Without an app, agents receive the environment token
A run requested by a member who has signed in acts under that member’s GitHub identity — their credential is merged in after the broker’s environment, so a commit or comment an agent makes for them is attributable to them

Troubleshooting

The PR list is empty and says GitHub is not connected

You have no GitHub credential on this server. Sign in or paste a token under Code hosting. Repos on other forges are unaffected — only GitHub’s contribute nothing.

The server has no client id — which is the normal state for a build from source, since credentials are only baked into official builds. See Create the GitHub App: it takes about two minutes and only the server owner has to do it, once.

The GitHub App exists but its Device flow checkbox is off. Turn it on in the app’s settings (General → Device flow) and try again.

The row says “via this server’s app” when I expected my own account

You have not signed in; what you are seeing is the server’s app identity answering. Click Sign in with GitHub on that row.

Adding a repo is rejected

Registration requires all three: the path is inside a git work tree, it has an origin remote, and that remote points at a supported forge (github.com, gitlab.com or bitbucket.org). See Add repos to a workspace.

Everything stops working for a while after heavy use

That is the rate-limit circuit breaker. GitHub signals its primary limit with a 403 carrying x-ratelimit-remaining: 0 and a reset time; on seeing one, the client fails further requests locally without a network call until the window elapses, so a retry storm cannot deepen the limit. Transient failures are retried up to three times with exponential backoff, honouring retry-after.