Skip to main content

Repositories settings

The company's Repositories tab sets how Merge Pilot follows the company's repositories: whether new repositories are watched automatically and in which mode, how much history a newly watched repository brings in, whether watched merge requests are scanned, and what is done about direct changes, changes that reach a watched branch without a merge request.

The repositories themselves are listed and managed on the Projects page (see Repositories).

Where to find it​

Administration → Company (platform admins: Administration → Companies → the company), tab Repositories. The company page opens for company admins and platform admins only.

The tab has two cards: Watching repositories and Direct changes. Both are saved with Save changes in the bar at the bottom of the company page, together with the other tabs (PUT /api/v1/companies/{id} with the monitoring and direct_changes objects). They are applied when saved; four-eyes review does not hold them.

Two related settings are on other tabs of the company page:

  • Branch patterns (General tab): which branches are followed. See Branch patterns below.
  • Watched repositories and Direct changes under What is announced (Notifications tab): whether watched repositories and direct changes send notifications.

Watching repositories​

Watched repositories' merge requests are recorded as change management would decide them; nothing is written to the repositories. Move a repository to change management from its page when you are ready. What watching means is described in Watching repositories.

Setting (label in the UI)What it doesDefaultAllowed valuesSet whereWho can change itAPI field
Watch new repositories automaticallyRepositories the company's VCS connections can reach and that are not in Merge Pilot yet are added on their own, in the mode below. Each active VCS connection is checked at the interval below; a GitHub App's repositories are also picked up as soon as the App gains them (installation events)OffOn, offCompanyCompany admins, platform adminsmonitoring.auto_watch
New repositories are addedWhat a repository found automatically starts as. Watched only: it is watched; nothing is written to it. Under change management: Merge Pilot writes to each new repository at once: the setup steps the VCS connection has on by default (branch protection, approval rule or ruleset, webhook), with the connection's defaults as consent. Shown while automatic watching is on. Repositories you add yourself are watched or set up as you chooseWatched onlymonitor, gatedCompanyCompany admins, platform adminsmonitoring.default_mode
Check for new repositories every (minutes)How often each VCS connection is checked for new repositories. Shown while automatic watching is on6015 to 1,440CompanyCompany admins, platform adminsmonitoring.discovery_minutes
Watch only repositories matchingAutomatic watching takes only repositories whose path matches one of these patterns (for example acme/*, platform/**; a regular expression is refused). Shown while automatic watching is onEmpty: every repositoryPath patternsCompanyCompany admins, platform adminsmonitoring.auto_watch_include
Never watch repositories matchingRepositories whose path matches one of these are left out of automatic watching, even when an include pattern matches. They can still be watched by handEmptyPath patternsCompanyCompany admins, platform adminsmonitoring.auto_watch_exclude
Skip forksForks are not watched automaticallyOffOn, offCompanyCompany admins, platform adminsmonitoring.auto_watch_skip_forks
Repositories one round addsAt most this many new repositories per round; the next round goes on with the rest5001 to 5,000CompanyCompany admins, platform adminsmonitoring.discovery_max_per_round
Repositories one listing readsA connection reaching more repositories than this stops automatic watching with an error. Only repositories the include and exclude patterns and Skip forks take are counted20,000100 to 100,000CompanyCompany admins, platform adminsmonitoring.discovery_max_listed
Import past merge requests (days)When a repository is first watched, its merge requests merged in this many days are imported and evaluated as change management would have, for the monitoring report (0, the default: none — only what happens from then on is recorded; at most 365). Merge requests open when a repository is watched or put under change management are evaluated either way. They are recorded as watched, as change management would have decided them (job project_backfill)0 (none)0 to 365CompanyCompany admins, platform adminsmonitoring.backfill_days
List open merge requests every (hours)Finds merge requests Merge Pilot never heard of: their webhook was lost. Each repository's open merge requests are listed on the VCS this often, and those Merge Pilot does not follow yet are processed. They are also listed when a repository is watched or put under change management, whatever this says (merge requests open before it was added). A listing that fails is tried again one interval later; repositories of a connection that is turned off are not listed. At most 2,000 open merge requests are listed per repository: a repository with more is audited as open_mr_sweep_capped, and the rest are found by their webhooks only. 0 never lists them afterwards60 to 168CompanyCompany admins, platform adminsmonitoring.open_mr_sweep_hours
Also scan imported merge requests for secrets and vulnerable dependenciesRuns the scans on imported merge requests too. Many diff reads and vulnerability lookups for a long history. Only while Scan watched merge requests… is onOffOn, offCompanyCompany admins, platform adminsmonitoring.backfill_scans
Scan watched merge requests for secrets, vulnerable dependencies and licensesRuns the secret scan, dependency scan, license and package health checks on watched merge requests. Only for merge requests whose policy runs the scan. The CI configuration check and the commit signature check count as scans too. While it is off, the scan controls of watched merge requests are skipped and Re-scan is refused (scans are off for watched repositories)OnOn, offCompanyCompany admins, platform adminsmonitoring.scans

How automatic watching works​

  • Each round reads every repository the connection can list and adds at most Repositories one round adds (500 by default) new ones that the include and exclude patterns and Skip forks allow; the rest follow in the next rounds.
  • When automatic watching would take more of a connection's repositories than Repositories one listing reads (20,000 by default), nothing is added: its check fails with automatic watching takes more than N of the connection's repositories, more than one listing reads (Company → Repositories → Repositories one listing reads): raise it, narrow automatic watching with include or exclude patterns, or watch them with bulk operations on the Projects page (see Bulk operations). Only the repositories the include and exclude patterns and Skip forks take count towards that number, so narrowing automatic watching with patterns helps a connection that reaches very many repositories.
  • Repositories already in Merge Pilot, in either mode, are left as they are. With New repositories are added set to Under change management, a repository already under change management through another connection is watched instead.
  • A repository someone removed from Merge Pilot is not added again automatically; it comes back only when someone adds it.
  • A repository that could not be added is tried again after 6 hours.
  • Each repository added is audited as project_watched (or cm_setup when it is put under change management), by Merge Pilot, with automatic in the details.
  • In Under change management, a new repository is set up with the VCS connection's default setup steps (see VCS connection settings); its past merge requests are not imported.
  • The outcome of each connection's last scheduled check is kept on the connection and shown under the switch while automatic watching is on: <connection>: last checked <when>, N repositories added., or, when the check failed, <connection>: the check <when> failed: <error>. In the API it is the VCS connection's discovery object (at, added, error).

Importing past merge requests​

  • The import runs once, when a repository is first watched (by hand, in a bulk operation or automatically). The period is counted back from that moment.
  • A repository moved to change management before its import ran imports nothing.
  • Import past merge requests on a watched repository's page imports the period again: merge requests imported before are judged again with the current policies, and those recorded as they happened are left as they are. While the company imports nothing (0 days) it is not offered; the page says instead: Past merge requests are not imported: the company imports no history (Company → Repositories → Import past merge requests).
  • The Projects page shows the progress under Background work (Past merge requests of N repositories are still being imported).

Direct changes​

Changes that reach a watched branch (a target branch or the default branch) without a merge request: direct pushes, force pushes and deleted branches. On projects under change management they are violations; on watched ones they are recorded as what change management would have blocked. How direct changes are found, classified and shown is described in Direct changes.

A watched branch here is the repository's default branch and every branch its target branch patterns match (the project's own patterns, else the company's branch patterns), except the project's excluded branches. The default branch is always watched.

Setting (label in the UI)What it doesDefaultAllowed valuesSet whereWho can change itAPI field
Receive push eventsThe repositories' webhooks deliver pushes to the watched branches, so a direct change is found as it happens, with who pushed it. On GitLab the project webhooks are updated to deliver pushes. A GitHub App needs the Push event turned on in its settings (the connection shows it when missing). Turning it off asks first (Pushes stop being delivered: changes made without a merge request are found only by the head check, later and without who pushed them.); pushes that still arrive are then ignoredOnOn, offCompanyCompany admins, platform adminsdirect_changes.receive_pushes
Check branch heads every (hours)Catches changes no push event reported: one VCS call per watched branch. Each repository's watched branches are compared with the heads Merge Pilot last saw (job branch_check). The branch protection check below runs with it. 0 turns the head check off; the branch protection check then still runs every 6 hours60 to 168CompanyCompany admins, platform adminsdirect_changes.head_check_hours
Record and report them (Insights, compliance and monitoring reports, audit log)Keeps each direct change, lists it under Insights → Direct changes and in the reports, and writes it to the audit log. Turning it off asks first (Direct changes stop being recorded: they no longer appear in Insights, the compliance report or the audit log.)OnOn, offCompanyCompany admins, platform adminsdirect_changes.record
Refresh the vulnerability inventory when one changes a dependency manifestA direct change to the default branch that changes a dependency manifest starts an analysis of the default branch, so the vulnerability inventory follows it (job vuln_refresh)OnOn, offCompanyCompany admins, platform adminsdirect_changes.refresh_dependencies
Pushes not reported as direct changesAccounts ("*" wildcards) whose pushes to watched branches are recorded as ignored: no violation, no notification. For example release bots and mirrors (release-bot, mirror-*). Matched against the user name of the account that pushed, ignoring case; only * is a wildcard. Projects may add their own; Merge Pilot's own account is always left out.EmptyAccount names, typed one at a timeCompany; each project can add its own listCompany admins, platform adminsdirect_changes.ignore_list
Check gated projects' branch protection and warn when it lets changes skip the merge gateFor repositories under change management, asks the VCS whether its branch protection lets changes skip the merge gate. A new finding is audited as protection_weakened (and announced while direct change notifications are on); a fixed one as protection_restored. Setup steps the project did not agree to are not counted as gaps. Turning it off asks first (Gated projects' branch protection is no longer checked: a rule that lets changes skip the merge gate goes unnoticed.)OnOn, offCompanyCompany admins, platform adminsdirect_changes.protection_check

Turning one of the three confirmed switches off (Receive push events, Record and report them…, Check gated projects' branch protection…) opens Turn this off? with Turn off.

How the branch head check works​

  • It runs in the background for every repository of the company, in both modes, once per interval. Repositories never checked go first.
  • It looks at up to 50 watched branches per repository. Branch patterns with wildcards are matched against the repository's branch list.
  • The first time a branch is seen, its head is only remembered: what happened before Merge Pilot looked is not judged.
  • A head that moved since, or a branch that disappeared, is classified like a push. The head check does not know who pushed, so the ignore list cannot apply to what it finds.
  • A change found by both a push and the head check is recorded once.
  • The Projects page warns under Background work when repositories are checked later than set (N repositories' branches are checked later than set (Company → Repositories).).
  • With Check branch heads every (hours) at 0, no heads are read, but the branch protection check of the repositories under change management still runs, every 6 hours (while Check gated projects' branch protection… is on).
  • Nothing is checked for an inactive company; its direct changes older than the retention period are still removed.

Pushes by Merge Pilot and ignored accounts​

  • Pushes by the VCS connection's own account (Merge Pilot) are never recorded.
  • Pushes by an account on the ignore list (the company's or the project's) are recorded as ignored: no violation, no notification. While recording is on they are audited as direct_change_ignored.

How long direct changes are kept​

Direct changes are deleted once a day after the number of days set as Keep fixed vulnerabilities, old analyses and direct changes (days) on the Scanning tab (365 by default); see Scanning → Vulnerability tracking.

Branch patterns​

Branch patterns are set on the company's General tab (see General). They decide which merge requests Merge Pilot follows (those into a matching branch), which branches change management protects, and which branches are watched for direct changes. "Repository default branch" is each repository's own (main, master, develop…); add any other branch or pattern your changes go through before production (prod-release, release/*, hotfix/**). A project may set its own.

  • Repository default branch, main and master are one click each; other branches and patterns are typed in.
  • In the API, Repository default branch is the token ~DEFAULT_BRANCH. A new company starts with it alone.
  • The list cannot be empty (refused with 400, branch_patterns cannot be empty).

When the webhooks are updated​

Changing the Branch patterns or Receive push events updates the webhook of every registered repository of the company, a batch at a time (job events_sync). The Projects page shows the progress under Background work (Updating the repositories' webhooks: N of M.), and the repositories whose webhook could not be updated. If the update stops part way (The webhook update stopped after N of M repositories), change the setting again to finish it.

Repositories under change management that follow the company's patterns (with no target branches of their own) get their gate set up again for the new patterns in the same run: the new patterns are protected and get their approval rules (GitLab) or ruleset branches (GitHub). One whose gate cannot be moved says so on its page (The gate could not be moved to the company's branch patterns: …).

API fields​

FieldValues
monitoring.auto_watchtrue, false (default)
monitoring.default_modemonitor (default), gated
monitoring.discovery_minutes15 to 1,440 while auto_watch is on (default 60)
monitoring.auto_watch_include, monitoring.auto_watch_excludePath patterns (default empty)
monitoring.auto_watch_skip_forkstrue, false (default)
monitoring.discovery_max_per_round1 to 5,000 (default 500)
monitoring.discovery_max_listed100 to 100,000 (default 20,000)
monitoring.backfill_days0 to 365 (default 0: none)
monitoring.open_mr_sweep_hours0 (never) to 168 (default 6)
monitoring.backfill_scanstrue, false (default)
monitoring.scanstrue (default), false
monitoring.notifyNotifications for watched repositories (Notifications tab); false by default
direct_changes.receive_pushes, record, refresh_dependencies, protection_checktrue (default), false
direct_changes.notifyNotifications for direct changes (Notifications tab); true by default
direct_changes.head_check_hours0 to 168 (default 6; 0: head check off, branch protection check every 6 hours)
direct_changes.ignore_listAccount names, * wildcards; empty entries are dropped
branch_patternsBranch names and patterns, ~DEFAULT_BRANCH for the repository's default branch; not empty

The monitoring object is saved as a whole: send every field. In direct_changes, a switch left out keeps its default (on).

Audit log​

ActionWhen
update_companyThe company's settings were saved, with what changed
project_watched, cm_setupA repository was added by automatic watching (by Merge Pilot, with automatic in the details)
direct_change, direct_change_violation, direct_change_ignoredA direct change was recorded
protection_weakened, protection_restoredThe branch protection check found a gap, or found it fixed

See Audit log → Projects and Audit log → Direct changes and branch protection.