Skip to main content

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 stateTitle on GitHubWhen
In progressThe first required control still pending and its reason, for example Change approval: …; Waiting for change management when no control is namedChange management is still deciding
SuccessApproved by change managementThe change is approved for this commit
FailureThe first enforced control that failed and its reason, for example Secret scan: …; Blocked by change management when no control is namedChange 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 doesDefaultAllowed valuesWho can change itAPI field
Enterprise Server URLAddress of the GitHub Enterprise Server. Shown for GitHub Enterprise Server only; a github.com connection always uses https://github.comnone, required for Enterprise ServerA full http(s):// URL that is not github.comCompany admingithub_config.web_url
Skip TLS verificationAccepts any certificate the server shows. Enterprise Server only, for servers with self-signed certificatesOffOn, offCompany admingithub_config.tls_skip_verify
Sign in with GitHubPeople sign in to Merge Pilot and link their GitHub account through the App. See Sign in with GitHubOffOn, offCompany admingithub_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.

Skip TLS verification

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 .local name, 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 doesDefaultAllowed values
OrganizationThe organization the App is registered underEmpty: your personal GitHub accountA GitHub organization name (letters, digits and hyphens, at most 39 characters)
Let other organizations install itMakes the App public. Without this, the App installs only on the account it is created underOffOn, off

Then choose Create GitHub App. Merge Pilot sends you to GitHub with the App's manifest:

Manifest itemValue
NameMerge Pilot <company slug> (you can change it on GitHub before confirming)
Homepage URLThe 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 installationOff

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)AccessUsed for
Checks (checks)writeThe change approval check on pull requests (the merge gate)
Pull requests (pull_requests)writeReading pull requests, their reviews and commits; comments on pull requests
Contents (contents)readReading changes and files (policies, scanning)
Metadata (metadata)readReading repositories and collaborators' access (required by GitHub)
Administration (administration)writeThe merge gate's ruleset; branch protection; joining and leaving repositories
Actions (actions)readPipeline results (workflow runs); listing environments
Commit statuses (statuses)readPipeline results (commit statuses)
Secrets (secrets)writeRepository secrets (the project page's Variables tab)
Variables (actions_variables)writeRepository variables (the Variables tab)
Environments (environments)writeEnvironment 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)writeOrganization secrets
Variables, organization (organization_actions_variables)writeOrganization variables
Email addresses (emails)readThe person's verified email at sign-in (company email domains, matching people in the tracker)
Merge queues (merge_queues)readThe 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
RefreshReads 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:

WarningWhyWhat 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 permissionThe 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 featuresThe 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 permissionsThe 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 doesAllowed valuesAPI field
App IDThe App's numeric IDA number. Required together with a private keygithub_config.app_id
App slugThe App's slug (the name in its URL)Textgithub_config.app_slug
Client IDThe App's client ID, for sign-inTextgithub_config.client_id
Client secretThe App's client secret, for sign-inText (write only; has_client_secret)github_config.client_secret
Webhook secretThe secret the App signs its webhooks withText (write only; has_webhook_secret)github_config.webhook_secret
Private keyThe App's private keyA PEM key (-----BEGIN RSA PRIVATE KEY-----); a key that is not valid PEM is refusedgithub_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)RequiredRuleset rule it addsWhen change management is removed
Ruleset with Merge Pilot's required checkYesThe 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 dateThe ruleset is deleted
Require a pull requestNo (on by default)"Require a pull request before merging", with no reviews required by itDeleted with the ruleset
Block force pushesNo (on by default)"Block force pushes"Deleted with the ruleset
Block branch deletionNo (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 rulesetBranch protection ruleset
NameMerge Pilot change managementMerge Pilot protected: <branch>, one per protected branch
Created byChange management setupProtect on the Branches tab
BranchesThe target branches, less the excluded onesThat one branch
RulesThe 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 pushNot changedRemoves "Block force pushes" from that ruleset
Removed byRemoving change managementUnprotect
  • 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​

ActionRequest
Create the connectionPOST /api/v1/connections with company_id, kind: "vcs", provider: "github", deployment_type, name and github_config
Start the manifest flowPOST /api/v1/connections/{id}/github/manifest with organization and public
Read the installationsPOST /api/v1/connections/{id}/github/installations/sync
Remove the App from the connectionDELETE /api/v1/connections/{id}/github/app

All of them need a company admin.