Skip to main content

GitLab change management: approval rules and beyond

· 8 min read
The team behind Merge Pilot

GitLab ships with a solid set of controls for merge requests: protected branches, approval rules, code owners, merge checks and external status checks. For many teams they are enough. Organisations that run formal change management usually need a little more: a change approval in a tracker, different paths for different kinds of change, and evidence that ties it all together. This guide describes what GitLab offers natively, then what a Merge Pilot change policy adds and how the two fit together.

What GitLab offers natively​

Protected branches​

A protected branch limits who may push to a branch and who may merge into it, and whether force pushes are allowed. It is the foundation for everything else: without it, changes can reach the branch without a merge request at all. Protected branches are available on every GitLab tier.

Approval rules and approval settings​

Merge request approval rules require a number of approvals from named users, groups or roles before a merge request can merge, and can target specific protected branches. Required approval rules are a GitLab Premium and Ultimate feature.

The project's approval settings tighten how approvals behave. Among them are settings that keep the author from approving their own merge request, keep people who added commits from approving it, stop approval rules from being edited inside a merge request, and remove existing approvals when new commits are pushed, so an approval never covers newer code.

CODEOWNERS​

A CODEOWNERS file names the owners of paths in the repository. With code owner approval required on a protected branch, a merge request that changes owned files needs an approval from the owners. Sections group owners and can set their own number of approvals; optional sections need none.

Merge checks​

Merge checks are conditions GitLab evaluates before it allows a merge, such as requiring the pipeline to succeed or all discussion threads to be resolved.

External status checks​

External status checks send merge request data to a service outside GitLab, which reports back a passed or failed status. A project can require them to pass before merging. They are a GitLab Ultimate feature and the usual integration point for external systems that want a say in the merge.

Merge trains​

Merge trains queue merge requests and run pipelines on the combined result of each merge request with the ones ahead of it, so the target branch stays green.

What a change process asks beyond that​

GitLab's controls are built around the merge request in GitLab: who may push, who must review, which checks must pass. A change management process usually asks further questions, and these are the ones a change policy answers:

QuestionWhat a change policy adds
Was the change approved in our change process, not only reviewed?A change approval in Jira or the built-in tracker, whose decision holds the merge
Do different kinds of change follow different paths?Policies matched by branch, repository, author, labels, changed files and size, each with a change type
Can an emergency merge now and be reviewed later?Emergency policies with a review deadline and limits on who may declare one
Was the ticket decision made by someone allowed to make it?Every tracker decision checked against the policy's approvers and separation of duties
Did the security scans of this change pass?Secret, dependency, license and other scans as policy controls, reported or enforced
Which version of the rules decided this change?Each merge request records the policy version that decided it
Did anything reach the branch outside the process?Direct changes and weakened protection reported, and a compliance report for a period

None of this replaces GitLab's controls. Merge Pilot writes several of them for you and builds the change decision on top.

How Merge Pilot uses GitLab's own controls​

When a GitLab project is put under change management, Merge Pilot writes these setup steps, after showing them and asking for consent:

StepWhat it writesRequired
Protect the target branchesA protected branch per target branch pattern: by default push allowed to no one and merge allowed to Developers and Maintainers (the connection sets both). An already protected branch is left as it isYes
Add the bot user as a memberThe connection's bot user with the Developer role, unless it already has that role or higherYes
Approval rule per target branchA rule named Merge Pilot — <branch> requiring one approval from the bot user onlyYes
Remove approvals when commits are addedTurns on the project setting of that nameNo (on by default)
Prevent editing approval rules in merge requestsTurns on the project setting of that nameNo (on by default)
Prevent approval by the authorTurns on the project's "Prevent approval by author"No (on by default)
Prevent approvals by users who add commitsTurns on the project setting of that nameNo (on by default)
Project webhookMerge Pilot's project webhookYes

The merge gate is the approval rule. When the change policy is met for the merge request's latest commit, the bot approves; otherwise it withdraws its approval. Nobody else can meet the rule, so GitLab refuses the merge until change management clears it. Because the gate is an approval rule, it needs GitLab Premium or Ultimate; when GitLab refuses the rule, the setup says so and leaves the project as it was. See GitLab change management setup steps and Merge gate on GitLab.

Your own approval rules stay in place. A team that already requires two maintainer approvals keeps that rule; the Merge Pilot rule is added next to it.

Peer review versus change approval​

A change policy separates two decisions that GitLab's approvals often carry together:

  • Code review: peers check the code in GitLab. The policy's Code review control can require a number of approvals from people with at least a given role, and hold the merge while changes are requested. GitLab approvals carry no commit, so they are counted for the latest commit only when the project removes approvals on push; otherwise the control stays pending and says why. See Code review on GitLab and GitHub.
  • Change approval: the change process signs off in the tracker. Who may approve is set by the policy's Who must approve: the project's approver roles, approver pools, or the code owners of the changed files.

CODEOWNERS in a change policy​

A Code owners of the changed files requirement reads the CODEOWNERS file on the target branch (CODEOWNERS, docs/CODEOWNERS or .gitlab/CODEOWNERS, the first found) and asks one approval from each set of owners, honouring a GitLab section's own count. Optional sections need no approval. Owners are people: user names, or the e-mail of a Merge Pilot user who linked their GitLab account. Groups and role entries are not asked, and the merge request lists them as Not asked from …. See Code owners.

Pipelines and merge trains​

The policy's CI control reads pipelines on the merge request's latest commit. GitLab pipelines always count; external pipelines created for commit statuses count only when the policy turns on Count commit statuses, because anyone who may push can post one. A policy can name the pipelines it expects by their workflow:name.

Merge Pilot does nothing of its own for merge trains: the gate stays the bot's approval. Pipelines GitLab runs on a merge request's merged result or merge train count for the latest commit, so the CI control sees them. See CI.

Keeping the setup intact​

A GitLab maintainer can loosen a project after it was set up: unprotect a branch, allow force pushes, edit the approval rule, unlock the approval settings. Merge Pilot checks gated projects for such gaps when the company's Check gated projects' branch protection and warn when it lets changes skip the merge gate is on (the default), every six hours by default. New gaps are written as protection_weakened and announced. Re-run CM setup writes the steps again. See Branch protection check.

Pushes that reach a target branch or the default branch without a merge request, force pushes and deleted branches are recorded as direct changes. Merge Pilot's own bot user is never reported.

A practical rollout on GitLab​

  1. Create the GitLab connection with a bot user that has a personal access token with the api scope and the Maintainer role on the projects to be gated. See GitLab.
  2. Watch first. Watched projects only get a webhook; Merge Pilot records what it would have decided without writing anything else. See Watching repositories.
  3. Write the policies, starting from a template, and check them with Which policy applies?.
  4. Move projects to change management, one or in bulk, reviewing the setup steps before agreeing to them.
  5. Keep your own rules. Leave existing approval rules, CODEOWNERS and merge checks in place; the change policy adds the change decision next to them.

Next steps​

The Merge gate feature page describes the gate on GitLab and GitHub side by side. For the step-by-step behaviour of the gate, see Merge gate. To see a change policy gate a GitLab project of yours, ask for a demo.