Skip to main content
3 video tutorials

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 api scope (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 /, so release/* covers release/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 doesDefaultAllowed valuesWho can change itAPI field
URLAddress of the GitLab instancenone, requiredA full http(s):// URL, for example https://gitlab.com or https://gitlab.yourcompany.comCompany admingitlab_config.url
TokenPersonal access token Merge Pilot calls GitLab with. It must belong to the bot user, since Merge Pilot approves merge requests with itnoneA GitLab token with the api scope. Leave empty when editing to keep the stored one; required again when the URL moves to another hostCompany admingitlab_config.token (write only; has_token shows whether one is stored)
Bot usernameThe 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 approvalnone, requiredA GitLab usernameCompany admingitlab_config.bot_username
Webhook secretThe secret GitLab sends with every webhook; Merge Pilot writes it into the project webhooks it creates and ignores every webhook that does not carry itnone, requiredAny string. Leave empty when editing to keep the stored oneCompany admingitlab_config.webhook_secret (write only; has_webhook_secret)
Enable OAuthLets people sign in to Merge Pilot with GitLab and link their GitLab account in My profile. See Sign in with GitLabOffOn, offCompany admingitlab_config.oauth_enabled
OAuth client IDApplication ID of the GitLab OAuth application. Shown when Enable OAuth is onnoneThe GitLab application IDCompany admingitlab_config.oauth_client_id
OAuth client secretSecret of the GitLab OAuth application. Shown when Enable OAuth is onnoneThe GitLab application secret. Leave empty when editing to keep the stored oneCompany admingitlab_config.oauth_client_secret (write only; has_oauth_client_secret)
Skip TLS verificationAccepts 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 offOffOn, offCompany admingitlab_config.tls_skip_verify
Skip TLS verification

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 settingValue
URL<Application URL>/api/v1/webhooks/vcs/<company slug>/<connection id> (the connection's Copy webhook URL)
Secret tokenThe connection's Webhook secret
Merge request eventsOn
Pipeline eventsOn
Job eventsOn
Push eventsOn 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 eventsOff
Enable SSL verificationOn, 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)RequiredWhat it writes to GitLabWhen change management is removed
Protect the target branchesYesA 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 memberYesAdds 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 branchYesOne 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 UltimateThe rules are deleted. When one cannot be deleted, the removal fails and the project stays under change management
Remove approvals when commits are addedNo (on by default)Turns on the project's "Remove all approvals when commits are added", so an approval never covers newer codeThe setting stays on; the undo puts back the value it had
Prevent editing approval rules in merge requestsNo (on by default)Turns on that project setting, so nobody changes the approvers of one merge requestAs above
Prevent approval by the authorNo (on by default)Turns on "Prevent approval by author"As above
Prevent approvals by users who add commitsNo (on by default)Turns on that project settingAs above
Project webhookYesCreates 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 doesDefaultAllowed valuesSet whereWho can change itAPI field
Allowed to push and mergeWho may push to the target branches directlyNo oneNo one (0), Maintainers (40), Developers and Maintainers (30)ConnectionCompany admins, platform adminscm_protection.push_level
Allowed to mergeWho may merge into themDevelopers and MaintainersDevelopers and Maintainers (30), Maintainers (40); nobody merging is refusedConnectionCompany admins, platform adminscm_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:

  1. The approval settings are put back first. When GitLab refuses, nothing is removed and the removal fails with GitLab's answer.
  2. The approval rules and the webhook are removed, as in any removal.
  3. 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 example release/** with release/* 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.

  1. In GitLab, create an OAuth application (for example under Admin → Applications) with the scope read_user.
  2. 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.
  3. 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​

ActionRequest
CreatePOST /api/v1/connections with company_id, kind: "vcs", provider: "gitlab", deployment_type, name and gitlab_config
EditPUT /api/v1/connections/{id} with the fields to change; empty secrets keep the stored ones
TestPOST /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 →

Connect GitLabYouTube ↗
Sign In with GitLab and Link Your AccountYouTube ↗
Approver RolesYouTube ↗