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
| Watching | Change management | |
|---|---|---|
| Label in the UI | Watching | Change management |
API value (mode) | monitor | gated |
| Written to the repository | GitLab: 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 requests | Recorded 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 |
| Merges | Never held. A merge that change management would have held is recorded as such | Held until the policy is met |
| Changes pushed without a merge request | Recorded as Would have been blocked | Recorded as a Violation |
| Scans | Run when the company turns on scans for watched merge requests | Run as the policy says |
| Notifications | Sent only when the company announces events of watched repositories | Sent 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 projects | The 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 does | Shown to |
|---|---|---|
| Watch repositories | Opens 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 management | Opens 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> groups | Lists 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 |
| Mode | All modes, Watching or Change management |
| VCS connection | All 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 |
| Name | The repository's name; select it to open the project page |
| Namespace | The repository's full path, such as acme/payments |
| Mode | Watching or Change management |
| CM status | For 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 date | How 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:
-
The role in Merge Pilot. Auditors only read. Some project settings are for company admins only (see Project page).
-
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:
Rule Lets 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 -
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.
| Action | Company admin, platform admin | Policy manager, user | Auditor |
|---|---|---|---|
| See the projects and project pages | Yes | Yes | Yes |
| Watch, add to change management, move to change management, repair the setup, import past merge requests again | Yes | As the rule for Set up change management allows | No |
| Remove change management, switch to watching, stop watching | Yes | As the rule for Remove change management allows | No |
| Change a project's target and excluded branches | Yes | As the rule for Set up change management allows to add branches, and the rule for Remove change management to gate fewer | Read only |
| Approver roles, change approval setup, push ignore list | Yes | No | Read only |
| Paths left out of the analysis, run an analysis | Yes | No | No |
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.
| Action | Request |
|---|---|
| List projects | GET /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 mode | GET /api/v1/projects/summary with the same filters; answers vcs_connection_id, watched and gated per connection |
| One project | GET /api/v1/projects/{id} |
| A project by repository | GET /api/v1/projects/by-repo-id/{repo_id} with connection_id; answers null when the repository is not in Merge Pilot |
| Search the VCS | GET /api/v1/projects/search with name and connection_id (at most 20 results) |
| Repositories that can be watched | GET /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 many | POST /api/v1/projects/bulk (see Bulk operations) |
| Put a repository under change management | POST /api/v1/projects/cm-setup (see Change management) |
| Move a project between modes | PUT /api/v1/projects/{id}/mode |
| Open merge requests and what change management would decide for them | GET /api/v1/projects/{id}/mode-impact |
| Stop watching | POST /api/v1/projects/{id}/unwatch |
| Remove change management | POST /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 status | GET /api/v1/projects/cm-status with repo_id and connection_id |
| Branches | PUT /api/v1/projects/{id}/branches (see Project page) |
| What the company's background work has left | GET /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
| Action | When it is written |
|---|---|
project_watched | A repository was watched (from the page, in a bulk operation, or by automatic watching) |
cm_setup | A repository was put under change management or its setup was run again |
project_mode_changed | A project was moved between watching and change management |
project_unwatched | A project stopped being watched |
cm_remove | Change management was removed |
project_branches_updated | A project's target or excluded branches were changed |
project_forgotten | A repository was taken out of Merge Pilot without touching the VCS |
vcs_access_lost | The GitHub App no longer reaches repositories Merge Pilot follows |
project_history_imported | Someone 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.
Related pages
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →