Create the GitHub App

Your CIHub instance talks to GitHub through a GitHub App that you own. The App receives the webhooks of your repositories, gives CIHub the rights to test and merge pull requests, and signs people in to the dashboard. You create it once, on GitHub.

Before you startCopy Anchor Link

• The HTTPS address of your instance, reachable from GitHub, for example https://cihub.example.com. The examples below write it https://<your CIHub host>.
• Owner rights on the GitHub organization that will own the App.

Create the AppCopy Anchor Link

The App has three addresses on your instance. Most mistakes come from mixing them up:

Generate the webhook secret first:

openssl rand -hex 32

Open the formCopy Anchor Link

• For an organization: your profile picture → Your organizations → Settings next to the organization → Developer settings → GitHub Apps → New GitHub App.
• For a personal account: your profile picture → Settings → Developer settings → GitHub Apps → New GitHub App.

On a GitHub Enterprise Server, the path is the same on your server.

Fill in the identity and the sign-inCopy Anchor Link

Fill in the webhookCopy Anchor Link

Set the permissionsCopy Anchor Link

Under Repository permissions:

Under Organization permissions: Members, Read-only, to give each person the role that they have on GitHub.

Leave every other permission at No access.

Subscribe to the eventsCopy Anchor Link

Under Subscribe to events, check:

• Branch protection rule
• Check run
• Check suite
• Issue comment
• Pull request
• Pull request review
• Push
• Repository
• Status
• Workflow job

GitHub sends the events of the installation itself without a subscription.

Keep the App privateCopy Anchor Link

Under Where can this GitHub App be installed?, choose Only on this account, then Create GitHub App.

Any account that installs your App gets an organization in your CIHub: a public App would let anyone use your instance.

Collect the keys of the AppCopy Anchor Link

On the page of the new App (General):

1. Note the App ID and the Client ID.
2. Under Client secrets, Generate a new client secret, and copy it: GitHub shows it once.
3. Under Private keys, Generate a private key: your browser downloads a .pem file.

Keep the private key, the client secret and the webhook secret in your secret store. The private key and the client secret act as the App: whoever has them can act on every repository where the App is installed.

Give the keys to CIHubCopy Anchor Link

You now have five values: the App ID, the private key, the webhook secret, the Client ID and the client secret. Give them to CIHub as Run CIHub with Docker or Run CIHub on Kubernetes shows, then come back here to install the App.

The Client ID and the client secret turn on the sign-in to the dashboard, with the public address (CIHUB_HTTP_PUBLIC_URL) and a sealing key (CIHUB_DATABASE_SECRET, at least 32 bytes, which seals the GitHub tokens of the people who sign in). Without them, only the API tokens work. cihub-server start stops at startup and names the value that is missing.

Install the App on your repositoriesCopy Anchor Link

On the page of the App: Install App → your organization → Only select repositories (or All repositories) → Install.

GitHub then sends you to the Setup URL: sign in to the dashboard, and it opens the repositories of the new organization. You create nothing else: CIHub creates the organization, named after the login of the account, and the first /cihub merge on a branch creates its queue. To add or remove repositories later, change the installation on GitHub (Settings → GitHub Apps → Configure in the organization); CIHub reads the change.

Check that GitHub reaches CIHubCopy Anchor Link

1. On the page of the App: Advanced → Recent Deliveries. The installation delivery has a green mark: CIHub answered it.
2. The dashboard lists the repositories that you selected.
3. A comment /cihub merge on an approved, green pull request gets a 👍 reaction, then the comment of CIHub.

Change the permissions laterCopy Anchor Link

When a new version of CIHub needs a new permission or event, change it on the page of the App. GitHub then asks an owner of each organization to accept the new permissions (Settings → GitHub Apps in the organization): until they do, the installation keeps the old ones.

From the release after 0.3.0, the App needs Actions, Read-only, and the Workflow job event: without them, a check of GitHub Actions shows queued until it ends, never running. On an older App, add them on the page of the App, then accept them in each organization.