GitHub
A GitHub connection lets Merge Pilot follow the pull requests of GitHub repositories and gate them. It works with github.com and with GitHub Enterprise Server 3.12 or newer.
On GitHub, Merge Pilot works as a GitHub App. The merge gate is a repository ruleset that requires the check Merge Pilot / change approval, accepted only from the connection's App. Merge Pilot reports that check on each pull request's head commit:
| Check state | Title on GitHub | When |
|---|---|---|
| In progress | The first required control still pending and its reason, for example Change approval: …; Waiting for change management when no control is named | Change management is still deciding |
| Success | Approved by change management | The change is approved for this commit |
| Failure | The first enforced control that failed and its reason, for example Secret scan: …; Blocked by change management when no control is named | Change management refused it |
A pull request that was already open when its repository was put under change management gets a passing check titled Not gated: opened before change management: only new pull requests and new commits are gated. On a merge queue commit the check is Change approved or Change not approved.
A new push has no check yet, so the gate closes by itself until Merge Pilot decides on the new commit.
Connection fields
Open the company's Connections tab, choose Add VCS connection and pick GitHub as the Provider. The fields shared by every connection (Name, Deployment type, Active) are described in Connections. For GitHub, Deployment type offers github.com and GitHub Enterprise Server.
The section GitHub configuration has these fields:
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Enterprise Server URL | Address of the GitHub Enterprise Server. Shown for GitHub Enterprise Server only; a github.com connection always uses https://github.com | none, required for Enterprise Server | A full http(s):// URL that is not github.com | Company admin | github_config.web_url |
| Skip TLS verification | Accepts any certificate the server shows. Enterprise Server only, for servers with self-signed certificates | Off | On, off | Company admin | github_config.tls_skip_verify |
| Sign in with GitHub | People sign in to Merge Pilot and link their GitHub account through the App. See Sign in with GitHub | Off | On, off | Company admin | github_config.oauth_enabled |
The App's own credentials are filled in by the manifest flow after you save. The section Use an existing GitHub App is only for an App registered by hand; see Using an existing App.
With Skip TLS verification on, someone between Merge Pilot and the server could read the connection's credentials.
Create the GitHub App
After the connection is saved, its row on the Connections tab shows Create the GitHub App. GitHub creates the App with the permissions and webhook below in one step; you only confirm its name on GitHub.
Before you start:
- A platform admin must set the Application URL under Settings → General to an address GitHub can reach from the internet. GitHub sends the App's events there. Merge Pilot refuses to start when the Application URL is empty, is not a full
http(s)://address, or is a local address (localhost, a.localname, a name without a dot, or a loopback or private-network IP). - You need the right to create GitHub Apps on the account the App is created under.
The fields of Create the GitHub App:
| Setting (label in the UI) | What it does | Default | Allowed values |
|---|---|---|---|
| Organization | The organization the App is registered under | Empty: your personal GitHub account | A GitHub organization name (letters, digits and hyphens, at most 39 characters) |
| Let other organizations install it | Makes the App public. Without this, the App installs only on the account it is created under | Off | On, off |
Then choose Create GitHub App. Merge Pilot sends you to GitHub with the App's manifest:
| Manifest item | Value |
|---|---|
| Name | Merge Pilot <company slug> (you can change it on GitHub before confirming) |
| Homepage URL | The Frontend URL under Settings → General (else the Public URL, else the Application URL) |
| Webhook URL | <Application URL>/api/v1/webhooks/vcs/<company slug>/<connection id>, active |
| Redirect after registration | <Public URL>/api/v1/github/manifest/callback |
| User authorization callback | <Public URL>/api/v1/auth/github/callback |
| Setup URL | <Public URL>/api/v1/github/<connection id>/setup, also after updates |
| Request user authorization during installation | Off |
Public URL falls back to the Application URL when it is empty.
When you confirm on GitHub, Merge Pilot stores the App's ID, slug, name, owner, client ID, client secret, private key and webhook secret on the connection (the secrets are never shown) and returns you to the Connections tab. The registration link is valid for one hour and can be used once. A connection holds one App: to create another, remove the current one first.
Permissions the App asks for
| Permission (manifest key) | Access | Used for |
|---|---|---|
Checks (checks) | write | The change approval check on pull requests (the merge gate) |
Pull requests (pull_requests) | write | Reading pull requests, their reviews and commits; comments on pull requests |
Contents (contents) | read | Reading changes and files (policies, scanning) |
Metadata (metadata) | read | Reading repositories and collaborators' access (required by GitHub) |
Administration (administration) | write | The merge gate's ruleset; branch protection; joining and leaving repositories |
Actions (actions) | read | Pipeline results (workflow runs); listing environments |
Commit statuses (statuses) | read | Pipeline results (commit statuses) |
Secrets (secrets) | write | Repository secrets (the project page's Variables tab) |
Variables (actions_variables) | write | Repository variables (the Variables tab) |
Environments (environments) | write | Environment variables and secrets (the Variables tab). An installation made before this permission was asked for has to accept it on GitHub first (see Permission warnings) |
Secrets, organization (organization_secrets) | write | Organization secrets |
Variables, organization (organization_actions_variables) | write | Organization variables |
Email addresses (emails) | read | The person's verified email at sign-in (company email domains, matching people in the tracker) |
Merge queues (merge_queues) | read | The change approval check on merge queues |
The Used for column is what the connection's permission warnings name when a permission is missing or not accepted yet. A permission the App has beyond these (for example Members, which Apps created earlier asked for) is not reported; its owner may remove it in the App's settings on GitHub.
The App does what people ask Merge Pilot to do on their repositories (variables and secrets, adding, editing and deleting them; branch protection; joining; see Permissions) with these permissions. Editing a variable changes its value; editing a secret replaces it (an organization secret keeps its visibility and repositories); neither creates one that does not exist. People need no more GitHub rights than the minimum role the connection's rule for an operation names (for example Read to protect a branch): the App does the operation for them. Merge Pilot reads each person's role on the repository with the App; on a public repository only a collaborator (directly, through a team or the organization) counts as having access.
Events the App subscribes to
pull_request, pull_request_review, check_run, check_suite, workflow_run, workflow_job, status, repository, merge_group and push. GitHub always delivers installation and installation_repositories to Apps; Merge Pilot uses them to refresh the list of installations.
An App created before Merge Pilot asked for push events lacks push. The connection then shows a warning: changes pushed without a pull request are found only by the head check. Turn on the Push event in the App's settings on GitHub, then choose Refresh.
Install the App
Once the App exists, its panel on the connection shows the App's name and owner, and these actions:
| Action (label in the UI) | What it does |
|---|---|
| Install on GitHub (Install on another account once installed) | Opens GitHub's installation page for the App. Install it on the organizations whose repositories Merge Pilot should gate, for all or selected repositories |
| Refresh | Reads the App's installations, name, slug, owner, events and permissions from GitHub again, and each installation's accepted permissions |
| Remove (trash icon) | Remove the GitHub App from this connection: Merge Pilot forgets the App's keys and installations, and you can create a new App. The App itself stays on GitHub until its owner deletes it there |
After an installation, GitHub sends the browser back to Merge Pilot. When that browser is signed in as a company admin of the connection's company, the installations are read right away; otherwise choose Refresh. Installation events from GitHub also refresh the list.
Each installation is listed with its account (organization or personal account), all repositories or selected repositories, and Suspended when GitHub suspended it.
A private App installs only on its owner. If GitHub offers only the owner when installing, make the App public in its GitHub settings (Advanced), or remove it here and create it under the organization.
Permission warnings
The panel compares the App's permissions, and each installation's accepted permissions, with the table above. A level counts when it is at least the one asked for (read, then write, then admin). It warns in two cases:
| Warning | Why | What to do |
|---|---|---|
| The App lacks permissions Merge Pilot needs. with a list such as Administration (repository, write): the merge gate's ruleset, branch protection, … don't work. | The App itself does not have the permission, or has a lower level. Usual for an App registered by hand, or created before Merge Pilot asked for the permission | The App's owner adds it in the App's settings on GitHub (Permissions and events). Each installation then has to accept it (the next warning). Choose Refresh: GitHub does not report changes to the App's own permissions |
| <account> has not accepted the App's new permissions yet. Until its owner approves them on the installation's settings page, these don't work: followed by the permissions and features | The App has the permission, but this installation has not accepted it. GitHub asks the account's owner (an organization owner, or the user) to approve new permissions | The account's owner follows the warning's link to the installation's settings page on GitHub and accepts the new permissions. GitHub reports the acceptance to Merge Pilot and the warning disappears; if it stays, choose Refresh |
Until a permission is there and accepted, what needs it is refused with a message naming it, for example the GitHub App needs the "Environments" repository permission, and the Variables tab offers no environments and says why.
GitHub Enterprise Server
- Version 3.12 or newer is required; Test connection reports an older server.
- The API address is
<Enterprise Server URL>/api/v3. - The installation page is
<Enterprise Server URL>/github-apps/<app slug>/installations/new(on github.com:https://github.com/apps/<app slug>/installations/new). - The Enterprise Server must reach the Application URL to deliver the App's webhooks.
- Changing the Enterprise Server URL to another host requires entering the private key again.
Using an existing App
The section Use an existing GitHub App is only for an App registered by hand. Leave the fields empty to keep the stored values.
| Setting (label in the UI) | What it does | Allowed values | API field |
|---|---|---|---|
| App ID | The App's numeric ID | A number. Required together with a private key | github_config.app_id |
| App slug | The App's slug (the name in its URL) | Text | github_config.app_slug |
| Client ID | The App's client ID, for sign-in | Text | github_config.client_id |
| Client secret | The App's client secret, for sign-in | Text (write only; has_client_secret) | github_config.client_secret |
| Webhook secret | The secret the App signs its webhooks with | Text (write only; has_webhook_secret) | github_config.webhook_secret |
| Private key | The App's private key | A PEM key (-----BEGIN RSA PRIVATE KEY-----); a key that is not valid PEM is refused | github_config.private_key (write only; has_private_key) |
All six can be changed by a company admin. An App registered by hand must be set up on GitHub like the manifest above: the same permissions and events, the webhook URL <Application URL>/api/v1/webhooks/vcs/<company slug>/<connection id> (the connection's Copy webhook URL) with the same webhook secret, and the callback and setup URLs.
What Merge Pilot writes to each repository
When a repository is put under change management, Merge Pilot creates or updates one ruleset in it, named Merge Pilot change management:
| Step (label in the UI) | Required | Ruleset rule it adds | When change management is removed |
|---|---|---|---|
| Ruleset with Merge Pilot's required check | Yes | The ruleset itself, enforcement active, on the target branches (the default branch when no target branch pattern is set), less the excluded branches. Rule "Require status checks to pass": the check Merge Pilot / change approval from the connection's App, branches not required to be up to date | The ruleset is deleted |
| Require a pull request | No (on by default) | "Require a pull request before merging", with no reviews required by it | Deleted with the ruleset |
| Block force pushes | No (on by default) | "Block force pushes" | Deleted with the ruleset |
| Block branch deletion | No (on by default) | "Restrict deletions" | Deleted with the ruleset |
API keys of the steps: ruleset_check, require_pull_request, block_force_push, block_deletion. The defaults per connection are set under Change management setup.
- Bypass actors that an administrator added to the ruleset are kept, and the setup warns how many there are.
- When GitHub refuses the ruleset, the setup fails with the reason: rulesets on private repositories need GitHub Team (or Pro) or Enterprise; or the App lacks the Administration (write) permission, which an organization owner accepts on the installation (see Permission warnings).
- A watched repository gets nothing written: the App's webhook already delivers its events. Merge Pilot only checks that the App's installation reaches the repository (step Event delivery).
- Merge Pilot also reports gaps in the ruleset (when the company turns that check on under Direct changes): a missing or unenforced ruleset, a missing rule that was chosen, or bypass actors.
Branch protection rulesets
The repository page's Branches tab (see Project page → Branches) protects branches with rulesets of their own, separate from the change management one:
| Change management ruleset | Branch protection ruleset | |
|---|---|---|
| Name | Merge Pilot change management | Merge Pilot protected: <branch>, one per protected branch |
| Created by | Change management setup | Protect on the Branches tab |
| Branches | The target branches, less the excluded ones | That one branch |
| Rules | The required check, and the optional steps above | "Restrict deletions", "Block force pushes" and "Require a pull request before merging" (no reviews required by it) |
| Allow force push | Not changed | Removes "Block force pushes" from that ruleset |
| Removed by | Removing change management | Unprotect |
- Neither touches the other, nor rulesets made by others. The checks of change management ignore the branch protection rulesets.
- A branch protection ruleset that was changed on GitHub (other branches, not active, bypass allowed, or other rules) is shown as Changed on GitHub and left alone: Merge Pilot neither changes nor deletes it.
- Each ruleset protects one branch by its exact name: patterns (
*,?,[ ],{ }) are refused. - Rulesets add up on GitHub: when several target a branch, the strictest rule applies. A branch whose change management ruleset blocks force pushes keeps them blocked after Allow force push; Merge Pilot says so and names the ruleset. It also says so when the branch's classic branch protection blocks force pushes.
- GitHub allows at most 75 rulesets per repository in total: each branch Merge Pilot protects uses one, so does change management, and rulesets made by others count too. Merge Pilot refuses one more with this repository already has the maximum of 75 rulesets on GitHub.
- The same plan rule applies: on private repositories rulesets need GitHub Team (or Pro) or Enterprise.
Merge queue
When a repository uses GitHub's merge queue, Merge Pilot reports the Merge Pilot / change approval check on each merge group commit too. It passes only when change management approved the pull request at the commit it was queued with; otherwise it fails, so the queue never merges what change management did not approve. Watched repositories get no check.
Sign in with GitHub
With Sign in with GitHub on, people sign in to Merge Pilot through the App and link their GitHub account from My profile. People need a linked account to be assigned and decide change approvals.
- It needs the App's client ID and client secret: the manifest flow stores them; for an App registered by hand, enter them under Use an existing GitHub App.
- The App's user authorization callback must be
<Public URL>/api/v1/auth/github/callback. - The GitHub sign-in button appears only when the switch is on and both the client ID and the client secret are stored.
Linking records only which GitHub user the person is. Merge Pilot keeps no access in the person's name: everything it does on GitHub is done by the App. Unlink in My profile removes the account.
How webhooks are verified
GitHub signs every delivery with the App's webhook secret in the X-Hub-Signature-256 header (HMAC-SHA256 of the body). Merge Pilot checks the signature and ignores the delivery when it is missing, malformed or wrong, or when the connection has no webhook secret.
API
| Action | Request |
|---|---|
| Create the connection | POST /api/v1/connections with company_id, kind: "vcs", provider: "github", deployment_type, name and github_config |
| Start the manifest flow | POST /api/v1/connections/{id}/github/manifest with organization and public |
| Read the installations | POST /api/v1/connections/{id}/github/installations/sync |
| Remove the App from the connection | DELETE /api/v1/connections/{id}/github/app |
All of them need a company admin.