Skip to main content
2 video tutorials

Merge requests

Every merge request (on GitHub: pull request) that Merge Pilot follows has a record in Merge Pilot. The Merge requests page lists them for the selected company; each one has its own page with the decision of its change policy, its change approval and votes, its scans and CI runs, and a timeline of everything Merge Pilot did with it.

Merge requests appear once a repository is watched or under change management and someone opens a merge request into one of its target branches (see Repositories). Watched repositories are listed too, marked Watched: for them the page shows what change management would have done.

Who sees what​

Every role of the company sees the list and every merge request page. Platform admins see every company's merge requests (all companies, or the one selected).

ActionWho may use itWhere it is offered
Sync with <GitLab or GitHub> (list)Everyone except auditorsAlways; Sync with the VCS when the company has both
RefreshEveryoneAlways
ResyncEveryone except auditorsAn open merge request, or one whose change approval (or an earlier, superseded one) Merge Pilot still owes the tracker a move
Open in <GitLab or GitHub>EveryoneAlways
Debug flowPlatform adminsAlways
Re-scan (secret scan, dependency scan, CI configuration check, container image scan, infrastructure check)Everyone except auditorsWhen the scan's card is shown, on an open merge request
Allow riskPeople the policy lets release a risk hold, never the author (see Accepting a risk)An open merge request held by its risk, not watched
Release from the freezePeople the policy lets release a change during a freeze, never the author (see Change freezes)An open merge request held by a change freeze, when its policy allows releases, not watched
Reset usage of <KEY>Company admins, platform adminsNext to a work item reported as already used
Assign to me, Take overPeople who may approve the change, never the authorAn open change approval of an open merge request, not watched
Approve, RejectPeople who may approve the change, never the authorAn open change approval of an open, normal or emergency merge request, not watched
Withdraw (a rejection)Whoever rejected, company admins, platform admins; not when the policy turns it offNext to a rejection in the votes list, on an open merge request (see Changing or withdrawing a vote)

Auditors read everything and act on nothing. The buttons are shown to everyone else who may act on the page; Merge Pilot still checks each action and answers with the reason when the person may not (for example you are not an approver for this change: you …).

The list​

Merge requests in the navigation. The heading counts the merge requests that match the filters, watched ones included (N merge requests at <company>, recorded while their repositories were under change management or watched.). The records stay after a repository is no longer watched or under change management.

Control (label in the UI)What it doesDefaultAPI parameter
Search (Search title, branch, author or repository)Finds merge requests whose title, source branch, target branch, author or repository path contains the textEmptyq
StateAll states, Open, Needs attention, Merged, Closed, Out of scopeAll statesstate (opened, merged, closed, out_of_scope); Needs attention is attention=true
Change typeAll change types, Standard, Normal, Emergency: the change type of the policy that covers the merge requestAll change typeschange_type (standard, normal, emergency)

The state and change type can also be given in the page address (?state=attention, ?change_type=emergency), which is how other pages link to the list.

Needs attention lists the open merge requests that cannot move on without someone acting:

  • refused by their policy;
  • an enforced check failed (Work items, Code review, CI, Secret scan, Dependency scan, Licenses, Package health, Dependency sources, CI configuration, Signed commits) or a risk hold applies;
  • the change approval of a normal change was rejected or could not be opened;
  • a change approval waits for votes, or an emergency change waits for its review.

Watched merge requests never need attention: nothing holds them.

Out of scope merge requests were moved to a target branch that change management does not cover (see Moved to another target branch).

Columns​

ColumnWhat it showsSortable
Merge requestThe title (a link to its page), the repository path and number (!12 on GitLab, #12 on GitHub), source branch into target branch, and Watched (or Imported, for a merge request read from a watched repository's history)Yes, by title
ClearanceThe clearance track (below) with one phrase for where the merge request standsNo
RiskThe risk level (critical, high, medium, low), or — without a risk assessmentYes, by risk score
SecretsA spinner while the secret scan runs, the number of findings (N secrets found), a check mark when none were found, or — without a secret scanNo
AuthorThe author's VCS usernameYes
OpenedWhen the merge request was openedYes (the default: newest first)
(icon)Open in <GitLab or GitHub>No

Select a row to open the merge request. The list loads 50 at a time and loads more as you scroll (Showing all N at the end).

Without merge requests, the page says No merge requests yet with Set up a project; when the search, the state or the change type matches nothing, No merge requests match these filters (Clear the search or change the filters.).

Sync with the VCS​

When the list is opened, and with Sync with GitLab or Sync with GitHub (Sync with the VCS for a company on both), Merge Pilot queues a background check that asks the VCS for the state of the open merge requests. Those that were merged or closed while their webhook was lost are recorded as merged or closed, with their change approval follow-up (see When the merge request is merged or closed); the list shows them once the check has run. The check runs one at a time per VCS connection, at most every 5 minutes when the list opens and every minute from the button, reads at most 300 open merge requests a run (those checked longest ago first) and runs after live work, within the share of the VCS's rate limit left to background work (see Sync with the VCS). The button says what happened: Sync started: merges and closes found will show shortly., A sync is already running. or Synced less than a minute ago.; the list is read again a few seconds later. A platform admin must select a company first. Auditors are not offered the button, and the list does not sync when an auditor opens it; a sync that fails says why.

API: POST /api/v1/merge-requests/sync-states (?force=true from the button) answers queued, running and recent: how many VCS connections got a new check, already had one waiting or running, or were checked within the interval.

The clearance track​

The list and the merge request page show where a change stands as five stages:

Stage (label in the UI)Done whenOther states
PolicyA change policy covers the merge request (the page shows its name and change type)Not processed yet; Refused by policy when the policy refuses its changes
ChecksEvery enforced check passed (the page shows the risk level, or Passed)Running checks while one is pending; Check failed with the control and its reason; Risk hold
Change approvalThe change approval exists (the page shows its key)Creating change approval; not applicable for a standard change (Standard change), a refused change, or a closed merge request
ApprovedThe change approval is approved (the page shows who approved); Pre-approved for a standard change; Reviewed for a reviewed emergency change, also when it was reviewed after the mergeAwaiting approval; Review after merge for an emergency change; Review rejected for an emergency change whose review was rejected (it does not hold or undo the merge); Change approval rejected; Merged before approval
MergedMerged (the page shows who merged)Ready to merge or Can merge; Merged without approval; Closed; Out of scope

Each stage is coloured: done, waiting on a person, on hold, blocked, pending or not applicable. The phrase next to the track is the first stage that stops the change, else the first one still pending.

For a watched merge request the phrase starts with Watched:, the Change approval and Approved stages are not applicable (Would need a change approval, Would need approval), and a merge that change management would have held shows Would have been held.

The merge request page​

Open it from the list, from My Work, or from the command palette (Go to a page or find a merge request).

The title, the repository path and number, source branch into target branch, by <author> and, once merged, merged by <user> on <date>. The back arrow returns to Merge requests. Buttons:

  • Refresh reloads the page.
  • Resync (Read CI and the change approval again from <GitLab or GitHub> and the tracker, and re-evaluate) does at once what the periodic re-check does: it retries a change approval that could not be opened, reads the CI runs of the latest commit and the change approval's status in the tracker again, retries a tracker move that failed, and processes the merge request again. For a merged or closed merge request it only retries the tracker moves Merge Pilot still owes; its record, scans included, stays as it was. Recorded as mr_resync. API: POST /api/v1/merge-requests/{id}/resync; it answers 409 for a merged or closed merge request that owes no move.
  • Open in <GitLab or GitHub>.
  • Debug flow opens the platform admins' debug console for this merge request (see Jobs).

A merge request that does not exist, or belongs to another company, shows Merge request not found.

Banners​

Under the clearance track, the page shows what needs saying:

BannerWhen
Its repository is watched: nothing was written to this merge request in <GitLab or GitHub>. The decision shows what change management would do.The repository is watched
Imported from history when its repository was first watched: it is evaluated as it was when it merged, with the policies of the time of the import. Import again on the repository's page judges it with the current policies.A merge request read from a watched repository's history
Change management would have held this merge: it merged while its decision was not approved.A watched merge request merged while its decision was not Can merge
This change was merged in <GitLab or GitHub> before change management approved it. It is recorded in the audit log.Merged without approval (see What is flagged at merge)
This change was merged during the change freeze "…", which held it. It is recorded as non-compliant.Merged during a change freeze that held it
Would be blocked (watched): this change was merged during the change freeze "…", which would have held it under change management.A watched merge request merged during a change freeze that holds merges
The change approval was withdrawn in the tracker after this change was merged.The approval was moved out of its approved status after the merge
The change approval is out of step with this page. … Move it in the tracker by hand, or fix the tracker connection's statuses and transition paths.Merge Pilot could not move the change approval in the tracker (see Tracker moves that fail)
Declared an emergency by … (label "…", …): policy … lets it merge before it is approved.An emergency change (also An emergency under policy …, opened by … and, when the declarer cannot be read, An emergency under policy …; who declared it is not known: …). The author declared it. is added when the author added the label
Commits by … match no person in Merge Pilot, so separation of duties cannot tell whether an approver wrote them. …An open merge request whose commits match no Merge Pilot user, when someone approves it (a normal or emergency change, or a standard change with a change approval); not for a change its policy refuses or a standard change without one, such as a dependency bot's
Separation of duties: … or Separation of duties broken: …Separation-of-duties flags (see Separation of duties)
This merge request now targets <branch>, which change management does not cover. …Out of scope

Policy card​

The policy that covers the merge request (a link to the policies page), its version (v4), its change type (Normal, Standard, Emergency) and the merge gate: Can merge, Waiting or Blocked. For a watched merge request nothing was held, so the gate reads what change management would have done: Would pass (watched), Would wait (watched) or Would be blocked (watched).

Below it is the decision checklist: one line per control that applies, in the order Work items, Code review, CI, Secret scan, Workflows, Signed commits, Dependency scan, Licenses, Package health, Risk, Change freeze, Change approval. Each line is marked passed, pending, failed (enforced) or failed with (report only), with its reason. Controls that are off or skipped are left out; with none left the card says No checks apply. The line Evaluated <time> for commit <sha> names the commit the decision is for.

Not processed yet means no policy covers the merge request yet; Not evaluated yet, that it has a policy but no decision. What each control checks is on its own page under Controls; how the gate follows the decision is on Merge gate.

Issue tracker card​

  • The work item problems in red (for example a key that is already used), with Reset usage of <KEY> for admins (see Work items).
  • For an emergency change: Emergency change: review due <date>, or review was due <date> once overdue.
  • The change approval: its key (a link to the tracker), its status (open, approved, rejected, cancelled) and covers <sha>, the commit it was opened or last kept for.
  • Earlier change approvals: the change approvals this merge request had before, each with its outcome (superseded, reopened, lost), the reason and the date (see Change approval). When Merge Pilot could not move a superseded change approval to its cancelled status, the entry says so in red (Could not move to cancelled: <reason>); the move is retried on its own, and Resync retries it at once, on a merged or closed merge request too.
  • Assignee: who the change approval is assigned to, by their name in Merge Pilot when the tracker account (for example an email address) is matched to a person; the account itself shows on hover. Otherwise the tracker account, or Unassigned, with No eligible approver: … when nobody could be assigned. Assign to me takes an unassigned change approval, Take over one assigned to someone else (see Taking a change approval).
  • Work items: the keys found, as links to the tracker.

Without a tracker linked to the repository: No issue tracker is connected for this MR.

Approval card​

The change approval's approval: its status (Approved, Rejected, 1 of 2 approvals, or Review pending for an emergency change), Approvals needed for each way to approve, the Votes (each marked in tracker or in Merge Pilot, with by …, standing in for a stand-in), the approval concentration warning, and Approve and Reject. A standard change shows Standard change: pre-approved by its policy, no change approval needed.; a merge request without a change approval, No change approval yet. (No change approval is opened while the repository is watched. when watched).

When the code owners of the changed files cannot be read, the card says so (Code owners could not be read: …), and lists owners that cannot be asked (Not asked from …).

Voting, eligibility and the dialogs are described on Approval.

Risk assessment card​

Shown when the merge request was assessed: the risk score and level, Blocked, Allowed by <user> and Blackout badges, the reason of a hold, the four scores (Change window, Criticality, Footprint, MR size), the lines added and removed, the files changed, the footprint category, binary files, whether it falls in a blackout, and the acceptance (Reason for lifting the hold:). Allow risk opens Lift the risk block?. See Risk.

Scan cards​

Each card has Re-scan (on the dependency scan Re-scan dependencies, on the CI configuration check Check the CI configuration again, on the container image scan Scan the container images again, on the infrastructure check Check the infrastructure files again). A re-scan runs the scan again for the latest commit, and the merge request is evaluated again when it finishes. Only open merge requests are scanned again: a merged or closed one's scans are the record of what merged, so the button is not shown and the API answers 409 (the merge request is merged: only open merge requests are scanned again; its recorded scans stay as they were). It is also refused on a watched repository whose company does not scan watched merge requests (scans are off for watched repositories); the CI configuration check runs only when the policy runs it. A scan already running is not started twice (scan already in progress), and while one card's re-scan is being requested the other cards' re-scan buttons wait. Recorded as secret_rescan, sca_rescan, workflow_rescan, image_rescan or iac_rescan.

API: POST /api/v1/merge-requests/{id}/rescan with scan: secret, sca, workflow, image or iac.

CI/CD pipelines card​

The CI runs Merge Pilot recorded for the merge request: status, name, ref, commit, duration and age, each with a link to the VCS. A run with jobs expands to its jobs, grouped by stage ((allowed to fail) marks jobs allowed to fail). See CI.

Timeline​

Everything that happened to the merge request in Merge Pilot, grouped by head commit, newest commit first. Each group starts with Commit <sha> · pushed <when> (when Merge Pilot first saw the commit); the group of the merge request's current head is marked Current head. Inside a group the events read oldest first. An event that names no commit (for example a vote) sits in the group of the newest commit seen when it happened.

The page loads the latest 100 events (Showing N of M events); Load more (N remaining) loads the next 100 older ones, which can add events to a group already shown or add older commits below it.

The events are:

  • the background jobs that worked on it (Processing, Policy evaluation, Secret scan, Dependency scan, CI configuration check, Container image scan, Infrastructure check, Change approval creation, Change approval assignment, Change approval decision, Pipeline tracking, MR merged, MR closed, Out of scope, Change approval changed (the change approval was moved in the tracker), Merge queue check, Vulnerability refresh, otherwise Job), each with its status, the merge gate it set (for a watched merge request, the one it would have set), the change approval key and the steps it took;
  • the audit entries written for it, with who and when (for example a vote, a superseded change approval, a re-scan). Rejections and blocks are shown in red, approval concentration warnings in amber.

API: GET /api/v1/merge-requests/{id}/timeline with page and page_size (at most 500; default 100), newest first: page 1 holds the latest events, later pages older ones. Each entry has type (job or audit), timestamp, data and, when the entry names one, head_sha (the head commit a job worked on, or the one an audit entry's details name).

API​

ActionRequest
ListGET /api/v1/merge-requests with state, attention, change_type, q, repo_id, watched (true, false), page, page_size (at most 100), sort (title, author, created_at, updated_at, risk; - for descending). Platform admins add company_id
Find by repository and numberGET /api/v1/merge-requests/lookup with repo_id, mr_number and optionally connection_id; answers id
Process one by numberPOST /api/v1/merge-requests/fetch with connection_id, repo_id and mr_number: queues the merge request as if its webhook had arrived (one Merge Pilot never heard of). The repository must be in Merge Pilot (404 otherwise). Answers 202
OneGET /api/v1/merge-requests/{id}
TimelineGET /api/v1/merge-requests/{id}/timeline
Sync statesPOST /api/v1/merge-requests/sync-states
ResyncPOST /api/v1/merge-requests/{id}/resync
Re-scanPOST /api/v1/merge-requests/{id}/rescan
VotePOST /api/v1/merge-requests/{id}/votes with decision and comment
Take the change approvalPOST /api/v1/merge-requests/{id}/assign-me; answers assignee
Accept a riskPOST /api/v1/merge-requests/{id}/risk-allow with reason and head_sha
Release from a change freezePOST /api/v1/merge-requests/{id}/freeze-release with reason and head_sha
Withdraw a rejectionPOST /api/v1/merge-requests/{id}/rejection/withdraw with voter and reason
Reset a work item's usagePOST /api/v1/merge-requests/{id}/work-items/{key}/reset-usage

Voting, withdrawing a rejection, taking a change approval, accepting a risk and releasing from a freeze act as a person: they need a session or a personal API token.

Main fields of a merge request: id, company_id, vcs_connection_id, tracker_connection_id, repo_id, mr_number, title, source_branch, target_branch, author, state (opened, merged, closed, out_of_scope), web_url, head_sha, draft, labels, watched, imported, policy (id, name, version, change_type), decision (head_sha, target_branch, gate, controls[] with control, status, blocking, reason, evaluated_at, needs_change_approval, monitored), issue_tracker, approval, risk_assessment, secret_scan, sca_scan, workflow_scan, signatures, code_owners, pipelines, emergency, committers, sod_flags, sod_violation, merged_by, merged_at, merged_without_approval, merged_in_freeze, would_have_held_in_freeze, would_have_blocked, approval_revoked_after_merge.

Audit log​

ActionWhen
mr_resyncSomeone resynced the merge request
secret_rescan, sca_rescan, workflow_rescan, image_rescan, iac_rescanSomeone started a scan again
risk_allowSomeone accepted the merge request's risk
freeze_releaseSomeone let the merge request go ahead during a change freeze
mr_fetch_requestedSomeone asked Merge Pilot to process a merge request by its number
work_item_usage_resetAn admin reset a work item's usage count
change_approval_voteA vote was cast in Merge Pilot
change_approval_rejection_withdrawnA rejection was withdrawn
change_approval_assign_me, change_approval_taken_overSomeone took the change approval, or took it over
approval_fatigue_detectedThe vote triggered the approval concentration warning

The entries Merge Pilot writes on its own are listed on Merge gate and Change approval, and all of them in the Audit log.

Video tutorials

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

Read the Merge Request PageYouTube ↗
What Developers See in GitLabYouTube ↗