Core concepts
Merge Pilot is organised around a few objects. The rest of the documentation uses these words in the meanings below.
Company
A company is a tenant: its own connections, projects, policies, people and settings. One Merge Pilot instance can hold many companies, and each is isolated from the others. People belong to a company and have a role in it (see Roles). A company's settings are described in Companies.
Connection
A connection links a company to an outside system:
| Kind | Providers | Used for |
|---|---|---|
| VCS | GitLab (GitLab.com or self-managed), GitHub (github.com or GitHub Enterprise Server 3.12 and newer) | Merge requests, pipelines, pushes, and the merge gate |
| Tracker | Jira (cloud or self-managed), MergePilot (the built-in tracker) | Change approvals and work items |
A company can have several connections of each kind. See Connections.
Project
A project is a repository of a VCS connection that Merge Pilot knows about. It is in one of two modes:
- Watching: merge requests are evaluated and recorded, but nothing is blocked. This shows what change management would do before it is switched on.
- Change management: the merge gate is written into the repository and merges wait for the policy.
See Repositories.
Change policy
A change policy decides how a merge request is handled. Policies are kept in order; each merge request is covered by the first active policy that matches it, from top to bottom, and a catch-all policy at the bottom covers the rest.
A policy has:
- Match conditions: target and source branches, repositories, changed paths, the size of the change, its author and labels.
- A change type:
- standard: the controls must pass; no change approval.
- normal: the controls must pass and a change approval must be approved.
- emergency: the change may merge before its change approval is decided; it is reviewed afterwards.
- Controls: work items, code review, CI, secret scan, dependency scan, licenses, package health, dependency sources, CI configuration check, container image scan, infrastructure check, signed commits, risk, change freeze and approval. Each control is off, reported (shown, does not hold the merge) or enforced (holds the merge until it passes).
See Change policies.
Change approval
A change approval is the tracker issue that records the decision on one change. For a change that needs one, Merge Pilot opens it in the company's tracker, assigns it to someone who may decide it, and counts the approving and rejecting votes, cast in the tracker or in Merge Pilot. The author of the change never decides its change approval. See Change approval and Voting.
Merge gate
The merge gate is how the VCS itself blocks the merge:
- GitHub: a ruleset requires the Merge Pilot / change approval check, which Merge Pilot reports on each head commit.
- GitLab: a protected branch, and an approval rule whose only approver is the connection's bot user. Merge Pilot approves as the bot when the policy is met.
The decision is for one commit: a new commit, or moving the merge request to another target branch, needs a new decision before it can merge. See Merge gate.
Roles
| Role | In short |
|---|---|
| Platform admin | Runs the Merge Pilot instance: platform settings, all companies |
| Company admin | Runs one company: connections, projects, people, settings |
| Policy manager | Writes the company's change policies and approver pools |
| Auditor | Reads everything in the company, changes nothing |
| User | Works with merge requests and change approvals |
Each role is described fully in Roles and users.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →