Skip to main content
2 video tutorials

Repositories

A repository that Merge Pilot follows is a project. Each project belongs to one company and one VCS connection, and is in one of two modes:

  • Watching: Merge Pilot records the repository's merge requests and decides them as change management would, but writes nothing to the repository except the delivery of its events. Nothing is blocked. Use it to see what change management would do before you switch it on. See Watching repositories.
  • Change management: Merge Pilot writes the merge gate into the repository, and merges wait for the change policy. See Change management.

A repository can move between the two modes in either direction, one at a time from its project page or many at a time with bulk operations.

Where to find it​

Projects in the main menu. The page shows the projects of the company selected in the header. With more than one VCS connection, a connection selector (Select connection) sits in the page header: it chooses the connection that the search tabs, Watch repositories, Add to change management and the groups button work with. It starts on the company's default VCS connection.

The two modes​

WatchingChange management
Label in the UIWatchingChange management
API value (mode)monitorgated
Written to the repositoryGitLab: one project webhook. GitHub: nothing (the GitHub App's webhook already delivers the events)The setup steps of the connection's VCS: branch protection and an approval rule (GitLab) or a ruleset (GitHub), and the GitLab webhook. See GitLab setup steps and GitHub
Merge requestsRecorded and decided by the policies; nothing is written to them (no merge gate, status comment, change approval or closing)Gated by the policies: status comment, change approval when the policy needs one, merge gate
MergesNever held. A merge that change management would have held is recorded as suchHeld until the policy is met
Changes pushed without a merge requestRecorded as Would have been blockedRecorded as a Violation
ScansRun when the company turns on scans for watched merge requestsRun as the policy says
NotificationsSent only when the company announces events of watched repositoriesSent as routed

Which mode a repository found by automatic watching starts in is a company setting; see Company repository settings.

The page​

The page has these tabs:

Tab (label in the UI)Shows
Registered projectsThe company's projects, of every connection
Search <connection>A search of the selected connection's repositories by name. Shown to company admins, platform admins and people the connection allows Set up change management

Selecting a repository in any tab opens its project page.

Buttons in the page header​

Button (label in the UI)What it doesShown to
Watch repositoriesOpens the dialog to watch repositories that are not in Merge Pilot yet (see Watching repositories)Company admins and platform admins, and people the selected connection allows Set up change management. Not to auditors
Add to change managementOpens the dialog to put repositories that are not in Merge Pilot yet straight under change management (see Adding repositories straight to change management)The same as Watch repositories
<connection> groupsLists the connection's GitLab groups, with a search, and lets you join a group (Join as Developer, or the highest role people may give themselves) or Leave it, after Leave the group <name>? (you give up your role in the group and in every project in it)GitLab connections only; company admins and platform admins, and people the connection allows Join groups (see Permissions)

Registered projects​

Above the list:

  • Background work: shown only while there is something left to do: past merge requests still being imported (with an estimate in hours at the current pace), open merge requests waiting to be evaluated under changed policies, an update of the repositories' webhooks in progress or one that could not finish, work waiting for a VCS rate limit to reset, repositories whose branches are checked later than set, and watched merge requests read back later than usual.
  • Bulk operations: the company's recent bulk operations and their progress (see Bulk operations).

Filters​

Filter (label in the UI)What it does
Search by name...Matches part of the project's name or full path, ignoring case
ModeAll modes, Watching or Change management
VCS connectionAll connections or one connection. Shown only when the company has more than one VCS connection

Refresh reloads the list. The list is sorted by name and shows 20 projects a page.

Columns​

Column (label in the UI)Shows
(check box)Chooses the project for a bulk operation. Not shown to auditors
NameThe repository's name; select it to open the project page
NamespaceThe repository's full path, such as acme/payments
ModeWatching or Change management
CM statusFor a watched project: an Events badge (green when Merge Pilot receives the repository's events) and the state of the import of past merge requests (see Importing past merge requests). For a project under change management: Set up when every setup step that was not turned off is in place, otherwise Incomplete
Setup dateHow long ago the repository was last set up (watched or put under change management)

Choosing projects opens the bulk bar; see Choosing repositories.

When there are no projects yet, the page says No registered projects and, for people who have the search tab, points to it.

Search <connection>​

Type at least 2 characters of a repository name and select Search (or press Enter). The search covers the repositories Merge Pilot can set up: on GitLab the projects its account holds Maintainer or Owner on (archived ones left out), matched by name, path or group, and never other public or internal projects of the GitLab instance; on GitHub the repositories the Merge Pilot App is installed on, matched by owner and name. The VCS returns at most 20 matches; when 20 come back, the page says so and suggests typing more of the name, or using Watch repositories or Add to change management, which page through every repository. The columns are Name, Namespace and Default branch.

The search is for finding repositories to set up, so only people who may set them up have it: company admins and platform admins, and people the connection's rule for Set up change management allows (never auditors). They see only the repositories they hold the rule's minimum role on, through the VCS account they linked in My profile. Without a linked account the search answers Link your <product> account in My profile to use this.

Who may do what​

Company admins and platform admins may do everything on this page and on the project pages. For everyone else, three things decide:

  1. The role in Merge Pilot. Auditors only read. Some project settings are for company admins only (see Project page).

  2. The VCS connection's rules. The connection's settings drawer has a rule per operation people may ask Merge Pilot to do with the connection's account: whether it is on, which Merge Pilot roles may, and the minimum role on the repository (see VCS connection settings). Watching and change management use two of them:

    RuleLets people
    Set up change management (cm_setup)Watch repositories, put them under change management, move watched ones to change management, repair the setup, import past merge requests again, list the repositories that can be watched, add target branches
    Remove change management (cm_remove)Take a repository out of change management, switch it to watching, stop watching it, gate fewer branches
  3. Their own role on the repository. Through the VCS account they linked in My profile, they must hold at least the rule's minimum role on each repository they set up, move or take out (the admin chooses it, from any access up). Reading a project's live setup status needs any access to the repository.

ActionCompany admin, platform adminPolicy manager, userAuditor
See the projects and project pagesYesYesYes
Watch, add to change management, move to change management, repair the setup, import past merge requests againYesAs the rule for Set up change management allowsNo
Remove change management, switch to watching, stop watchingYesAs the rule for Remove change management allowsNo
Change a project's target and excluded branchesYesAs the rule for Set up change management allows to add branches, and the rule for Remove change management to gate fewerRead only
Approver roles, change approval setup, push ignore listYesNoRead only
Paths left out of the analysis, run an analysisYesNoNo

Every operation of someone who is not a company admin is checked by the server, whatever the page shows: a repository they may not act on is refused with a message such as this needs at least Maintainer on this repository in GitLab (you have Developer).

Before you start​

  • The platform's Application URL must be set (see Platform settings): webhooks point to it. Watching or setting up a repository without it is refused.
  • The VCS connection's account must be allowed to write what the mode needs: on GitLab, the bot user's token needs the Maintainer role to create the project webhook (also for watching); on GitHub, the App must be installed on the repository. See GitLab and GitHub.

API​

Every request needs company_id (a query parameter, or in the body where shown). Repositories are named by their VCS ID (repo_id); a project by its Merge Pilot ID.

ActionRequest
List projectsGET /api/v1/projects with q, mode (monitor or gated), vcs_connection_id, page and page_size (at most 100)
Count matching projects per connection and modeGET /api/v1/projects/summary with the same filters; answers vcs_connection_id, watched and gated per connection
One projectGET /api/v1/projects/{id}
A project by repositoryGET /api/v1/projects/by-repo-id/{repo_id} with connection_id; answers null when the repository is not in Merge Pilot
Search the VCSGET /api/v1/projects/search with name and connection_id (at most 20 results)
Repositories that can be watchedGET /api/v1/projects/watchable with connection_id, q, page and page_size (default 50, at most 100); each has project_id and mode when it is in Merge Pilot already, and the answer has has_more
Watch, add, move or stop watching manyPOST /api/v1/projects/bulk (see Bulk operations)
Put a repository under change managementPOST /api/v1/projects/cm-setup (see Change management)
Move a project between modesPUT /api/v1/projects/{id}/mode
Open merge requests and what change management would decide for themGET /api/v1/projects/{id}/mode-impact
Stop watchingPOST /api/v1/projects/{id}/unwatch
Remove change managementPOST /api/v1/projects/cm-remove
Remove from Merge Pilot only, for a repository the VCS no longer answers for (company admins)POST /api/v1/projects/{id}/forget with reason; 409 while the VCS still answers for the repository (see Change management)
Live setup statusGET /api/v1/projects/cm-status with repo_id and connection_id
BranchesPUT /api/v1/projects/{id}/branches (see Project page)
What the company's background work has leftGET /api/v1/projects/background

connection_id may be left out: the company's default VCS connection is used.

A project has id, company_id, repo_id, vcs_connection_id, name, path_with_namespace, web_url, mode, default_branch, target_branches, excluded_branches, watch_started_at, vcs_access_lost_at, backfill, cm_setup (with steps, warnings, setup_completed_at, consented_by, consented_at), cm_steps, events_warning, protection, push_ignore_list, sca_exclude, vcs_settings, tracker_override, heads_checked_at, created_at and updated_at.

Audit actions​

ActionWhen it is written
project_watchedA repository was watched (from the page, in a bulk operation, or by automatic watching)
cm_setupA repository was put under change management or its setup was run again
project_mode_changedA project was moved between watching and change management
project_unwatchedA project stopped being watched
cm_removeChange management was removed
project_branches_updatedA project's target or excluded branches were changed
project_forgottenA repository was taken out of Merge Pilot without touching the VCS
vcs_access_lostThe GitHub App no longer reaches repositories Merge Pilot follows
project_history_importedSomeone imported a watched project's past merge requests again

The full list, with the project settings and bulk operation actions, is on the Audit log page.

Video tutorials

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

Watch Repositories Before You Enforce AnythingYouTube ↗
Put a GitLab Repository Under Change ManagementYouTube ↗