Connections
A connection links a company to an outside system. Merge Pilot reads merge requests and writes the merge gate through a VCS connection, and opens change approvals through a tracker connection. Connections are managed on the company's Connections tab, in two lists: VCS connections and Tracker connections.
Providers and deployment types
| Kind | Provider | Deployment type (label in the UI) | Page |
|---|---|---|---|
| VCS | GitLab | Cloud (GitLab.com) or On-prem (self-managed) | GitLab |
| VCS | GitHub | github.com or GitHub Enterprise Server (3.12 or newer) | GitHub |
| Tracker | Jira | Cloud or On-prem (Server or Data Center) | Jira |
| Tracker | MergePilot Tracker (the built-in tracker) | none: it runs inside Merge Pilot | Built-in tracker |
- A company can have several connections of each kind and of each provider, for example two GitLab instances and one GitHub organization.
- The provider and the deployment type are chosen when the connection is created and cannot be changed later. To move to another provider or deployment type, create a new connection.
Fields every connection has
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Name | The name shown in lists and pickers | none, required | Any text | Company admin | name |
| Provider | Which system the connection talks to. Shown only when the connection is created | GitLab (VCS), Jira (tracker) | VCS: GitLab, GitHub. Tracker: Jira, MergePilot Tracker | Set once, at creation | provider (gitlab, github, jira, mergepilot) |
| Deployment type | Cloud service or self-hosted instance. Not asked for the built-in tracker | The provider's first option (Cloud, github.com) | See the table above | Set once, at creation | deployment_type (cloud, on_prem) |
| Active | Off: Merge Pilot ignores every webhook the connection receives, the connection is left out of the pickers on other pages (projects, policies, sign-in), and the operations people ask Merge Pilot to do on the VCS through it are paused (below). It stays on the Connections tab, marked inactive, where it is turned back on | On | On, off | Company admin | active |
While a VCS connection is turned off, every change asked through it is refused, company admins included, with 409 this connection is turned off: ask a company admin: joining, variables, branch protection, creating tokens, and setting change management up or removing it. Taking access back still works, so that nobody is left holding access they want to give up: leaving a repository or group, cancelling an invitation, and revoking a token. Reads (lists, membership, what you may do) work too. The project page says This <GitLab or GitHub> connection is turned off: Merge Pilot operations are paused. You can still leave and revoke your tokens. and offers no other change; GET /api/v1/vcs-ops/projects/{pid}/my-access answers connection_active: false.
The kind of a connection (kind: vcs or tracker) follows from the list it was added in. GET /api/v1/connections lists active connections; add include_inactive=true to list the inactive ones too. The provider-specific fields are described on each provider's page.
Secrets (tokens, webhook secrets, private keys, client secrets) are never shown again after they are saved. A saved secret is marked Configured; leave the field empty to keep it. Changing the URL of a GitLab or Jira connection to another host, or the Enterprise Server URL of a GitHub connection, requires entering the token (or the private key) again: a stored secret is never sent to a different host.
Connection URLs must start with http:// or https:// and the host name must resolve. Addresses of cloud metadata services, link-local addresses and loopback addresses (such as localhost) are refused. Addresses on private networks are allowed.
Who may do what
| Action | Who |
|---|---|
| See the company's connections (without their secrets) | Every signed-in member of the company |
| Add, edit, test and delete a connection, change its settings, create or remove its GitHub App | Company admins of that company, and platform admins |
| Use the operations a VCS connection allows through Merge Pilot | Company admins always; other members only where the connection's permissions allow it |
Creating, changing and deleting a connection is recorded in the audit log, with what changed (secrets masked).
Default connections
Each company has one default VCS connection and one default tracker connection (marked with a star).
- The first connection of a kind that a company gets becomes its default automatically.
- A company admin makes another connection the default with the star button on its row (tooltip: Set as default (preselected for the People check and new projects)). API:
PUT /api/v1/companies/{id}withdefault_vcs_connection_idordefault_tracker_connection_id. - The default VCS connection is used when a request names no connection, and its sign-in button is listed first on the sign-in page when sign-in through the VCS is set up on several connections.
Change approvals do not go to the default tracker: they go to the tracker connection linked to the merge request's VCS connection (see Linked tracker connection).
Test connection
The Test connection button (flask icon) checks that Merge Pilot can reach the provider with the stored credentials:
| Provider | What the test does |
|---|---|
| GitLab | Lists one project the token is a member of |
| GitHub | Checks that a GitHub Enterprise Server runs version 3.12 or newer, signs in as the GitHub App, and checks that the App is installed on at least one account. When that passes, it also checks the installation tokens, the credentials all background work uses (see Connection health) |
| Jira | Reads the account the username and token belong to |
| MergePilot Tracker | Always succeeds |
The test passes when the provider answers. For a GitHub App, an installation token GitHub refuses does not fail the test, as the App itself answered: the token problem shows in red on the connection's row instead (see Test passes but the row stays red).
When the test fails, the message says in one sentence what failed and what the provider or the network answered, for example Jira refused the connection's credentials (it answered 401 Unauthorized: …): enter a valid token or key. or Merge Pilot could not reach GitLab at gitlab.example.com: the host name does not resolve. (see Test connection fails). The test does not check the token's permissions on each repository; the change management setup reports those per step (see GitLab and GitHub).
Connection health
Merge Pilot keeps track of problems that stop a connection from working, and shows each on the connection's row in red with when it started:
| Problem | Line on the Connections tab | Found by | Gone when |
|---|---|---|---|
| Credentials refused | The VCS refuses Merge Pilot's credentials (since …) | The regular check of every active VCS connection (about every minute), Test connection, or a background job the VCS answered 401. For a GitHub App the check also calls GitHub with each installation's token, the credentials all work uses | A check succeeds with the same credentials: the connection's token (GitLab), or the token of every installation Merge Pilot can use (GitHub). The GitHub App answering is not enough |
| GitHub App permissions | The GitHub App lacks permissions Merge Pilot needs (since …) | The App's sync, the regular check or Test connection, from the permissions last read from GitHub: the App, or one of its installations, lacks a permission Merge Pilot asks for or has not accepted it | The permissions are granted and accepted, and the App is refreshed |
| Rate limit used up | The API rate limit is used up: background work waits for its reset (since …) | A background job that hit the VCS's rate limit, or a check that found an installation's limit used up (GitHub) | For a limit a background job hit, the reset time the VCS gave has passed; a check succeeds with the same credentials; and the share of the hour's calls kept for live events is no longer all that is left |
| Turned off | (the connection shows as inactive) | An admin turned the connection off | It is turned on again |
Each change is written to the audit log (connection_unhealthy, connection_recovered) and announced as the Connection problem and Connection recovered notifications (the same problem once within an hour; a recovery only after its problem was announced, so the two always alternate; turning a connection off or on every time), to the routes that take them and by email to the company admins (see Events → Connections and sign-in). While a connection has a problem, the jobs that fail because of it are not each announced as Background job failed. A check that cannot reach the VCS at all changes nothing here: it is shown on Insights → Service health.
The API returns the problem as health on the connection: problem (token_refused, app_permissions, rate_limited, turned_off), since, and for a rate limit a background job hit until (the reset time the VCS gave, if it did); no health means no problem.
GitHub App installations
A GitHub App connection's check looks at each installation as GitHub lists it:
- Suspended: the installation's owner suspended the App on GitHub. Merge Pilot cannot reach that account's repositories until it is unsuspended. The installation shows Suspended on the connection; it is not a token problem and does not keep the connection red.
- Removed on GitHub: GitHub no longer lists the installation (the App was uninstalled from the account). It shows Removed on GitHub until the next refresh of the App's installations drops it.
- Token refused: GitHub refused that installation's token. The connection shows The VCS refuses Merge Pilot's credentials until every installation Merge Pilot can use works again.
With many installations, each check calls up to 20 of them, a few at a time, and the next check goes on with the others. An installation keeps what its last check found, so a refused token is not forgotten while the others are checked. The API returns this as installation_tokens on the connection: by installation ID, a status (ok, suspended, removed, token_refused, rate_limited, unreachable) and checked_at.
Webhook URLs
GitLab, GitHub and Jira connections show a Copy webhook URL link on their row. The built-in tracker takes no webhooks and shows none. The URL has this form:
<Application URL>/api/v1/webhooks/vcs/<company slug>/<connection id> (VCS)
<Application URL>/api/v1/webhooks/tracker/<company slug>/<connection id> (tracker)
Application URL is set by a platform admin under Settings → General: it is the address the VCS and the tracker call, so it must be reachable from them. A GitHub App created from Merge Pilot gets this URL by itself; an App registered by hand needs it entered on GitHub.
Refused webhooks
When a webhook for the connection arrives without the connection's webhook secret, Merge Pilot ignores it and the connection's row shows Last refused webhook: wrong secret, <date and time>. Its tooltip names the address the delivery came from. The same refusal is written to the audit log as webhook_refused. Both are recorded at most once a minute per connection, so a sender repeating a wrong secret cannot flood them.
The line stays until a new webhook secret is entered for the connection (Edit), or, for a GitHub App created from Merge Pilot, until the App is created again. See Webhooks arrive but are ignored for what to check.
Webhooks are accepted only while the Merge Pilot license is valid. A webhook for an unknown, deleted or inactive connection, or for a deactivated company, is answered and ignored.
Deleting a connection
The Delete button (trash icon, shown on hover) asks for confirmation. A connection that is still in use cannot be deleted; the dialog says why and its Delete connection button stays off:
- VCS connection: while repositories are watched or under change management through it. Merge Pilot wrote project webhooks, protected branches, approval rules or rulesets to them, and only Merge Pilot removes them. Take the repositories out on the Projects page first (stop watching, or move them back to watching and then stop).
- Tracker connection: while VCS connections send their change approvals to it. Link those VCS connections to another tracker, or to none, in their settings first.
The API answers 409 with the same reason.
What happens when the connection is deleted:
- The connection is removed from Merge Pilot right away, and webhooks that still arrive for it are ignored.
- When it was the company's default connection of its kind, another active connection of that kind becomes the default, or none when there is no other.
- VCS connection: Merge Pilot stops tracking the repository access people got by joining through it. That access stays on GitHub or GitLab; company admins see it under People.
- Deleting cannot be undone in the UI.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →