Skip to main content
Video tutorial · 1:34

Change management

A repository under change management has Merge Pilot's merge gate written into it: from then on its merge requests into the target branches merge only when their change policy is met (see Merge gate). This page covers how a repository gets there, what is written to it, how to check and repair the setup, and how to go back.

A repository can be put under change management in three ways:

WayWhereFor
Move a watched repositoryThe repository's page, or many at a time with a bulk operationRepositories you watched first. Recommended: the move shows what was recorded while watching and lets you decide what happens to open merge requests
Set up one repositoryThe page of a repository that is not in Merge Pilot yetA single new repository
Add repositories straight to change managementProjects → Add to change managementMany new repositories at once, without watching them first

Repositories found by automatic watching can also go straight under change management when the company says so (see Automatic watching).

Before you start​

  • The platform's Application URL is set (see Platform settings). Without it the setup is refused (app URL is not configured in settings — set it before running CM setup).
  • GitLab: the connection's bot user has the Maintainer role on the project, and the project is on GitLab Premium or Ultimate (approval rules need it). See GitLab.
  • GitHub: the App is installed on the repository with the Administration (write) permission accepted. Rulesets on private repositories need GitHub Team (or Pro) or Enterprise. See GitHub.
  • A change policy covers the connection: every connection has a catch-all policy (see Change policies). Without a linked tracker only standard changes can merge (see Tracker).

Before anything is written, every way of putting a repository under change management shows the setup steps: what is written to the repository, in two groups.

  • Required (a lock icon; Always written: the merge gate depends on them): these make the merge gate and cannot be turned off.
  • Optional: a check box each. They start as the VCS connection's defaults (see Change management setup); turn one off to leave it out for these repositories.

Each step shows what it writes and, after When change management is removed:, what happens to it then. The steps of each VCS, with their API keys, are described on the GitLab and GitHub pages.

Below the steps, a check box asks for consent: I allow Merge Pilot to make these changes in 1 repository. (or in N repositories, or in every matching repository). The button stays disabled until it is checked.

What is recorded:

  • cm_steps on the project: the steps that were chosen. Setting the repository up again later (a repair, a change of branches) writes the same steps without asking again.
  • cm_setup.consented_by and cm_setup.consented_at: who agreed and when. It is the person's user ID; for repositories added by automatic watching it is connection defaults. A bulk operation's retry keeps the consent of the person who agreed in the first operation.

API: the requests that write the steps take steps (a map from step key to on or off; a step left out takes the connection's default) and consent: true. Without consent the request is refused (agree to the setup steps written to the repository (consent)); turning a required step off, or naming a step the VCS does not have, is refused too.

Setting up one repository​

On the page of a repository that is not in Merge Pilot yet (found with the Search tab), the CM status card shows Not registered for CM and two buttons, Watch and Set up CM.

  1. Select Set up CM. The dialog Put <repository> under change management explains Merge Pilot writes the steps below to each repository and gates its merges by the change policies.
  2. Choose the optional steps and give consent.
  3. Select Set up CM.

The page then shows the live setup status. When an optional step failed, a warning says Change management set up with warnings with the first warning.

A watched repository cannot be set up this way (the repository is watched: move it to change management from its page).

API: POST /api/v1/projects/cm-setup with company_id, repo_id, connection_id (optional; the company's default VCS connection when left out), steps and consent. It answers 201 with the project.

Adding repositories straight to change management​

Projects → Add to change management opens Add repositories to change management: The repositories you choose, from <connection>, go straight under change management: their merge requests merge only once approved. Those already in Merge Pilot are listed but cannot be chosen.

  • Choosing repositories works as in Watch repositories (search, Choose the N shown, Show more, or Take every repository matching "…" that is not in Merge Pilot yet); see Watching a repository.
  • What is set up in each repository: the setup steps, with the optional ones to choose.
  • A note recalls that without a watching period there is no record of what change management would have held.
  • The consent check box, then Add N repositories (or Add every matching repository).

The repositories are set up in the background as a bulk operation of kind add_gated. Repositories already in Merge Pilot are skipped: one under change management (it is already under change management) and one that is watched (it is watched: move it with Move to change management), because moving a watched repository decides its open merge requests.

Moving a watched repository to change management​

On a watched repository's page, select Move to change management. The dialog explains: From now on Merge Pilot sets the merge gate on this repository, comments on its merge requests and opens change approvals, as its policies say. It shows:

Section (label in the UI)What it shows
While watchedWhat was recorded while watching, from the monitoring report of the last 90 days for this project: N merge requests recorded: B would be blocked, P would wait, C would need a change approval., and how many merges would have been held. Nothing recorded yet. when there is no record
Open merge requestsEach open merge request with its policy and the decision it has now: Would pass, Would wait, Would be blocked, or Not decided yet
What happens to the open merge requestsA choice, below
Written to the repository in <GitLab or GitHub>The setup steps

Then the consent check box and Move to change management.

What happens to the open merge requests​

Choice (label in the UI)What it doesAPI
Only new merge requests and new commits are gated; the open ones are let through until their next commit (the default)The open merge requests stay watched: their merge gate lets them through, nobody's work in progress is stopped. A merge request is gated from its next commit, or when its target branch is changed. New merge requests are gated from the startgate_open: false
Also gate the open merge requests nowEach open merge request is evaluated again under change management at once: its merge gate is set, its status comment is written and a change approval is opened when its policy needs onegate_open: true

When it fails​

The setup steps are written before anything else changes. When a required step fails, everything written in this run is removed again (on GitLab the approval settings it changed are put back too), the repository stays watched, and the move answers with the step that failed (changing the mode failed: the <step> step failed, nothing was changed: …). When an optional step fails, the move succeeds with a warning that names the setting to turn on by hand.

API: PUT /api/v1/projects/{id}/mode with mode: "gated", gate_open, steps and consent: true. GET /api/v1/projects/{id}/mode-impact lists the open merge requests with id, mr_number, title, policy, gate (approved, pending, blocked, or empty when not evaluated yet) and needs_change_approval.

When the gate is live​

From the moment the setup succeeded:

  • merge requests into the repository's target branches are matched to a policy, get a status comment and, when the policy needs one, a change approval, and their merge gate is set for the current head commit;
  • merges without approval, during a change freeze or against separation of duties are flagged;
  • changes pushed to the target branches or the default branch without a merge request are recorded as Violations (see Direct changes);
  • the branch protection is checked regularly (see Branch protection check).

Setup status and repair​

The CM status card on the page of a repository under change management reads the setup live from the VCS each time the page opens (not from what Merge Pilot wrote earlier). Each step shows:

ShownAPI statusMeaning
A green check (In place)okThe step is in place
A red cross (Missing), with the reasonfailedThe step is not in place: it failed, or someone changed the repository since
A grey dash, · turned off for this repositoryskippedAn optional step left out at setup

On GitLab, Add the bot user as a member is in place while the bot user has Developer or higher on the project, directly or through a group, as the setup requires. Otherwise its reason reads <bot> is a member below Developer or <bot> is not a member.

Below the steps:

  • the warnings of the live check and of the last setup (for example an optional step that failed, or bypass actors in a GitHub ruleset);
  • Changes can reach the target branches without change management: with the gaps the last branch protection check found;
  • a warning when the repository's webhook could not be updated.

When the live status cannot be read from the VCS at the moment, the card says This repository is under change management, but its setup could not be read from <GitLab or GitHub> now., with the reason, and offers Sync CM.

On the Projects page, the CM status column shows Set up when every step not turned off is in place at the last setup, otherwise Incomplete.

Repairing​

The card's first button writes the steps again, the same steps agreed to before, without asking for consent again:

  • Sync CM when every step is in place (for example after the company's branch patterns changed);
  • Re-run CM setup when a step is missing.

It needs the same rights as setting up (see Who may do what). Each run is recorded as cm_setup. Only one setup of a repository runs at a time: another one meanwhile is refused (409, change management of this repository is being set up right now: try again in a moment).

On GitLab, a run also gives the branch protections Merge Pilot created the connection's current push and merge levels; protections that existed before keep theirs, with a warning (see Branch protection levels).

API: GET /api/v1/projects/cm-status with company_id, repo_id and connection_id reads the live status (steps, warnings); people who are not company admins need some access to the repository (Guest or higher on GitLab, Read or higher on GitHub). POST /api/v1/projects/cm-setup without steps and consent repairs a repository under change management.

Branch protection check​

Someone with enough rights on the VCS can loosen a repository after it was set up: unprotect a branch, allow force pushes, edit the approval rule, add a bypass actor. Merge Pilot looks for that.

  • When. Each time the branch heads of a repository under change management are checked (every 6 hours by default; see Direct changes); when the company turned the head check off (Check branch heads every (hours) at 0), still every 6 hours. In both cases only as long as the company's Check gated projects' branch protection and warn when it lets changes skip the merge gate is on (the default).
  • What it reports. What lets a change reach a target branch without the merge gate: for example a target branch someone may push to directly, a branch that allows force pushes, an approval rule that is missing or names other approvers, approval settings that were unlocked, or a GitHub ruleset that is missing, not enforced, lacks a chosen rule, or has bypass actors. Steps turned off for the repository at setup are not reported.
  • What happens when it changes. When the gaps found differ from the last check:
    • new gaps are recorded as protection_weakened in the audit log and announced as Branch protection weakened (Changes can reach the target branches of <repository> without change management: and the list), when the company announces direct changes;
    • when no gap is left, protection_restored is recorded.
  • Where it shows. On the repository's page (see Setup status and repair) and in the API as protection (weakened, a list of texts, and checked_at).

To close a gap, fix it in the VCS, or select Re-run CM setup / Sync CM, which writes the steps again.

Changing the branches​

The target and excluded branches of a repository under change management can be changed on its page (see Branches). Saving sets the gate up again in the repository for the new branches at once; when that fails, the branches are not changed (the gate could not be moved to the new branches (they were not changed): …). Gating fewer branches needs the right to remove change management.

On GitLab an approval rule cannot leave one branch out of a wildcard. With release/* as a target branch and release/legacy excluded, GitLab's rule for release/* also covers release/legacy. Merge Pilot then approves merge requests into the excluded branch without checking them (again after each push), records nothing for them, and says once on the merge request that the branch is excluded. Likewise a target pattern an exclusion covers only in part (release/** with release/* excluded) stays protected, and merge requests into the excluded branches are approved this way. On GitHub the ruleset leaves excluded branches out itself.

Moving back to watching​

On the page of a repository under change management, Switch to watching asks Switch this repository to watching?: Merge Pilot's gate rule is removed and nothing more is written to its merge requests; they are only recorded. Branch protection set up in <GitLab or GitHub> stays.

  • Removed: on GitLab the approval rules; on GitHub the ruleset (with its rules). On GitLab, when an approval rule of Merge Pilot cannot be removed, the switch fails and the repository stays under change management.
  • Kept: on GitLab the branch protection, the bot user's membership and the approval settings, unless Also take back what change management created is ticked: then the protections and membership Merge Pilot added are removed and the settings it changed put back (see What change management created). The event delivery is set up again as for any watched repository (on GitLab, Merge Pilot's project webhook).
  • The open merge requests are watched from then on.
  • When the event delivery cannot be set up again, the repository is watched anyway and the problem is shown (Events are not delivered: …).

It needs the Remove change management permission (company admins always may) and, for everyone else, the rule's minimum role on the repository.

API: PUT /api/v1/projects/{id}/mode with mode: "monitor". Audit: project_mode_changed.

Removing change management​

On the page of a repository under change management, Remove CM asks Remove change management from <repository>?: Merge Pilot's merge gate and webhook are removed from <GitLab or GitHub>. Merge requests in this project are then no longer governed by its change policies or audited.

  • Also take back what change management created (off by default) removes, on GitLab, the branch protections and the bot membership Merge Pilot added and puts back the approval settings it changed; anything that was there before stays. The approval settings go back first: when GitLab refuses, nothing is removed. A branch protection or the bot membership GitLab refuses to remove does not stop the removal: it completes, and the page lists what was left on GitLab, to remove by hand (see What change management created).
  • What each step leaves behind is in the step tables (GitLab, GitHub): on GitLab the approval rules and the webhook are deleted and the branch protection stays; on GitHub the ruleset is deleted.
  • On GitLab only the approval rules Merge Pilot named Merge Pilot — <branch> are removed; a rule of your own, such as Merge Pilot reviewers, is never touched. The rules go first, then the webhook.
  • When GitLab keeps a rule or the webhook, the removal fails, says what is left and why, and the repository stays under change management: a rule left behind would hold every merge for an approval Merge Pilot no longer gives. The usual cause is that Merge Pilot's account lost Maintainer on the project (Merge Pilot's account is no longer a Maintainer of the project); give it back and try again. When GitLab no longer offers approval rules at all (for example after a licence downgrade), the removal completes.
  • The project is taken out of Merge Pilot. Its vulnerability inventory and analyses are deleted; its recorded merge requests stay, and its direct changes stay until the company's retention removes them.
  • Automatic watching leaves the repository out until someone adds it again.

It needs the Remove change management permission (company admins always may) and, for everyone else, the rule's minimum role on the repository. A watched repository is refused (the repository is watched: stop watching it from its page), as is a repository that is not in Merge Pilot for the company.

To keep recording the repository, switch it to watching instead.

API: POST /api/v1/projects/cm-remove with company_id, repo_id, connection_id and undo_setup; it answers left_on_vcs, what GitLab refused to take back. Audit: cm_remove.

Removing a repository the VCS no longer answers for​

A repository that was deleted or moved on the VCS, that the GitHub App can no longer reach, or whose connection's token was revoked, cannot be removed the usual way, and its connection cannot be deleted while it is in Merge Pilot. While the VCS still answers for the repository, Remove from Merge Pilot only is refused (409, the VCS still answers for this repository: remove change management (or stop watching it) the usual way), so nothing Merge Pilot set up is left behind on a repository that can still be cleaned. When the GitHub App loses a repository, its page says GitHub no longer gives Merge Pilot access to this repository, until the access is given back.

On the repository's page, a company admin selects Remove from Merge Pilot only and writes why it cannot be removed the usual way (at least 5 characters). Nothing is changed on the VCS:

  • The project is taken out of Merge Pilot, as with removing change management; its open merge requests are no longer followed.
  • The page lists what Merge Pilot had set up on the VCS, as its records say: the approval rules or the ruleset, branch protection, the bot user's membership, the approval settings, the webhook. Remove them on the VCS by hand; until then they may hold merges.
  • It is recorded as project_forgotten, with the reason and the list.

API: POST /api/v1/projects/{id}/forget with reason.

One connection per repository under change management​

Two connections to the same GitLab or GitHub, in one company or in two, cannot both have a repository under change management: both would write the same rules for different Merge Pilot accounts. The second setup is refused (409, the repository is under change management through another connection (…): a repository can be under change management through one connection only; it can still be watched through this one). The second connection can still watch the repository; each connection's webhook is its own and is removed alone.

Limits​

  • A bulk operation moves at most 10,000 repositories (see Bulk operations).
  • Automatic watching sets up at most the company's Repositories one round adds (500 by default) new repositories per check (see Automatic watching).
  • One repository of a connection is one project per company.

API​

ActionRequest
Set up a repository not in Merge Pilot yet, or repair one under change managementPOST /api/v1/projects/cm-setup with company_id, repo_id, connection_id, steps, consent
Take a repository out of Merge Pilot without touching the VCS (company admins)POST /api/v1/projects/{id}/forget with reason; 409 while the VCS still answers for the repository
Move a watched project to change managementPUT /api/v1/projects/{id}/mode with mode: "gated", gate_open, steps, consent: true
Open merge requests and their decisionsGET /api/v1/projects/{id}/mode-impact
Live setup statusGET /api/v1/projects/cm-status with company_id, repo_id, connection_id
Switch to watchingPUT /api/v1/projects/{id}/mode with mode: "monitor"
Remove change managementPOST /api/v1/projects/cm-remove with company_id, repo_id, connection_id, undo_setup
The connection's setup steps and their defaultsGET /api/v1/connections/{id}/cm-steps
Many repositoriesPOST /api/v1/projects/bulk with kind to_gated, add_gated or to_watching (see Bulk operations)

A required step the VCS refused answers 422 with the step; other failures 500. Missing permission answers 403 (this connection does not let people set up change management through Merge Pilot, your Merge Pilot role cannot set up change management through this connection, or this needs at least Maintainer on this repository in GitLab (you have Developer)).

Audit actions​

ActionWhen it is written
cm_setupA repository was set up or repaired, with the steps written. Also per repository of a bulk add_gated operation, and for repositories set up by automatic watching (as Merge Pilot). A failure is recorded too
project_mode_changedA project moved between watching and change management, with from, to, gate_open and the steps written. A failure is recorded too
cm_removeChange management was removed. A failure is recorded too
protection_weakened, protection_restoredThe branch protection check found new gaps, or none left

See the Audit log page for every action.

Video tutorial

Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →

Put a GitLab Repository Under Change ManagementYouTube ↗