Monitoring report
The monitoring report answers what would change management have done here? for repositories Merge Pilot only watches. From what it recorded while watching, it decides each merge request again under the current change policies and counts what the merge gate would have been, which controls would have held it, how many change approvals it would have needed, and which merges it would have stopped. It is the evidence for moving a repository from watching to change management.
How watching works, and what is recorded while watching, is described in Watching repositories.
Opening it
- Insights → Monitoring, for every watched repository of the company.
- From a watched repository's page, See what change management would have done: the report of that one project.
- The Move to change management dialog shows the same report for the project in one sentence (see below).
Every role can read it, for their own company. Platform admins see the company selected in the header; without one, the page says Select a company (Pick a company in the header to see what change management would have done with its watched repositories.).
Period and scope
| Choice (label in the UI) | What it does | Default |
|---|---|---|
| Period | 30 days, 90 days, 180 days or 365 days, up to now. A merge request counts when it was first recorded, or merged, in the period | 90 days |
| Project: … | Shown when the report covers one project. The cross (Show all projects) goes back to every watched repository | Every watched repository |
- Which merge requests: those decided while their repository was watched, imported ones included. The report of one project also works after it moved to change management: the merge requests it recorded while watched remain its evidence.
- At most 5,000 merge requests are counted, the newest of the watched repositories in scope (merge requests of other repositories never take their place). When there are more, the page says The period has more merge requests than one report covers; only the newest N are counted. Choose a shorter period or one project.
- Merge requests no policy matches are left out of every count and of the CSV; the page says how many: N merge requests matched no policy and are left out of this report: its counts and the CSV.
- Current policies: each merge request is decided by the policies of its VCS connection as they are now, from what was recorded about it (its changes, scans, reviews, pipelines). Nothing is read from the VCS and nothing is written.
How a merge request is decided
Each merge request gets the merge gate change management would set:
| Outcome | Merge gate | Means |
|---|---|---|
| Would be approved | Approved | Every enforced control passed: change management would let it merge |
| Would wait | Pending | No enforced control failed, but at least one has not passed yet (for example, it waits for an approval) |
| Would be blocked | Blocked | An enforced control failed, or the policy refuses its changes |
A merge request needs a change approval when its policy opens one (and does not refuse the change).
Only enforced controls count in What would hold them: a control that only warns never holds a merge request.
Cards
| Card (label in the UI) | Value | Line below it |
|---|---|---|
| Merge requests | The merge requests counted (those a policy matched) | N merged: those merged in the period |
| Would be approved / wait / blocked | The three outcomes, as A / W / B | The gate change management would have set |
| Would need a change approval | Those whose policy opens a change approval | About N change approvals a week: that number divided by the weeks of the period, with one decimal |
| Merges these policies would hold | Merges in the period whose outcome is not Would be approved | Evaluated now, against the policies of this report |
| Merges held when they merged | Merges in the period recorded as held at the moment they merged, under the policy then in force (what each merge request's clearance track shows as Would have been held) | Recorded at the merge, with the policy then in force (as each merge request shows) |
| Direct changes | Changes pushed to a watched branch without a merge request in the period that change management would have stopped | Pushed without a merge request: change management would have stopped them |
| Merges per week | Merges in the period divided by the weeks of the period, with one decimal | |
| Median lead time | The median time from opened (on the VCS) to merged, over the merges of the period. For an even number of merges, the later of the two middle values. Shown in minutes, hours (under 48) or days; — without merges | From opened to merged |
The two "held" cards can differ: the first uses today's policies, the second what was recorded at each merge. A policy changed since then, or a check that finished after the merge, makes the difference.
Tables
By policy
One row per policy that matched, most merge requests first:
| Column (label in the UI) | Shows |
|---|---|
| Policy | The policy's name |
| Change type | Standard, Normal or Emergency; Refuses for a policy that refuses its changes |
| Merge requests | The merge requests it matched |
| Approved, Would wait, Blocked | Their outcomes |
| Need a change approval | Those that would need a change approval |
What would hold them
One row per enforced control that failed or was waiting at least once, most failures first: Control, Failed (how many merge requests it failed), Waiting (how many it kept waiting). Not shown when no control held anything.
The report decides from what was recorded. Work items that were never looked up for a merge request (its policy then did not check them) count as Waiting, not Failed. For history imported before the policies existed, Import again on the repository's page judges it with the current policies, work items included (see Importing past merge requests).
By project
One row per project in scope, also projects without merge requests in the period, by path. With more than 10 projects, Filter projects narrows them by path; they show 50 at a time (Show more (N left)). Select a project to open its page.
| Column (label in the UI) | Shows |
|---|---|
| Project | Its path |
| Mode | Watching, or Change management for a project that moved since |
| Merge requests, Blocked, Need a change approval | As in the cards, for this project |
| Held merges | Merges these policies would hold |
| Direct changes | Its direct changes change management would have stopped |
Findings
What the scans of the counted merge requests found, merged or not:
- N possible secrets in M merge request(s);
- N new vulnerabilities in M merge request(s): vulnerabilities the merge requests bring in;
- N dependencies with a denied license.
Scans run on watched merge requests only while the company's Scan watched merge requests for secrets, vulnerable dependencies and licenses is on (see Scans on watched repositories).
Risk
The merge requests per risk level (high: 4), when risk was assessed. Not shown otherwise.
Without any counted merge request the page says No watched merge requests in this period with Go to projects (for one project: This project has no recorded merge requests in this period. Choose a longer period, or show all projects. with Show all projects).
Download CSV
Download CSV exports the counted merge requests of the period and scope shown, newest first. It is not offered while the report is empty. The file is named monitoring-<company>-<date>.csv and starts with a byte-order mark so spreadsheets read it as UTF-8. A project, title, author, policy or link that starts with =, +, -, @, a tab or a carriage return is prefixed with ' so spreadsheets do not read it as a formula.
| Column | Shows |
|---|---|
| Project | The project's path |
| Merge request | Its number |
| Title, Author | As on the VCS |
| Opened | When it was opened on the VCS (when the VCS did not say, when Merge Pilot first recorded it; RFC 3339, UTC) |
| Merged | When it merged, or empty |
| Policy, Change type | The policy that matched and its change type (standard, normal, emergency) |
| Would be | approved, pending or blocked |
| Needs change approval | yes or no |
| Merge held under these policies | yes for a merge in the period these policies would hold |
| Merge held when it merged | yes for a merge recorded as held when it merged |
| Failing controls | The enforced controls that failed, separated by spaces (such as ci sca) |
| Imported | yes for a merge request imported from the repository's history |
| Link | The merge request on the VCS |
Before moving to change management
The report shows what a repository's teams would meet under change management:
- Would be blocked and What would hold them show which controls would stop work, and whether the policies need adjusting first.
- Would need a change approval and About N change approvals a week show the load on approvers.
- Merges these policies would hold and Direct changes show what change management would have stopped.
When a repository is moved (its page → Move to change management), the dialog's While watched section sums up this project's report of the last 90 days: N merge requests recorded: B would be blocked, P would wait, C would need a change approval., with the merges that would have been held. See Moving a watched repository to change management.
API
| Action | Request |
|---|---|
| Report | GET /api/v1/companies/{id}/monitoring/report with since and until (RFC 3339; the last 90 days by default; the period must be positive and at most 366 days) and project_id |
| Report under draft policies | POST /api/v1/companies/{id}/monitoring/report with the same parameters and {"policies": [...]}: each merge request is decided by these draft policies instead of the saved ones. Nothing is saved. An empty list is refused (give at least one policy), and each draft must be a valid policy |
| CSV | GET /api/v1/companies/{id}/monitoring/report.csv with the same parameters |
Any member of the company may call them; platform admins any company. Another company's ID answers 404.
The report holds since, until, drafts, truncated, merge_requests, unmatched, merged, approved, pending, blocked, needs_change_approval, would_have_blocked, held_at_merge, direct_changes, change_approvals_per_week, merges_per_week, lead_time_hours, policies[] (name, change_type, deny, count, approved, pending, blocked, needs_change_approval), controls[] (control, failed, pending), projects[] (project_id, repo_id, vcs_connection_id, path, mode, merge_requests, blocked, needs_change_approval, would_have_blocked, direct_changes), findings (secret_mrs, secrets, vulnerable_mrs, vulnerabilities, denied_licenses) and risk (merge requests per risk level).
Reading or downloading the report is not recorded in the audit log.
Related pages
- Watching repositories: watching, automatic watching, importing past merge requests.
- Change management: moving a repository to change management.
- Policies and Controls: what decides the outcome.
- Direct changes.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →