Project page
Each repository has a page in Merge Pilot. It shows whether the repository is watched or under change management and lets you change that, holds the repository's own settings (branches, approver roles, where its change approvals go), and gathers what Merge Pilot knows about it: its dependency analysis and its direct changes. It also offers the operations on GitLab or GitHub that people may ask Merge Pilot to do, which Merge Pilot does with the connection's own account.
Opening it
- Projects → select a project in Registered projects or Search <connection>.
- From the monitoring report's By project table, or a direct change's project.
A repository that is not in Merge Pilot yet (found with the search) has a page too, with the buttons to watch it or set it up; its settings and tabs appear once it is in Merge Pilot.
The header shows the repository's name and full path, a back button to Projects, and Open in <GitLab or GitHub>. A repository that cannot be found shows This project could not be found: it may have been deleted on the VCS, or you may not have access to it.
Who sees what
| Part of the page | Company admin, platform admin | Policy manager, user | Auditor |
|---|---|---|---|
| Project info, status card, membership | Yes | Yes | Yes |
| Buttons of the status card | Yes | As the connection's rules for Set up change management and Remove change management allow: their Merge Pilot role, and the rule's minimum role on the repository (see Who may do what) | No |
| Change approval setup, Approver roles | Edit | Not shown | Read |
| Branches | Edit | Shown and editable with Set up change management | Read |
| Variables, Branches (VCS operations) | Yes, on GitLab and GitHub | As the connection's rule for the operation allows (below) | Read only, when one of the tab's rules is on (no values, no buttons) |
| Tokens (VCS operations) | Yes, on GitLab | As the connection's rules for Create project access tokens and Create deploy tokens allow, or while they have tokens of their own there to revoke | Read only, when one of the two rules is on |
| Not available to you here | Not shown | When an operation is open to their Merge Pilot role but they lack the minimum role on the repository, or have not linked their VCS account: each with the reason | Not shown |
| Security tab | Yes, and run analyses and set excluded paths | Read | Read |
| Direct changes tab | Yes; the push ignore list (on Overview) too | Policy managers read it; users do not see it | Read, push ignore list included |
Status cards
Project info
| Field (label in the UI) | Shows |
|---|---|
| <GitLab or GitHub> ID | The repository's ID on the VCS (repo_id) |
| Default branch | The repository's default branch |
CM status
For a repository under change management: the live setup status read from the VCS, step by step (In place, Missing with the reason, or turned off for this repository), the warnings, the gaps found by the branch protection check, and the buttons Sync CM / Re-run CM setup, Remove CM and Switch to watching. See Setup status and repair.
When the setup of a repository under change management cannot be read from the VCS at the moment, the card says This repository is under change management, but its setup could not be read from <GitLab or GitHub> now., with the reason below it and, for those allowed to set up change management, Sync CM.
For a repository not in Merge Pilot: Not registered for CM, with Watch and Set up CM (see Setting up one repository).
Watching
For a watched repository, this card replaces CM status:
- Merge Pilot records this repository's merge requests as change management would decide them. Nothing is written to the repository but the delivery of its events.
- a warning when its webhook could not be updated;
- the Events badge (green when events are delivered) and the state of the import of past merge requests, with Import again or Import past merge requests (see Importing past merge requests);
- See what change management would have done: the monitoring report of this project;
- Move to change management (see Moving a watched repository) and Stop watching (see Stop watching).
Company admins also see Remove from Merge Pilot only on the page of a repository in Merge Pilot, for a repository the VCS no longer answers for. It is refused while the VCS still answers for the repository: remove change management or stop watching it the usual way (see Removing a repository the VCS no longer answers for).
Process a merge request Merge Pilot has not seen
Below the status card of a repository in Merge Pilot, Process a merge request Merge Pilot has not seen takes a merge request number (such as !42, GitHub #42) and Process has Merge Pilot read that merge request from the VCS and process it in the background, for one whose events never arrived. API: POST /api/v1/merge-requests/fetch?company_id=… with connection_id, repo_id and mr_number, answers 202; 404 when the repository is not in Merge Pilot. Audit: mr_fetch_requested.
Membership
Join or leave the repository with your own VCS account (linked in My profile).
| Shown | When |
|---|---|
| Set up CM to manage membership from Merge Pilot. | The repository is not in Merge Pilot |
| Role to join with and Join project (GitHub: Join repository) | You have no access to the repository, and you are a company admin or the connection allows Join or leave projects. Shown once your membership is read: while it is read the card shows a spinner, and when it cannot be read it says Could not read your membership: … with Try again instead. The roles are the VCS's up to Developer: Guest, Reporter or Developer on GitLab; Read, Triage or Write on GitHub. The highest one is preselected |
| Invitation pending (Accept the invitation in GitHub to get … access.) | GitHub sent you an invitation instead of giving the access at once (you are not a member of the repository's organization). Open the invitation in GitHub opens it; Cancel invitation withdraws it |
| Your role here: … and Leave project (GitHub: Leave repository) | GitLab: you are a direct member. GitHub: Merge Pilot gave you this access when you joined. Leaving asks first: Leave <project>?, You give up your … role on this project. You can join it again here, with at most Developer. (GitHub: Write); when your role is above that, the dialog says that getting it back needs someone who manages access on the VCS |
| Your access is managed in GitHub (a team, the organization or a repository admin): leave it there. | GitHub: your access was not given by joining here, so it cannot be left here |
| Member (via group) | GitLab: your membership comes from a parent group: leave the group to remove it |
| Link your <GitLab or GitHub> account to see and change your membership of this project. and Open My profile | You have not linked your VCS account (the API answers 400 with code link_required) |
| No membership actions available | The connection does not allow it |
Leaving needs no rule: you can leave what you hold even after the connection stops letting you join, and while the connection is turned off. Your membership is read again after you join or leave, so what the page offers follows at once.
On GitLab, Merge Pilot records the access it gives when you join a project or a group, so that company admins see it if you leave the company (below); Leave project takes back your direct membership whether or not Merge Pilot recorded it, and joining what you are a direct member of already is refused (409 already a member of this project). When GitLab shows no direct membership any more, the record is dropped the next time your membership is read.
On GitHub:
- Someone who already has access to the repository, or an invitation to it, cannot join again here.
- GitHub cannot tell access given to you directly from access through a team or the organization. Merge Pilot therefore remembers the access it gives when you join, and Leave project takes back only that. Access through a team stays.
- Leave project removes your access when you have it, and cancels your invitation when you have not accepted it yet. An old, expired invitation left on the repository does not change that.
- When GitHub shows neither access nor an invitation any more (someone removed you there, you declined, or the invitation expired), Merge Pilot forgets the access it gave the next time it reads your membership (
vcs_access_grant_droppedin the audit log). While some access remains, for example through a team, it keeps the record. - When you leave the company (deactivated, moved to another company or made platform admin) or unlink your account, when the repository is removed from Merge Pilot, or when the connection is deleted or the company deactivated, the access you got by joining stays on the VCS (GitHub and GitLab alike). Your company admins see it under Company → People (see People); on GitHub it no longer counts as access you can leave here.
- If the organization does not allow outside collaborators, joining is refused with your organization does not allow adding outside collaborators: ask an owner, followed by GitHub's own words.
- On a repository of a personal GitHub account (not an organization), GitHub gives every collaborator write access and takes no role. Only Write can be chosen there; a lower role is refused with … belongs to a personal GitHub account, where a collaborator always gets write access: only Write can be chosen.
See Projects and groups. Joining and leaving are recorded in the audit log (vcs_join_project, with whether an invitation was sent; vcs_leave_project, with whether an invitation was cancelled). API: GET /api/v1/vcs-ops/projects/{pid}/membership, POST …/join with access_level (an empty body, or one without access_level, joins with the highest role people may give themselves; a body that is not JSON is refused with 400), POST …/leave.
Settings
These cards appear once the repository is in Merge Pilot. Each overrides a company or connection setting for this repository only.
Change approval setup
Where this repository's change approvals are created in the tracker linked to its VCS connection. Leave a field empty to use the tracker connection's setting. The card names the values the tracker connection sets. When the connection has no tracker linked, it says so: no change approvals are created (see Tracker).
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Tracker project | The tracker project change approvals are created in | Empty: the tracker connection's project | A project of the tracker (picked from its list, or typed); stored in upper case | Company admin | tracker_override.project_key |
| Issue type | The issue type of the change approvals | Empty: the tracker connection's issue type | An issue type of the tracker project | Company admin | tracker_override.issue_type |
| Link type | The issue link type between a change approval and its work items. Not shown for the built-in tracker | Empty: the tracker connection's link type | A link type of the tracker | Company admin | tracker_override.link_type |
Save change approval setup saves; Use the connection's setup removes the override. API: PUT /api/v1/projects/{id}/tracker-override with project_key, issue_type and link_type; all empty removes it. Audit: update_tracker_override.
Approver roles
Who may be assigned this repository's change approvals, take them and decide them. The card says whether the repository uses the connection's roles or its own.
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Roles that may be assigned and decide change approvals | Exactly the checked repository roles may be given this project's change approvals, take them and decide them, unless the policy's approver pool sets its roles. They replace the connection's roles | None checked: the connection's roles (shown below the list), or Developer and above when the connection sets none | GitLab: Guest, Reporter, Developer, Maintainer, Owner. GitHub: Read, Triage, Write, Maintain, Admin | Company admin | vcs_settings.assignee_access_levels (GitLab: 10, 20, 30, 40, 50; GitHub: 20, 25, 30, 40, 50) |
| Also leave out these logins | VCS usernames never assigned this repository's change approvals, on top of the connection's exclude list (which the card names) | Empty | VCS usernames | Company admin | vcs_settings.assignee_exclude_list |
The change's author never decides its change approval, whatever their role. Save roles saves; Use the connection's roles clears the repository's own roles (its excluded logins stay). Roles that do not exist on the VCS are refused. API: PUT /api/v1/projects/{id}/vcs-settings; both empty removes the override. Audit: update_project_vcs_settings. See also Approver roles and Who may approve.
Branches
Which merge requests of this repository are followed: Merge requests into these branches are gated by the change policies; others are ignored. (for a repository under change management) or are recorded (for a watched one).
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Target branches | The branches whose merge requests are followed, replacing the company's branch patterns for this repository | Empty: the company's branch patterns (named below the field; All branches when the company sets none) | Branch names and glob patterns, such as main or release/*, and Repository default branch (~DEFAULT_BRANCH). An empty pattern is refused | Company admin; members the rule for Set up change management lets | target_branches |
| Excluded branches | Merge requests into these branches are ignored, even when a target pattern matches them | Empty | Branch names and glob patterns, such as release/legacy | The same | excluded_branches |
A line below the fields shows the result: Followed: main, release/*. Except: release/legacy. Patterns are globs, not regular expressions (see Patterns).
Save branches saves. What happens then:
- Under change management: Saving sets the gate up again in the repository for these branches. The setup steps agreed to before are written again for the new branches at once. When that fails, the branches are not changed.
- Watched: on GitLab, the webhook's push filter follows the new branches.
- Direct changes are looked for on the new branches from the next push or head check.
Adding branches needs the Set up change management permission; gating fewer (removing a target pattern, or adding an excluded branch) needs Remove change management. Company admins may always do both. On a repository under change management, someone without Remove change management who edits the branches reads Gating fewer branches also needs the Remove change management permission.
API: PUT /api/v1/projects/{id}/branches with target_branches (empty: the company's) and excluded_branches. Audit: project_branches_updated.
Tabs
Below the page title, a line shows how the repository is followed (Change management, Watching or Not registered) and its default branch. The page has four tabs; the one open, and the view inside it, are in the address (?tab=overview|security|changes|operations, &view=…), so a link opens the same place and the browser's back button goes to the previous one. Each tab loads what it shows only when it is first opened.
| Tab (label in the UI) | What it holds | Shown when |
|---|---|---|
| Overview | The status cards (project info, change management status or watching, membership) and the settings (change approval setup, approver roles, branches, the push ignore list) | Always |
| Security | The analysis of the default branch and its inventories (below); its badge counts the open dependency, container image and infrastructure findings | Once the repository is in Merge Pilot |
| Direct changes | Changes made without a merge request (below); its badge counts those of the last 30 days | Once the repository is in Merge Pilot, for company admins, policy managers, auditors and platform admins |
| VCS operations | Variables, Branches and Tokens | When one of them is shown (below) |
Links made before this layout still work: ?tab=analysis opens Security, and ?tab=variables, branches or tokens opens VCS operations on that part.
Inside VCS operations, each part appears only when the VCS supports it and you may use it:
| Part (label in the UI) | Shown when |
|---|---|
| Variables | GitLab and GitHub; you are a company admin, or the connection's rule for View CI/CD variables, Manage project variables or Manage group variables lets you; auditors, read only, when one of them is on |
| Branches | GitLab and GitHub; company admin, or the rule for Protect branches, Unprotect branches or Allow or forbid force pushes lets you; auditors, read only, when one of them is on |
| Tokens | GitLab only; company admin, or the rule for Create project access tokens or Create deploy tokens lets you, or you still have tokens of your own on the repository (so that you can revoke them); auditors, read only, when one of the two is on |
The Variables, Branches and Tokens parts run operations on the VCS with the connection's account (the GitLab bot user, or the GitHub App), so you need no VCS rights for them beyond the minimum role the connection's rule names. They offer only what your own GitLab or GitHub role does not allow: what you can do yourself there, such as forking a repository or creating a branch, is done on GitLab or GitHub. A rule lets you when it is on, names your Merge Pilot role, and your linked GitLab or GitHub account holds at least its minimum role on the repository (see VCS connection settings). The page asks Merge Pilot what you may do and shows only that; when that cannot be read, the page says so (Could not read what you may do on this repository, so its operations are not offered: …) and offers none. When your role on the VCS cannot be read at the moment, a change is refused rather than allowed (502 could not verify your <GitLab or GitHub> access). While the connection is turned off, the page says This <GitLab or GitHub> connection is turned off: Merge Pilot operations are paused. You can still leave and revoke your tokens. and offers no other change (see Connections). Auditors see the tabs of the rules that are on, read only: no values, no forms, no buttons. Every change made through them is recorded in the audit log with who asked and the rule that allowed it, whether it succeeded or failed on the VCS (see VCS operations); a request the rules refuse changes nothing and is answered with the reason.
Not available to you here lists the operations open to your Merge Pilot role that you cannot use on this repository, each with the reason, for example this needs at least Maintain on this repository in GitHub (you have Write), you have no access to this repository in GitLab: this needs at least Developer on it, or Link your GitLab account in My profile to use this. It covers setting up and removing change management, viewing and changing variables, changing the group's variables, branches, unprotecting, force pushes, joining the repository and, on GitLab, creating project access tokens and deploy tokens. Changing the group's (GitHub: organization's) variables is judged by the group, as the change itself is: the reason is then this needs at least Maintainer in GitLab on one of the company's repositories in this group, and holding the minimum role on another of your company's repositories in the group is enough. Operations the connection keeps off, or does not open to your role, are not listed: when you have not linked your VCS account, you are asked to link it only for the operations linking would open. API: GET /api/v1/vcs-ops/projects/{pid}/my-access answers, per operation, allowed, view (you may read what its tab lists) and, when not allowed, reason and code (off, role, level, link, read_only, unregistered, unverified; a rule that is off or does not name your role is reported before link), and connection_active (false while the connection is turned off); on GitLab also own_tokens, how many tokens you asked for on the repository and have not revoked.
Variables
The repository's CI/CD variables, by Key, Environment scope (GitLab) and Flags. Values are not shown in the list. The form and the flags follow the VCS: GitLab variables have an environment scope, a type (variable or file), a description, and can be Protected, Masked, Hidden and Raw; GitHub has Actions variables and secrets, for the whole repository or one of its environments.
| Field (label in the UI) | What it does | Default |
|---|---|---|
| Variable key | The variable's name. Required. On GitHub a name is unique whatever its case, and follows GitHub's rules: only letters (A-Z), digits (0-9) and underscores, not starting with a digit or with GITHUB_ (in any case) | Empty |
| Variable value (Secret value for a secret, File content for a file) | The value, sent exactly as typed (spaces included); the form does not take a blank one. Through the API value is required and may be empty (400 key and value are required when it or key is left out; when editing, value is required). On GitHub at most 48 KB | Empty |
| Environment | GitHub: the repository's environment the variable or secret belongs to, chosen from the environments the repository has; None (the whole repository) for the repository's own. An environment has to be created on GitHub first. Not shown for organization variables | None |
| Secret | GitHub: store the value as an encrypted Actions secret. A secret can never be read back, here or on GitHub; the list shows it with a Secret badge | Off |
| Environment scope | GitLab: the environments that can use the variable, typed as GitLab takes it: * (or empty) for all, a name such as production, or a pattern such as review/*. On a group, GitLab has environment scopes on Premium and Ultimate only | * (all) |
| Type | GitLab: Variable, or File (the job gets a file holding the value, and the variable names that file) | Variable |
| Description | GitLab: what the variable is for (up to 255 characters) | Empty |
| Protected | GitLab: sets the Protected flag on the variable | Off |
| Masked | GitLab: sets the Masked flag on the variable. The value must then meet GitLab's masking rules (one line, no spaces, at least 8 characters) | Off |
| Hidden | GitLab (17.4 and later): the variable is masked, and its value is never shown again, in GitLab or here. Only a new variable can be hidden, and a hidden one cannot be unhidden. Masked is then on and cannot be turned off | Off |
| Raw | GitLab: $VARIABLES in the value are left as they are instead of being expanded. A variable that expands them shows Expanded | On |
A repository without environments shows no Environment field. If GitHub has not given Merge Pilot's App access to environments yet, the Environment field is turned off and says why (an App permission waiting to be accepted on GitHub). When the environments cannot be read at all, the field is turned off with Could not read the repository's environments: … and the reason, rather than letting you type a name.
What cannot be read is left out of the list instead of failing it, and a note above the list names it: an environment that GitHub does not answer for (for example one deleted on GitHub a moment ago) gives Could not read the variables and secrets of environment <name>: …, and the other environments and the repository's own variables are still listed; when the App may not read the environments (a permission not accepted yet), the repository's variables are listed with Could not read the repository's environments, so their variables and secrets are not listed: … or The environments' variables and secrets are not listed: …, naming the permission. API: the list answers {variables, warnings}.
Whose variables: when the repository belongs to a group (GitHub: an organization), a switch above the list, with Repository and the group's name, shows the group's variables instead. On GitHub, a new organization variable or secret is given only to the organization's repositories that are in Merge Pilot for your company (Selected repositories); repositories added later are not given it, and on GitHub Free private repositories cannot use organization variables and secrets. Group variables need the rule for Manage group variables to change; its minimum role counts on one of your company's repositories in the group (no role in the group itself is needed), so the group's list may be changeable for you even where this repository's list is not, and the other way round. When you may not change the group's variables, the switch shows Read only: with the reason, and the form and buttons are not shown. The switch is offered by the same judgement: the rule's minimum role on one of your company's repositories in the group, not on this repository. API: GET /api/v1/vcs-ops/projects/{pid}/group answers the group with can_manage and, when false, manage_reason.
A group's variables can reach other teams' repositories too. So the list shows only the ones your company's repositories in Merge Pilot can use, and a variable can be deleted here only when every repository that can use it is your company's:
| Variable | Listed | Can be deleted here |
|---|---|---|
| GitHub, visible to all repositories | Yes | No: every repository in the organization can use it, not only the company's |
| GitHub, visible to private repositories | When one of your company's repositories in the organization is private | No: every private repository in the organization can use it |
| GitHub, visible to selected repositories | When one of them is your company's | When all of them are your company's; otherwise repositories that are not the company's in Merge Pilot can use it too |
| GitLab group variable | Yes (every project of the group and its subgroups can use it) | When every project of the group and its subgroups is in Merge Pilot for your company; otherwise the group holds projects that are not the company's in Merge Pilot, and they can use it too |
A variable that cannot be changed here shows Read only: with the reason under its name, and has no edit or delete button; change it on GitHub or GitLab. Changing or deleting it through the API is refused (403, with the reason).
Values. The value of a masked or hidden variable is never sent by Merge Pilot, to anyone, company admins included, and a secret has none to send. Other values are sent only to people who may change the variable (company admins, or the rule for Manage project variables, or Manage group variables for a group's); for everyone else the list shows Value hidden, and the API answers value_hidden: true without the value. The answers to adding and editing a variable follow the same rule.
Edit (the pencil, Edit variable <key>) changes a variable or secret. The key and the environment scope (GitHub: the environment) stay. The value is always entered: a plain value is filled in, while a masked, hidden or secret value is not shown, and the dialog says why (GitLab: GitLab needs the value again to change this variable: Merge Pilot never reads hidden or masked values back. Enter it again, or a new one.; a GitHub secret: GitHub stores a secret encrypted and never returns it: enter its value again, or a new one, to change it.; otherwise The value is not shown here: enter it again, or a new one.). On GitLab the type, description, Protected, Masked and Raw can change too; a hidden variable stays masked and hidden. A variable is changed only where it is: Merge Pilot looks it up first, so editing never creates one, and a variable of another environment scope is never changed instead (GitLab's own group update would change another scope's variable of the same key when the scope asked for does not exist; Merge Pilot answers no variable named <key> … (404) instead). On GitHub only the value changes; an organization secret keeps its visibility and repositories. Editing needs the same rule as adding (Manage project variables, or Manage group variables for a group's, where only variables every repository of which is your company's can change). Only what you changed is sent: options you left as they were stay as they are on the VCS. API: PUT /api/v1/vcs-ops/projects/{pid}/variables/{key} and PUT /api/v1/vcs-ops/groups/{gid}/variables/{key}, with ?environment= and ?secret=true as for deleting.
Add variable (Add secret) creates it, unless one of that name exists already. GitLab's own refusals come back in its words, for example GitLab answered 400: {"value":["is invalid"]} for a value that cannot be masked. On GitHub a name or value that breaks GitHub's rules is refused before anything is sent, under the field and by the API (400): GitHub variable names may contain only letters (A-Z), digits (0-9) and underscores (_), … must not start with a digit, … must not start with GITHUB_, GitHub variable values are limited to 48 KB (the same with secret). When GitHub itself refuses a new variable for another reason, the answer is GitHub refused the variable: … with GitHub's words. The delete button removes one after Delete variable <key>? (GitLab: Pipelines that use this variable will fail or behave differently. This cannot be undone.; GitHub: Workflow runs that use this variable will fail or behave differently. This cannot be undone.). Reading needs the rule for View CI/CD variables or Manage project variables (changing them serves reading them); creating and deleting need the rule for Manage project variables; each with its minimum role on the repository. On GitLab several variables may share a key with different environment scopes: the delete names the variable's scope, so only that one is deleted (for group variables the scope is sent only when it is not the default *: GitLab has it for groups from 16.9, on Premium and Ultimate). When GitLab still finds several, it refuses with There are multiple variables with provided parameters. Please use 'filter[environment_scope]'. The form, the edit and the delete buttons are shown only with Manage project variables (company admins always have it); with View CI/CD variables alone the tab is read-only. API: GET, POST /api/v1/vcs-ops/projects/{pid}/variables and DELETE /api/v1/vcs-ops/projects/{pid}/variables/{key} (with ?environment= and ?secret=true to name an environment's value or a secret); GET /api/v1/vcs-ops/projects/{pid}/environments; the group: GET /api/v1/vcs-ops/projects/{pid}/group, then /api/v1/vcs-ops/groups/{gid}/variables.
Branches
| Part (label in the UI) | What it does |
|---|---|
| Branches | The repository's branches, all of them; protected ones carry Protected (on GitHub: protected by Merge Pilot, as below), and those under change management Change management. Search branches above the list finds branches by name (the VCS searches them, a moment after you stop typing); the Protect choice offers what the search found. On GitLab a repository with more than 10,000 branches lists the first 10,000 and says so above the list: search for the branch to find it. When GitLab answers too slowly to read every branch within the time a request has (25 seconds), the list stops there and says Merge Pilot read the first N branches in the time a request has: search for the branch to find it |
| Protected branches | Each protected branch, with Force push or No force push (GitHub: Changed on GitHub when its ruleset was changed there, see below). Allow force push / Disable force push switches it (needs Allow or forbid force pushes); allowing asks first, Allow force pushes to <branch>?, since commits that were reviewed could then be replaced. Through the API the body must name allow (400 allow (true or false) is required). Unprotect removes the protection after Unprotect <branch>? (Anyone with push access could then push or merge to this branch without a merge request, bypassing change management.; GitHub says pull request); it needs Unprotect branches |
| Protect | Choose a branch (Select branch to protect) and protect it, so it changes only through merge requests (pull requests). On GitLab no one may push to it and Developers and above may merge into it. All branches are protected when none is left. Shown only with Protect branches |
On GitHub, Merge Pilot protects each branch with a ruleset of its own, named Merge Pilot protected: <branch>, as the tab says above the list: no deleting the branch, no force pushes, and changes only through a pull request. Allow force push takes the force push rule out of that ruleset, and Unprotect deletes only that ruleset; the change management ruleset and rulesets made by others are never changed. Rulesets add up on GitHub, so when another ruleset still blocks force pushes on the branch (for example the change management ruleset, which blocks them unless that setup step is turned off), a warning names it: Force pushes are still blocked. Force pushes to "main" are still blocked on GitHub by the ruleset "Merge Pilot change management": rulesets add up, and the strictest rule applies. The branch's classic branch protection on GitHub (branch protection rules, outside rulesets) is named too when it blocks force pushes: … The branch's classic branch protection on GitHub also blocks force pushes., or alone Force pushes to "main" are still blocked on GitHub by the branch's classic branch protection. GitHub allows at most 75 rulesets per repository in total: each branch Merge Pilot protects uses one, so does change management, and rulesets made by others count too (see Troubleshooting connections).
A ruleset counts as Merge Pilot's protection only while it is still what Merge Pilot made: that one branch, active, nobody allowed to bypass it, and only its own rules. One that was changed on GitHub (other branches, turned off or to evaluate, bypass allowed, rules added or taken out) is listed with Changed on GitHub and how, for example This protection was changed on GitHub (its rules were changed). Merge Pilot does not change or remove it; change or remove it on GitHub.; its Allow force push and Unprotect are turned off, and the API answers 409 the ruleset "…" was changed on GitHub (…); change or remove it there.
A branch is named exactly, on GitLab and GitHub alike: refs/heads/main is read as main, and a name with spaces around it, another refs/… name or no name is refused with 400 (the branch name has spaces around it: give the exact name, "…" is not a branch: …, branch name is required), when protecting, unprotecting or changing force pushes. On GitHub names with a pattern character (*, ?, [, ], {, }) are refused with 400 too (branch "…" contains a pattern character ( ? [ ] ); give one branch by its exact name*). Allow force push is done once GitHub saved the ruleset; when the other rulesets or the classic branch protection cannot be read for the warning, it succeeds without naming them.
Branches under change management. A branch is under change management when the repository is under change management and the branch matches its target branches (the repository default branch resolved; with none set anywhere, the default branch) and none of its excluded branches; a protected name pattern such as release/* counts too. These branches carry Change management, and only company admins may unprotect them or change force pushes on them (allowing or forbidding), whatever the connection's rules say. For anyone else the row says This branch is under change management; only a company admin can change its protection., its Unprotect and force push button are turned off, and the API answers 403 this branch is under change management; only a company admin can change its protection (recorded in the audit log as a failure, with the reason). Protecting one branch follows the rules as before.
On GitLab a protection can be a wildcard pattern (ma*, release/*, *), and GitLab applies the most permissive of the protections matching a branch. So on a repository under change management, a pattern that could cover a branch under change management (it matches the default branch or a target branch, or a target branch is a pattern itself) is the company admins' alone: protecting with it, unprotecting it and changing its force pushes are refused to anyone else with 403 this pattern can cover a branch under change management; only a company admin can change protection with it (recorded as a failure). Such a pattern carries Change management in the protected list.
On GitLab, change management's approval rule for a branch is linked to the branch's protection. When a company admin unprotects such a branch, the confirmation says so, and Merge Pilot warns: Merge Pilot's approval rule for this branch was linked to the branch's protection, which is now removed, so the rule is no longer linked to the branch. Run change management setup on the project again to protect the branch and link the rule again. Protecting the branch again on the Branches tab does not link the rule; running change management setup does. On GitHub the change management ruleset is separate, so unprotecting removes only Merge Pilot's branch ruleset and nothing is lost.
The tab and its two lists follow any of the rules for Protect branches, Unprotect branches and Allow or forbid force pushes (each with its own minimum role on the repository); protecting, unprotecting and force pushes each follow their own rule. Someone who may only unprotect branches sees the lists and Unprotect, without Protect. API: /api/v1/vcs-ops/projects/{pid}/branches, /api/v1/vcs-ops/projects/{pid}/protected-branches, /api/v1/vcs-ops/projects/{pid}/protected-branches/{name} and …/{name}/force-push.
Tokens
GitLab only. The project access tokens and deploy tokens Merge Pilot created on the repository with its own GitLab account, newest first, and Create token to make one. Tokens made on GitLab directly are not listed.
| Column | Shows |
|---|---|
| Name | The token's name; for a deploy token also its user name |
| Kind | Project access token or Deploy token |
| Scopes | The scopes it was given |
| Role | A project access token's role (Guest, Reporter or Developer) |
| Expires | Its expiry date |
| Requested by | The Merge Pilot user who asked for it |
| Status | Active; Expired; Revoked (with who revoked it); Not active on GitLab when GitLab lists it as revoked or no longer has it. When GitLab's list cannot be read, a note above the table says so and the status comes from Merge Pilot's records only |
Create token asks for:
| Field (label in the UI) | What it does | Default |
|---|---|---|
| Kind | Project access token or Deploy token; only the kinds you may create are offered | The first you may create |
| Name | The token's name. Required | Empty |
| Description (optional) | Project access tokens: what it is for, up to 255 characters. GitLab keeps it from 17.7 | Empty |
| Role | Project access tokens: Guest, Reporter or Developer, never above your own role on the repository. Maintainer and Owner are never given through Merge Pilot | Guest (the lowest; choose a higher one on purpose) |
| User name (optional) | Deploy tokens: the user name the token signs in with. Left empty, GitLab names it gitlab+deploy-token-<n> | Empty |
| Scopes | At least one. Project access tokens: read_api, read_repository, write_repository, read_registry, write_registry (never api or self_rotate). Deploy tokens: read_repository, read_registry, write_registry, read_package_registry, write_package_registry, read_virtual_registry, write_virtual_registry (a deploy token never pushes code). A deploy token has no role of its own, so each scope needs your own role on the repository: Reporter for read_repository, read_registry and read_package_registry, Developer for write_registry and write_package_registry, any role for the two virtual registry scopes (company admins may give all). A scope above your role is shown off with Needs at least … on this repository, which you do not have | None |
| Expires on | Required: a date after today and at most 365 days away. For project access tokens this is GitLab's own default limit; GitLab lets a deploy token never expire, but Merge Pilot always sets an expiry, with the same limit | 30 days from today |
The value is shown once. After Create token, a dialog shows the token's value with a Copy button and the warning that this is the only time it is shown. Merge Pilot does not store the value, does not write it to the audit log, and GitLab does not show it again; after I have copied it it is gone. Only that button closes the dialog: pressing Escape or clicking outside it does not, so the value is not lost by accident. Where the browser does not allow copying, Copy says so: select the value and copy it. A lost value cannot be recovered: revoke the token and create a new one.
Revoke asks Revoke this token? and then GitLab revokes it at once; anything still using it stops working. A token GitLab no longer has is marked revoked with a warning. A token revoked already (for example by someone else a moment before) is answered 409 this token is revoked already. Revoking is open to the person who asked for the token (even after the connection's rule is turned off), company admins, and anyone the rule for the token's kind lets create one (with its minimum role on the repository).
GitLab asks the account that creates tokens to be a Maintainer or Owner of the project, so Merge Pilot's GitLab account needs that role on the repository (see GitLab connection). On GitLab.com, project access tokens need a Premium or Ultimate subscription.
When the person who asked for a token leaves the company, the repository is removed from Merge Pilot, the connection is deleted or the company deactivated, the token keeps working on GitLab: company admins see it under People, to revoke or dismiss.
API: GET /api/v1/vcs-ops/projects/{pid}/tokens (answers {tokens, warnings}, never a value), POST /api/v1/vcs-ops/projects/{pid}/access-tokens (name, description, scopes, access_level 10, 20 or 30, expires_at as YYYY-MM-DD), POST /api/v1/vcs-ops/projects/{pid}/deploy-tokens (name, username, scopes, expires_at), both answering 201 with {token, value}, and DELETE /api/v1/vcs-ops/projects/{pid}/tokens/{token_id}. Invalid input is refused with 400 before GitLab is asked. On GitHub the rules for tokens cannot be turned on, so creating answers 403 (company admins: 501), the list 501, and revoking 404 (no token is ever recorded there).
Security
An analysis reads the repository's default branch: its dependency manifests (the dependencies, their known vulnerabilities and licenses), the container images it refers to (see Container image scan) and its infrastructure files (see Infrastructure check), and keeps the result. Analyses also run on their own when a merge or a direct change updates the repository's vulnerability inventory.
Run analysis (company admins) starts one in the background. Another cannot start while one runs, nor within 5 minutes after the last one completed or failed; after a temporary failure the button reads Retry and works at once. An analysis still running after 65 minutes is marked failed. Starting one is audited as analysis_triggered.
At the top, the last analysis on one line: its status (Running, Completed, Failed; Stale when it is older than 7 days), the branch, the commit, when and by whom it ran and how long it took, with Run analysis and Export SBOM; under it, Results may be incomplete with the reasons. Four tiles give the open findings and the worst severities: Dependencies, Container images, Infrastructure, and Licenses (distinct licenses). A tile opens its view:
| View (label in the UI) | Shows |
|---|---|
| Dependencies | The repository's vulnerability inventory for its dependency manifests: each vulnerability followed from when it was first seen until it is fixed; all but auditors may accept an open one as an exception. Below it, Dependencies (N) (expand it to load the list): Name, Version, Ecosystem, Manifest, with Filter by name, 200 rows at a time; and Excluded paths for company admins (below). Without access to the inventory (users), the last analysis's Vulnerabilities (N) list instead |
| Container images | The vulnerabilities of the container images the default branch refers to, in the same inventory |
| Infrastructure | The default branch's infrastructure findings, each followed from first seen until fixed |
| Licenses | Most used licenses (the five licenses with the most packages, with their counts), then Package, Version, License(s), Ecosystem, Manifest, 200 rows at a time |
| History | Date, Status, Duration, Manifests, Deps, Vulns, Run (After merge !N, After a direct change to <branch>, or who started it) and What changed (N new, M gone since the previous analysis) |
Container images and Infrastructure are shown to company admins, policy managers, auditors and platform admins, as is the dependency inventory.
Limits of one analysis: at most 50 manifests (the first by path; findings in the others stay as they were), at most 500 vulnerabilities, and at most the company's dependency limit (Company → Scanning → Dependencies; see Scanning). When a limit is reached, the analysis says so. Dependencies without an exact version are not looked up; ecosystems the vulnerability database does not cover, and dependencies without license data, are counted.
Excluded paths
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Excluded paths | Manifests under these globs are not analysed (test fixtures, examples), on top of the company's blocked paths. Findings only they had are closed by the next analysis | Empty | Comma-separated file globs, such as test/**, examples/** | Company admin | sca_exclude |
They apply from the next analysis. API: PUT /api/v1/projects/{id}/sca-exclude with paths. Audit: update_project_sca_exclude.
SBOM
Once an analysis of the repository has completed, Export SBOM downloads the dependencies its default branch uses, as of the last analysis, with their licenses: CycloneDX (JSON) or SPDX 2.3 (JSON). When not every manifest could be read, the download warns that the SBOM may leave dependencies out. Every member of the company may export it. API: GET /api/v1/projects/{id}/sbom?format=cyclonedx (or spdx). Audit: sbom_exported.
Analysis API
| Action | Request |
|---|---|
| Start (company admins) | POST /api/v1/projects/{id}/analysis, answers 202; 429 while one runs or within the 5 minutes |
| The latest | GET /api/v1/projects/{id}/analysis (null when none ran) |
| History | GET /api/v1/projects/{id}/analysis/history with page and page_size |
| One analysis | GET /api/v1/projects/{id}/analysis/{aid} |
| Its details | GET /api/v1/projects/{id}/analysis/{aid}/details with type (deps, vulns or licenses) |
| What changed since the previous one | GET /api/v1/projects/{id}/analysis/{aid}/diff, answers previous, new and fixed |
When an analysis finishes, project_analysis is written to the audit log.
Direct changes
Changes that reached this repository's watched branches without a merge request: direct pushes, force pushes and deleted branches. The tab lists them with the same filters, columns and CSV export as Insights → Direct changes (see Where to see them), without the project column; the search looks for a pusher, commit or SHA.
On the Overview tab, the Pushes recorded as ignored card holds the repository's own ignore list; company admins edit it and auditors read it:
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Pushes recorded as ignored | Pushes by these logins to this repository are recorded as ignored direct changes: no violation, no notification. They are listed as Ignored account. The company's list (named below the field, with a Company list link) applies too | Empty | VCS usernames; * is a wildcard, case is ignored | Company admin | push_ignore_list |
Save saves it. API: PUT /api/v1/projects/{id}/push-ignore with logins. Audit: update_project_push_ignore. See Ignore lists.
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 →