GitLab
A GitLab connection lets Merge Pilot follow the merge requests of GitLab projects and gate them. It works with GitLab.com (Cloud) and self-managed GitLab (On-prem).
On GitLab the merge gate is a protected branch plus an approval rule whose only approver is the connection's bot user. Merge Pilot approves the merge request as the bot, for its current head commit, once change management clears it, and withdraws that approval otherwise.
Before you start
- A bot user: a GitLab account used only by Merge Pilot (a service account).
- A personal access token of the bot user with the
apiscope (GitLab: User Settings → Access Tokens). - The Maintainer role for the bot user on the projects Merge Pilot sets up: the setup steps protect branches, write approval rules, change project approval settings and create project webhooks. The bot user also does what people ask Merge Pilot to do on their projects (variables, branch protection, joining; see Permissions): for those it needs the role GitLab asks for each operation, for example Maintainer on the project for its variables and branch protection. Merge Pilot adds people to a group, or creates a group variable, only while every project of the group and its subgroups is in Merge Pilot for the company; it adds no one but company admins to a group that is shared with other groups (invited into them), since its direct members get access there too. Only company admins may unprotect a branch under change management or allow force pushes on it. GitLab's protection patterns are read as GitLab reads them:
*also matches/, sorelease/*coversrelease/a/b. - People need no more GitLab rights than the minimum role the connection's rule for an operation names (for example Developer to manage variables): the bot user does the operation for them.
- Variables: people can add and edit project and group variables with an environment scope, a type (variable or file), a description, and as protected, masked, hidden or raw. Hidden variables need GitLab 17.4 or later; on groups, environment scopes need GitLab Premium or Ultimate. The value of a masked or hidden variable is never shown in Merge Pilot (see Variables).
- Tokens: people can create project access tokens and deploy tokens through Merge Pilot (see Tokens through Merge Pilot).
- If GitLab refuses the bot user's token (revoked or expired), operations answer Merge Pilot's account was refused by GitLab; check the connection: give the connection a new token. When GitLab's API rate limit is reached, they answer GitLab's API rate limit is reached: try again in N seconds.
- GitLab Premium or Ultimate for projects under change management: approval rules need it. Projects that are only watched do not.
- A webhook secret: a long random string (at least 32 characters). It is required.
Connection fields
Open the company's Connections tab, choose Add VCS connection, and pick GitLab as the Provider. The fields shared by every connection (Name, Deployment type, Active) are described in Connections. The section GitLab configuration has these fields:
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| URL | Address of the GitLab instance | none, required | A full http(s):// URL, for example https://gitlab.com or https://gitlab.yourcompany.com | Company admin | gitlab_config.url |
| Token | Personal access token Merge Pilot calls GitLab with. It must belong to the bot user, since Merge Pilot approves merge requests with it | none | A GitLab token with the api scope. Leave empty when editing to keep the stored one; required again when the URL moves to another host | Company admin | gitlab_config.token (write only; has_token shows whether one is stored) |
| Bot username | The GitLab username of the account that owns the token. Merge Pilot approves merge requests as this account, the only approver of its approval rule, so nobody else can meet the rule. The bot is never assigned a change approval | none, required | A GitLab username | Company admin | gitlab_config.bot_username |
| Webhook secret | The secret GitLab sends with every webhook; Merge Pilot writes it into the project webhooks it creates and ignores every webhook that does not carry it | none, required | Any string. Leave empty when editing to keep the stored one | Company admin | gitlab_config.webhook_secret (write only; has_webhook_secret) |
| Enable OAuth | Lets people sign in to Merge Pilot with GitLab and link their GitLab account in My profile. See Sign in with GitLab | Off | On, off | Company admin | gitlab_config.oauth_enabled |
| OAuth client ID | Application ID of the GitLab OAuth application. Shown when Enable OAuth is on | none | The GitLab application ID | Company admin | gitlab_config.oauth_client_id |
| OAuth client secret | Secret of the GitLab OAuth application. Shown when Enable OAuth is on | none | The GitLab application secret. Leave empty when editing to keep the stored one | Company admin | gitlab_config.oauth_client_secret (write only; has_oauth_client_secret) |
| Skip TLS verification | Accepts any certificate the GitLab server shows. Only for self-hosted instances with self-signed certificates. The project webhooks Merge Pilot creates then also have SSL verification turned off | Off | On, off | Company admin | gitlab_config.tls_skip_verify |
With Skip TLS verification on, someone between Merge Pilot and GitLab could read the connection's token. Prefer a certificate GitLab and Merge Pilot both trust.
The connection is refused without a bot username, both when it is created and when it is edited.
When the token expires, Merge Pilot can no longer reach GitLab. The Connections tab shows when it expires, as GitLab says, and the company admins get Connection token expiring (connection_token_expiring) 14 days and again 3 days before: create a new token for the same account on GitLab and enter it on the connection.
The webhook
Merge Pilot learns about merge requests, pipelines and pushes from a GitLab project webhook. You do not create it by hand: the setup step Project webhook creates it on every project that is put under change management or watched.
The webhook Merge Pilot creates:
| GitLab webhook setting | Value |
|---|---|
| URL | <Application URL>/api/v1/webhooks/vcs/<company slug>/<connection id> (the connection's Copy webhook URL) |
| Secret token | The connection's Webhook secret |
| Merge request events | On |
| Pipeline events | On |
| Job events | On |
| Push events | On when the company's Receive push events (Direct changes) is on, filtered to the target branches and the default branch. GitLab versions that cannot filter pushes by a regular expression deliver pushes of every branch, and Merge Pilot ignores those outside the target branches |
| Tag push events | Off |
| Enable SSL verification | On, unless the connection has Skip TLS verification |
An existing webhook of this connection on the project (one whose URL ends with /api/v1/webhooks/vcs/<company slug>/<connection id>, whatever address it calls) is updated in place; extra copies are deleted. Another connection's webhook to the same project is left alone. When the Application URL changes, every webhook is pointed at the new address in the background.
The branch protection check (see Direct changes) also reports a webhook that is missing, or that GitLab disabled after failed deliveries: merge requests are then not reported to Merge Pilot. Sync CM creates a missing one again; a disabled one is enabled again on GitLab.
How webhooks are verified
GitLab sends the secret in the X-Gitlab-Token header. Merge Pilot compares it with the connection's Webhook secret and ignores the delivery when the header is missing or the secret does not match.
Lost webhooks are not fatal: Merge Pilot re-checks open merge requests against GitLab regularly.
Change management setup steps
When a project is put under change management, Merge Pilot writes these steps, in this order. Required steps make the merge gate and cannot be turned off. Optional steps are on by default; each connection sets its own defaults (see Change management setup), and each move to change management may turn them off for that project.
| Step (label in the UI) | Required | What it writes to GitLab | When change management is removed |
|---|---|---|---|
| Protect the target branches | Yes | A protected branch for each target branch pattern, with the connection's Allowed to push and merge (No one by default) and Allowed to merge (Developers and Maintainers by default). A branch that was protected before Merge Pilot is left as it is; one Merge Pilot protected gets the connection's current levels (see Branch protection levels) | The protection stays, so the project is not loosened; Also take back what change management created removes the protections it added |
| Add the bot user as a member | Yes | Adds the bot user to the project with the Developer role, so it can be the approval rule's approver. When the bot already has Developer or higher on the project, for example as a member of its group, nothing is added (GitLab accepts a member of the project's group or a parent group as an approver, and refuses a direct role lower than an inherited one) | The bot stays a member; the undo removes it when Merge Pilot added it |
| Approval rule per target branch | Yes | One rule per target branch, named Merge Pilot — <branch>, requiring 1 approval from the bot user only. Rules of branches no longer gated are deleted once the setup succeeded. Needs GitLab Premium or Ultimate | The rules are deleted. When one cannot be deleted, the removal fails and the project stays under change management |
| Remove approvals when commits are added | No (on by default) | Turns on the project's "Remove all approvals when commits are added", so an approval never covers newer code | The setting stays on; the undo puts back the value it had |
| Prevent editing approval rules in merge requests | No (on by default) | Turns on that project setting, so nobody changes the approvers of one merge request | As above |
| Prevent approval by the author | No (on by default) | Turns on "Prevent approval by author" | As above |
| Prevent approvals by users who add commits | No (on by default) | Turns on that project setting | As above |
| Project webhook | Yes | Creates or updates Merge Pilot's project webhook (see The webhook) | The webhook is deleted (a watched project keeps it) |
API keys of the steps: protect_branches, bot_member, approval_rule, reset_approvals_on_push, no_approver_override, no_author_approval, no_committer_approval, webhook.
Branch protection levels
The connection's settings (Change management setup) set the branch protection change management adds:
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Allowed to push and merge | Who may push to the target branches directly | No one | No one (0), Maintainers (40), Developers and Maintainers (30) | Connection | Company admins, platform admins | cm_protection.push_level |
| Allowed to merge | Who may merge into them | Developers and Maintainers | Developers and Maintainers (30), Maintainers (40); nobody merging is refused | Connection | Company admins, platform admins | cm_protection.merge_level |
A push level other than No one is the connection's choice: the protection check does not report it, and the tab warns that such pushes change the branch without a merge request (direct change detection still reports them).
Changing the levels does not touch the repositories at once. At each repository's next setup run (Sync CM, Re-run CM setup, or a change of branches), the protections Merge Pilot created get the new levels. A branch that was protected before Merge Pilot keeps its own levels, and the setup warns that they differ from the connection's (change them on GitLab if you want the connection's).
What change management created
The setup records what it created, not what was there before: the branch protections and the bot membership it added, and the approval settings it changed with their earlier values (cm_setup.created on the project). Remove CM, Switch to watching (one repository or a bulk switch) and Stop watching (one or bulk) of a repository that was once under change management offer Also take back what change management created: those protections and that membership are removed and the settings put back; anything that was there before stays. Off by default. API: undo_setup on POST /api/v1/projects/cm-remove, PUT /api/v1/projects/{id}/mode, POST /api/v1/projects/{id}/unwatch and bulk operations of kind to_watching and unwatch.
Taking back happens in this order:
- The approval settings are put back first. When GitLab refuses, nothing is removed and the removal fails with GitLab's answer.
- The approval rules and the webhook are removed, as in any removal.
- The branch protections and the bot membership are removed. When GitLab refuses one of these, the removal still completes, and the page lists what was left on GitLab, to remove by hand (API:
left_on_vcs).
When GitLab no longer offers approval rules (for example after a licence downgrade to Free), the removal completes: there is no rule left to hold merges.
- A required step fails: everything this run created is removed again and the approval settings it changed are put back, so the project is as before, and the move reports the failing step. When GitLab refuses the approval rule, the message says that approval rules need GitLab Premium or Ultimate.
- One setup at a time: while a repository is being set up, another setup of it is refused (
409, change management of this repository is being set up right now: try again in a moment). - An optional step fails: the setup still succeeds, with a warning that names the GitLab setting to turn on by hand (Settings → Merge requests).
- A watched project gets only the project webhook (step Event delivery). Creating it needs the Maintainer role.
- The target branches are the project's own target branch patterns, else the company's; the project's excluded branches are skipped.
**in a pattern is written as*, which in GitLab also spans/. A target pattern that an exclusion covers only in part (for examplerelease/**withrelease/*excluded) stays protected and gets its approval rule; merge requests into the excluded branches are approved by Merge Pilot without checking them.
Merge Pilot also checks gated projects for gaps in their protection (when the company turns that check on under Direct changes) and reports, for example, a target branch that someone may push to directly, a branch that allows force pushes, an approval rule that is missing or names other approvers, or approval settings that were unlocked. Pushes at the level the connection allows are not reported.
Tokens through Merge Pilot
With the connection's rules Create project access tokens and Create deploy tokens (see Permissions), people create GitLab tokens on a repository from its Tokens tab, and the bot user creates them.
- The bot user needs Maintainer or Owner on the project: GitLab asks that role of whoever creates project access tokens and deploy tokens. Otherwise GitLab refuses, and Merge Pilot answers the VCS refused the operation: GitLab answered 403: ….
- GitLab.com needs Premium or Ultimate for project access tokens. During a trial GitLab allows one project access token. On GitLab Self-Managed and GitLab Dedicated they are available with any license. Deploy tokens are available on every tier.
- Roles: a project access token gets Guest, Reporter or Developer, never above the person's own role on the project. GitLab itself would allow up to the bot user's role; Merge Pilot never gives Maintainer or Owner.
- Expiry: always set, at most 365 days away (GitLab's default maximum for access tokens). If your GitLab administrators lowered the maximum lifetime, GitLab refuses a date beyond it. GitLab lets deploy tokens never expire; Merge Pilot always sets an expiry, with the same 365-day limit.
- The value is shown once to the person who created the token and never stored by Merge Pilot.
- Description of a project access token is kept by GitLab 17.7 and later.
Sign in with GitLab
With Enable OAuth, people sign in to Merge Pilot with their GitLab account, and link it from My profile. Linking matters: people need a linked GitLab account to be assigned and decide change approvals.
- In GitLab, create an OAuth application (for example under Admin → Applications) with the scope
read_user. - Set its redirect URI to
<Public URL>/api/v1/auth/gitlab/callback. Public URL is set under Settings → General; when it is empty, the Application URL is used. - On the connection, turn on Enable OAuth and enter the OAuth client ID and OAuth client secret.
The GitLab sign-in button appears only when OAuth is on and both the client ID and the client secret are set.
A first sign-in that creates a Merge Pilot account needs an email GitLab says is confirmed. When GitLab reports the account's email as not confirmed, no account is created and the person sees Your GitLab email is not confirmed. Confirm it in GitLab, then sign in again. People whose Merge Pilot account already linked their GitLab account sign in either way, as their email is not used.
API
| Action | Request |
|---|---|
| Create | POST /api/v1/connections with company_id, kind: "vcs", provider: "gitlab", deployment_type, name and gitlab_config |
| Edit | PUT /api/v1/connections/{id} with the fields to change; empty secrets keep the stored ones |
| Test | POST /api/v1/connections/{id}/test |
All three need a company admin.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →