Skip to content

Create the GitHub App

This guide shows you how to give your server its own GitHub App. It takes about two minutes, only the server owner does it, and it only has to happen once per server.

For signing in to your own account afterwards, see Set up GitHub integration.

One registration answers two different jobs:

Job What answers it Why it matters
A person signs in The app’s client id and client secret Everyone gets a GitHub credential of their own, on the server, on every device
The server acts The app’s id and private key Agents, pipelines, pollers and bot replies get tokens for one repository at a time

The second job never borrows a person’s credential wholesale. Each token the server mints covers one repository and is limited to what an accountable member can do there. Reading a linked repository needs only the app; anything that writes needs a member who can push. Automation never approves a pull request.

The server’s own app applies only under Use my own apps. With Control Center’s or a custom Connect, Connect runs every lane, GitHub included; the server’s app stays saved but unused until you switch back. A workspace on its own apps (Give one workspace its own app) uses its own App instead, whatever the server’s mode. An app with some of its fields missing is an error, not a fall back: GitHub sign-ins are refused until every field is set.

  • You are the server owner. The Provider apps card is invisible to everyone else
  • A GitHub account. The app is created under it
  • A server address your browser can reach. The server’s public URL (or loopback, for a desktop’s own server) is where GitHub sends you back
  1. Go to Settings → Server → Single sign-on and scroll to the Provider apps card
  2. On the GitHub block, optionally type the GitHub organisation that should own the app in Organisation (optional). Leave it empty to create the app under your own account; creating it under an organisation takes an owner of that organisation
  3. Click Create my GitHub App
  4. Your browser opens GitHub with the app already filled in. Click Create GitHub App
  5. GitHub sends you back to the server, which stores the app id, private key, client id and client secret, then opens the app’s install page

Nothing is copied by hand, and the conversion code goes straight from GitHub to your server. The link works once and expires after ten minutes; if it expires, click Create my GitHub App again.

The app is named Control Center <code> and asks for exactly what Control Center uses:

Permission Access
Metadata Read
Contents Read and write
Pull requests Read and write
Issues Read and write
Checks, Actions, Commit statuses Read
Organisation members Read

Webhooks are off: the server polls. To move an app you created under your own account to an organisation later, use Transfer ownership in the app’s advanced settings on GitHub.

Checkpoint: the GitHub block reads “The server can act as itself, and people can sign in”.

An app that is registered but not installed can sign people in and read nothing.

  1. Pick the account or organisation that owns your repositories on the install page GitHub opened
  2. Choose All repositories, or select the ones this server should see

To install it on another account later, a workspace admin goes to Settings → Workspace → Integrations, finds GitHub App installations on the GitHub App card under Code hosting and clicks Install GitHub App. The list shows every account the app is installed on and flags a suspended installation.

An organisation installs the GitHub App once. After that, anyone in it who signs in to GitHub on a Control Center server can use the installation, whichever server that is: yours, a colleague’s, or one of their own. There is nothing to authorise per server.

Every token a server gets is the signed-in person’s own, limited to one repository and to their role on it, so it never reaches further than they could on GitHub. GitHub’s audit log shows that person, acting through the app.

To stop Control Center reaching an organisation, an owner of the organisation removes the installation or narrows its repositories on GitHub. Removing a person from the organisation stops their access too.

The Provider apps card also takes the values directly, for an app you registered yourself:

Group Fields
Acting as the server App id, and Private key (the whole .pem, BEGIN and END lines included)
Signing people in Client id and Client secret. Callback URLs shows the URL to register, verbatim
Pull request conversations Bot login, resolved when you test the connection

Register the callback URL <server origin>/oauth/github/callback exactly as the card shows it, leave Expire user authorization tokens on, and grant the permissions in the table above. Click Test: it asks GitHub which accounts the app is installed on, so “saved” and “works” are not confused.

For a headless or scripted install, the server seeds each field from its .env file the first time it has no stored value:

Terminal window
GITHUB_APP_ID=123456
GITHUB_CLIENT_ID=Iv23li0123456789abcd
GITHUB_CLIENT_SECRET=<secret>
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEow…\n-----END RSA PRIVATE KEY-----"

Put the key on one line: a .env value is one line, and \n inside double quotes decodes to a newline. The server refuses to start when GITHUB_APP_PRIVATE_KEY or GITHUB_CLIENT_SECRET is exported in its process environment, where every child process could read it; keep them in the .env file (in Docker, mount it at /app/bin/.env). Seeding happens once per field, so editing in Settings is not undone by the next restart.

A workspace can run on an app of its own instead of the server’s:

  1. A workspace admin goes to Settings → Workspace → Integrations
  2. On the Control Center Connect card, they choose Use my own apps and click Apply. Everyone in the workspace signs in again through the workspace’s apps
  3. The GitHub App card under Code hosting now holds the app’s fields: App id and Private key under Acting for this workspace, Client id and Client secret under Signing people in. Click Test once they are set

Members then sign in to that app for this workspace. A workspace on its own apps never falls back to the server’s app or to Connect: until its fields are complete, its GitHub work is refused. The same choice covers Google Calendar, Linear and GIF search, each with its own fields beside its provider on the same page. See Give one workspace its own Linear application and Give one workspace its own Google client. The other choices on that card, and what each one does, are in Per-workspace choice.

Create my GitHub App says the server has no address

Section titled “Create my GitHub App says the server has no address”

The server has no public URL a browser could return to. Set CC_SERVER_PUBLIC_URL (or --public-url) and try again.

The one-time page was already used, or ten minutes passed. Start again from Settings.

Test says the credentials work but the app is not installed anywhere

Section titled “Test says the credentials work but the app is not installed anywhere”

Registration and installation are separate steps. Open the app’s install page, or use Install GitHub App in Workspace → Integrations.

Test says the private key could not be read

Section titled “Test says the private key could not be read”

Paste the whole .pem file, including the -----BEGIN and -----END lines. An ed25519 or EC key cannot be used: GitHub Apps sign with RSA.

A member signed in but sees no repositories

Section titled “A member signed in but sees no repositories”

The app is not installed on the account that owns them, or its installation selects different repositories. A sign-in only grants what the app may see.

Agents say the GitHub App installation is suspended

Section titled “Agents say the GitHub App installation is suspended”

Someone suspended the installation on GitHub. Unsuspend it in the account’s Settings → Applications → Installed GitHub Apps.