Direct changes
Change management only sees what goes through merge requests. A direct change is a change that reached a watched branch without one: a direct push, a force push that rewrote the branch's history, or a deleted branch. Merge Pilot finds these, records them and reports them, so a change that skipped review does not go unnoticed:
For a short overview of what it is for, see the Direct changes feature page.
- on a repository under change management a direct change is a Violation: something got past the merge gate;
- on a watched repository it is marked Would have been blocked: part of the evidence of what change management would change.
Which branches are watched
For each project, the default branch of the repository and its target branches (the project's own patterns, else the company's, less the project's excluded branches). Pushes to other branches and to tags are ignored.
How changes are found
Two ways, which complement each other. A change both find is recorded once.
A change is the branch moving on from the head Merge Pilot last saw:
- Only the push (or head check) that starts from that head records the change. The same push delivered again, or a push whose change the head check already found, is not another change.
- A branch deleted, restored (even at the same commit) and deleted again is a change each time, as is a branch pushed back and forth.
- Pushes made one right after another are recorded in their order, each with its pusher: a push waits for the push before it to be classified, up to 10 minutes after it arrived, and the head check leaves a branch whose push is still being classified to its next round. A push whose classification failed and is waiting to be tried again does not hold the head check back; the change is then recorded as found by the head check, without a known pusher.
- A push delivered out of order (it does not start from the head Merge Pilot has, and the push before it did not arrive within those 10 minutes) is not recorded on its own. The next head check records the change from the last head Merge Pilot saw to the current one, so it shows up later (within the company's Check branch heads every (hours)), as found by the head check, without a known pusher.
Push events
With the company's Receive push events on (Company → Repositories, on by default), the VCS tells Merge Pilot about every push:
- GitLab: Merge Pilot's project webhook delivers push events for the target branches and the default branch (see The webhook). Changing this setting or the branch patterns updates the webhooks of every project in the background; the Background work box on the Projects page shows the progress.
- GitHub: the App's webhook delivers pushes, when the App has the Push event (see Events the App subscribes to).
A push names who pushed it. Each push to a watched branch is classified in the background (job branch_change).
Branch head check
Every N hours (the company's Check branch heads every (hours), 6 by default, at most 168, 0 turns it off; the head check does not run for an inactive company), Merge Pilot reads the head commit of each watched branch of each project and compares it with the last head it saw. A head that moved without a push event explaining it is classified as a change, and a branch that disappeared as a deletion. This catches what a lost webhook or an App without the Push event would miss.
- A branch seen for the first time only sets the starting point: what happened before Merge Pilot looked is not judged.
- A branch Merge Pilot saw deleted that is there again is classified as a new branch.
- Branch patterns (such as
release/*) are matched against the repository's branches; at most 50 branches are checked per repository. - The head check does not know who pushed: the change shows Not known (head check).
- The check runs as a background job (
branch_check) at the lowest priority, below live events. For a repository under change management, it also runs the branch protection check, which keeps running every 6 hours when the head check is turned off. - When checks fall behind the interval, the Background work box on the Projects page says how many repositories are checked later than set.
What counts as a direct change
For each change, Merge Pilot reads its commits (from the old head to the new; for a new branch, from the default branch) and asks the VCS, for each commit, through which merged merge request it reached the branch.
- All commits came through merge requests, and the branch was neither force-pushed nor deleted: not a direct change; nothing is recorded.
- A merge request change management did not approve: on a branch under change management, the commits of a merge request that merged without Merge Pilot's approval for the commit it merged, or that Merge Pilot never saw, count as direct (not approved by change management). Merge requests opened while the repository was watched count as approved.
- A merge commit whose merged-in side came through a merge request counts as coming through it.
- A force push (the new head does not contain the old one) and a deleted branch always count.
- Merge Pilot's own account (the GitLab connection's bot user, or the GitHub App) is never reported.
- At most 100 commits of one change are looked up; commits not looked up count as not from a merge request.
How a change is marked
| Mark (label in the UI) | API | Meaning |
|---|---|---|
| Violation | violation: true | On a repository under change management |
| Would have been blocked | would_have_blocked: true | On a watched repository |
| Ignored account | class: "ignored" | Pushed by an account on an ignore list (below): neither a violation nor would have been blocked |
| Force push | forced: true | The branch's history was rewritten |
| Branch deleted | deleted: true | The branch was deleted |
| Head check | via: "head_check" | Found by the head check (otherwise via: "push") |
class is direct when no commit came through a merge request, mixed when some did (the details show Came partly through: and the merge requests), and ignored for ignored accounts.
Ignore lists
Some accounts push to protected branches on purpose: release bots, mirrors. Their pushes are recorded as Ignored account instead: no violation, no notification, not counted as would have been blocked.
| List | Where | Who changes it | API |
|---|---|---|---|
| The company's list (Pushes not reported as direct changes) | Company → Repositories; see Company repository settings | Company admins | direct_changes.ignore_list on the company |
| A project's own list (Pushes recorded as ignored) | The project's Overview tab (see Project page) | Company admins; auditors read it | PUT /api/v1/projects/{id}/push-ignore with logins; read as push_ignore_list |
Both lists apply to a project. Entries are VCS usernames, compared ignoring case; * is the only wildcard (mirror-*), so a name such as dependabot[bot] is matched literally. Empty entries are dropped. A change found by the head check has no known pusher and is never ignored.
Changing a project's list is recorded as update_project_push_ignore.
What Merge Pilot does with a direct change
The company's settings (Company → Repositories, all on by default) decide:
| Setting | What it does |
|---|---|
| Record and report them (Insights, compliance and monitoring reports, audit log) | Keeps the change and writes it to the audit log. Off: direct changes are not kept or reported |
| Refresh the vulnerability inventory when one changes a dependency manifest | When a change to the default branch touched a dependency manifest, the project's vulnerability inventory is brought up to date. With recording off it still is: the findings and the analysis name the push by its branch and commit |
| Company → Notifications → Direct changes | Announces the change (below) |
What is kept
For each change: the project, branch, mode of the project at the time, the old and new head, whether it was forced, created or deleted, who pushed it, how it was found, the number of commits and of commits without a merge request, the merge requests some commits came through, the dependency manifests changed, and whether the vulnerability inventory was refreshed.
For each commit: its SHA, author, author email, title (the first line of the message), the number of files changed, the manifests it changed and the merge request it came through. Never the commit's content. At most 50 commits are kept per change, the newest; the rest are counted (N more commits not kept).
Direct changes are kept as long as the company's Keep fixed vulnerabilities, old analyses and direct changes (days) (365 days by default); older ones are removed once a day. They stay after the project leaves Merge Pilot, as evidence, until then.
Where to see them
Insights → Direct changes
For company admins, policy managers, auditors and platform admins.
The cards count the last 30 days:
| Card | Counts |
|---|---|
| Direct changes | Every change, ignored accounts included |
| Violations | On branches under change management |
| Would have been blocked | On watched branches |
| History rewritten | Force pushes and deleted branches |
Who pushed most and Projects with most list the top five, leaving out ignored accounts.
Below, Changes lists them, newest first, 25 a page:
| Filter (label in the UI) | Options |
|---|---|
| Search direct changes | Matches the project, the pusher, a commit SHA, a commit title or author |
| Kind of change | Every change, Violation, Would have been blocked, Ignored account, Force push, Branch deleted |
| Found by | Push or head check, Push event, Head check |
| Column (label in the UI) | Shows |
|---|---|
| Detected | When it was found |
| Project | The repository; select it to open its page |
| Branch | The branch |
| Pushed by | The VCS username, or Not known (head check) |
| What happened | The marks above |
| Commits without a merge request | N of M (empty for a deleted branch) |
Detected, Project, Branch and Commits without a merge request can be sorted. Expanding a row shows the old and new head, the manifests changed (and vulnerability inventory refreshed), the merge requests some commits came through (not approved by change management where that applies), and each commit with a link to it on the VCS and its merge request or No merge request.
Download CSV exports the filtered list, at most the newest 20,000 (a larger export says so), with the columns Detected, Project, Branch, Mode, Class, Violation, Would have been blocked, Pusher, Found by, Forced, Deleted, Commits, Commits without a merge request, Merge requests, Manifests changed, Before, After and Commit titles. Commit titles lists every direct commit (its short SHA and title): those of no merge request and those of a merge request merged without change management's approval.
Elsewhere
- A project's Direct changes tab lists that project's changes (see Project page).
- The monitoring report counts the direct changes of watched repositories.
- The audit log has an entry for each.
Notifications
When the company announces direct changes (Company → Notifications → Direct changes, on by default), each direct change that is not by an ignored account is sent to the notification routes that take the event Direct change to a watched branch (direct_change), and emailed to the company admins who did not turn it off (see Personal notifications). For a watched repository it is sent only when the company also announces Watched repositories. Each change is sent once, however many times its push is delivered and whether the head check found it too.
The first direct change to a branch is sent at once. Further direct changes to the same branch within the next 15 minutes are recorded and audited as usual, and sent together when the 15 minutes end, in one notification of the same event: N more direct changes to <branch>, with who pushed them, how many commits did not come from a merge request, and the branch's head after the last one (or that the last one deleted the branch). A direct change after the 15 minutes is sent at once again and starts a new 15 minutes.
The notification's title is Direct change to <branch>. Its text says what happened:
- <pusher> pushed N commits to <branch> of <repository> without a merge request
- <pusher> force-pushed <branch> of <repository>, rewriting its history (N commits not from a merge request)
- <pusher> deleted the branch <branch> of <repository>
followed by . The branch is under change management: this is a violation or . Change management would have blocked it. When the head check found the change, the pusher reads Someone (found by the head check). The message links to the project's page.
Audit actions
| Action | When it is written |
|---|---|
direct_change | A change reached a watched branch without a merge request (watched repository) |
direct_change_violation | Such a change reached a branch under change management |
direct_change_ignored | Such a change was made by an ignored account |
update_project_push_ignore | A project's ignore list was changed |
The first three are made by Merge Pilot, with the project, branch, pusher, how it was found, the old and new head, whether it was forced or deleted, the commit counts and the class. They are written only when the company records direct changes.
API
The direct changes of a company are read by company admins, policy managers, auditors and platform admins.
| Action | Request |
|---|---|
| List | GET /api/v1/companies/{id}/direct-changes |
| Summary of the last 30 days | GET /api/v1/companies/{id}/direct-changes/summary with optional project_id; answers total, by_class, violations, would_have_blocked, forced, deleted, top_pushers and top_projects |
| CSV | GET /api/v1/companies/{id}/direct-changes.csv with the list's filters |
| A project's ignore list | PUT /api/v1/projects/{id}/push-ignore with {"logins": [...]} (company admins) |
The list takes project_id, branch, class (direct, mixed, ignored), violation, would_have_blocked, forced, deleted (true or false), via (push, head_check), since and until (RFC 3339), q, page, page_size and sort (detected_at, project, branch, commits; - in front for descending; newest first by default).
A direct change has id, project_id, vcs_connection_id, repo_id, project_path, project_url, branch, project_mode, before, after, forced, created, deleted, pusher (id, username), via, commits, commit_count, direct_commits, mrs, manifests_changed, class, violation, would_have_blocked, refreshed and detected_at.
Related pages
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →