Create a GitHub App (single repository)

Last updated:

Why a dedicated App

Chorum uses a GitHub App for the DevOps integration. Each Chorum workspace owns its own App, and the App ID and private key live only in that workspace, encrypted. A GitHub App has one webhook URL, so a separate workspace (for example the Chorum.io platform) needs its own App pointed at that workspace's webhook. This guide creates an App and scopes it to a single repository, which is the tightest useful setup.

Step 1: Create the App

  1. Sign in to GitHub as an owner of the organisation.
  2. Go to the organisation's Settings, Developer settings, GitHub Apps and choose New GitHub App.
  3. Set a GitHub App name, for example "Chorum DevOps".
  4. Set the Homepage URL to your Chorum address, for example https://chorum.io.

Step 2: Webhook

  1. Tick Active.
  2. Set the Webhook URL to your workspace's endpoint: https://YOUR-WORKSPACE/api/helpdesk/devops/webhook (for a customer this is your tenant address, for example https://acme.chorum.io/api/helpdesk/devops/webhook).
  3. Set a Secret: generate a long random string and keep a copy, because you enter the same value in Chorum.

Step 3: Permissions

Under Repository permissions:

  • Metadata: Read-only (this is mandatory).
  • Issues: Read and write.
  • Pull requests: Read and write.
  • Contents: Read-only.
  • Actions: Read and write (needed to trigger workflows).
  • Deployments: Read-only (optional, powers the Hub deployments list).

Under Organization permissions:

  • Projects: Read and write. This is required for GitHub Project board sync and is a separate setting from Repository, Projects.

Step 4: Subscribe to events

Under Subscribe to events, tick:

  • Issues
  • Pull request
  • Projects v2 (board created, edited or deleted)
  • Projects v2 item (cards added, moved or edited)

Step 5: Finish and collect the credentials

  1. For Where can this GitHub App be installed? choose Only on this account.
  2. Select Create GitHub App.
  3. Note the App ID shown at the top of the page.
  4. Scroll to Private keys and choose Generate a private key. A .pem file downloads. Keep it safe, because GitHub will not show it again.

Step 6: Install on a single repository

  1. Open the App's Install App tab and choose Install next to your organisation.
  2. Select Only select repositories.
  3. Pick the one repository you want Chorum to access, and confirm.

Choosing "Only select repositories" is what limits the App to a single repository. You can add or change the selected repository later from the same screen.

Step 7: Enter the credentials in Chorum

  1. Go to Helpdesk, DevOps, Settings.
  2. Under GitHub App credentials, enter the App ID, paste the contents of the .pem private key, and enter the webhook secret from Step 2, then save.
  3. Choose the installed organisation, add the repository, and set its switches.

Changing permissions later

If you add a permission or event to the App after installing, GitHub asks the organisation to accept the update, and an existing access token keeps its old permissions for up to an hour. After you accept, use Refresh connection on the Chorum settings card so the new permissions take effect immediately.