Skip to main content
Video tutorial · 1:02

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 doesDefault
Period30 days, 90 days, 180 days or 365 days, up to now. A merge request counts when it was first recorded, or merged, in the period90 days
Project: …Shown when the report covers one project. The cross (Show all projects) goes back to every watched repositoryEvery 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:

OutcomeMerge gateMeans
Would be approvedApprovedEvery enforced control passed: change management would let it merge
Would waitPendingNo enforced control failed, but at least one has not passed yet (for example, it waits for an approval)
Would be blockedBlockedAn 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)ValueLine below it
Merge requestsThe merge requests counted (those a policy matched)N merged: those merged in the period
Would be approved / wait / blockedThe three outcomes, as A / W / BThe gate change management would have set
Would need a change approvalThose whose policy opens a change approvalAbout N change approvals a week: that number divided by the weeks of the period, with one decimal
Merges these policies would holdMerges in the period whose outcome is not Would be approvedEvaluated now, against the policies of this report
Merges held when they mergedMerges 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 changesChanges pushed to a watched branch without a merge request in the period that change management would have stoppedPushed without a merge request: change management would have stopped them
Merges per weekMerges in the period divided by the weeks of the period, with one decimal
Median lead timeThe 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 mergesFrom 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
PolicyThe policy's name
Change typeStandard, Normal or Emergency; Refuses for a policy that refuses its changes
Merge requestsThe merge requests it matched
Approved, Would wait, BlockedTheir outcomes
Need a change approvalThose 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
ProjectIts path
ModeWatching, or Change management for a project that moved since
Merge requests, Blocked, Need a change approvalAs in the cards, for this project
Held mergesMerges these policies would hold
Direct changesIts 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.

ColumnShows
ProjectThe project's path
Merge requestIts number
Title, AuthorAs on the VCS
OpenedWhen it was opened on the VCS (when the VCS did not say, when Merge Pilot first recorded it; RFC 3339, UTC)
MergedWhen it merged, or empty
Policy, Change typeThe policy that matched and its change type (standard, normal, emergency)
Would beapproved, pending or blocked
Needs change approvalyes or no
Merge held under these policiesyes for a merge in the period these policies would hold
Merge held when it mergedyes for a merge recorded as held when it merged
Failing controlsThe enforced controls that failed, separated by spaces (such as ci sca)
Importedyes for a merge request imported from the repository's history
LinkThe 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​

ActionRequest
ReportGET /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 policiesPOST /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
CSVGET /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.

Video tutorial

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

The Monitoring Report of Watched RepositoriesYouTube ↗