Skip to main content
2 video tutorials

VCS connection settings

Each VCS connection has a settings drawer (gear icon, Settings) that says how the connection is used: the tracker its change approvals go to, who may approve them, what change management writes to its repositories, and what people may ask Merge Pilot to do with the connection's account. It has four sections: Tracker, Approver roles, Change management setup and Permissions.

Only company admins (and platform admins) change these settings. Save settings saves all four sections together: when one part is refused, nothing is saved. API: PUT /api/v1/connections/{id}/vcs-usage with tracker_connection_id, vcs_settings, vcs_permissions and cm_steps; each part left out stays as it is. Closing the drawer with unsaved edits (Cancel, Escape or a click outside) asks first: Discard changes throws them away.

Tracker​

Setting (label in the UI)What it doesDefaultAllowed valuesAPI field
Linked tracker connectionThe tracker where change approvals are created for the merge requests of this connection's repositoriesNoneNone (tracker disabled), or one of the company's active tracker connectionstracker_connection_id (empty string: unlink)

Without a linked tracker, only standard changes can merge: normal and emergency changes need a change approval. Choosing None asks for confirmation (Unlink the tracker?) for that reason.

Approver roles​

Setting (label in the UI)What it doesDefaultAllowed valuesAPI field
Roles that may be assigned and decide change approvalsExactly the checked repository roles may be assigned a change approval, take it and decide itNone checked: Developer, Maintainer and Owner (GitLab); Write, Maintain and Admin (GitHub)GitLab: Guest, Reporter, Developer, Maintainer, Owner. GitHub: Read, Triage, Write, Maintain, Adminvcs_settings.assignee_access_levels (GitLab: 10, 20, 30, 40, 50; GitHub: 20, 25, 30, 40, 50)
Exclude listUsernames that are never assigned a change approval, for example bot accounts and service usersEmptyVCS usernames (matched ignoring case)vcs_settings.assignee_exclude_list
  • A repository may set its own roles, and an approver pool its own; they replace the connection's roles. A repository's excluded usernames are added to the connection's.
  • The connection's own account (the GitLab bot user, or the GitHub App) is never assigned.
  • The change's author never decides its change approval, whatever their role.

Change management setup​

What is written to a repository when it is moved to change management, including repositories added automatically. Required steps make the merge gate and are always written. Optional steps are checked here by default; each move to change management shows this list again and may turn optional steps off for that repository.

ProviderStep (label in the UI)RequiredDefaultAPI key
GitLabProtect the target branchesYesAlwaysprotect_branches
GitLabAdd the bot user as a memberYesAlwaysbot_member
GitLabApproval rule per target branchYesAlwaysapproval_rule
GitLabRemove approvals when commits are addedNoOnreset_approvals_on_push
GitLabPrevent editing approval rules in merge requestsNoOnno_approver_override
GitLabPrevent approval by the authorNoOnno_author_approval
GitLabPrevent approvals by users who add commitsNoOnno_committer_approval
GitLabProject webhookYesAlwayswebhook
GitHubRuleset with Merge Pilot's required checkYesAlwaysruleset_check
GitHubRequire a pull requestNoOnrequire_pull_request
GitHubBlock force pushesNoOnblock_force_push
GitHubBlock branch deletionNoOnblock_deletion

On GitLab connections the same section sets Allowed to push and merge and Allowed to merge for the branch protection change management adds (see Branch protection levels).

What each step writes, and what happens to it when change management is removed, is described on the GitLab and GitHub pages.

  • API field: cm_steps, a map from step key to on or off. A step that is left out takes its own default. Turning a required step off, or naming a step the provider does not have, is refused.
  • Repositories added automatically use the connection's defaults; their setup records the agreement as connection defaults.
  • Every signed-in member of the company can read the list and its defaults: GET /api/v1/connections/{id}/cm-steps.

Permissions​

What people may ask Merge Pilot to do on the VCS. Merge Pilot does the operation with the connection's own account (the GitLab bot user, or the GitHub App), at once, and records it in the audit log. People need no VCS rights for it beyond the minimum role the rule names: a GitLab Developer can add a CI/CD variable, a GitHub Write collaborator can protect a branch, when the connection's rule lets them.

Two rules decide what is offered at all:

  • Only what people's own role does not allow. People are usually kept at GitLab Developer or GitHub Write, so that they cannot remove the controls change management adds. What they can already do there themselves, such as forking a repository, creating a branch or listing their own repositories, is not offered.
  • Nothing that weakens change management, except for company admins. Unprotecting a branch under change management, or changing force pushes on it (allowing or forbidding them), is refused to everyone else, whatever the rules say. So is a GitLab wildcard protection (such as ma*) that could cover such a branch.

Why pipeline schedules are not offered. Merge Pilot would have to take ownership of a schedule to change it, which makes Merge Pilot's account its owner, and GitLab runs a scheduled pipeline with its owner's permissions. A Developer could then run pipelines with the rights of Merge Pilot's account (a Maintainer at least), which is more than their own role gives them.

Each operation has its own rule:

Part of the rule (label in the UI)What it doesDefault when the operation is turned onAPI field
On/off switchWhether people other than company admins may ask for the operationOffvcs_permissions.<operation>.enabled
Merge Pilot rolesThe Merge Pilot roles that may ask for it: User, Policy manager. With none checked, only company admins mayBothvcs_permissions.<operation>.roles (user, policy_manager)
Minimum role on the repositoryThe lowest role the person's own VCS account (the one they linked in My profile) must hold on the repository. Merge Pilot reads it with its own accountGitLab Developer, GitHub Write: the role people are usually kept at. Lower it only on purposevcs_permissions.<operation>.min_access: GitLab 10 Guest, 20 Reporter, 30 Developer, 40 Maintainer, 50 Owner; GitHub 20 Read, 25 Triage, 30 Write, 40 Maintain, 50 Admin
  • Company admins (and platform admins) may always do every operation, with or without a VCS account.
  • Auditors never change anything. They may read what an operation that is on shows (the variables of a repository without their values, its branch lists, its tokens), whatever their own role on the VCS: the Variables, Branches and Tokens tabs show to them read only.
  • Any access (the lowest minimum: GitLab Guest, GitHub Read) means the person can see the repository on the VCS:
    • GitLab: a member of the project, directly or through a group, with at least Guest. Minimal access does not count: it cannot see the repository.
    • GitHub: a collaborator of the repository, directly, through a team or as a member of its organization. On a public repository everyone can read it on GitHub, but that is not access here: someone who is not a collaborator has no access.
  • The repository must already be in Merge Pilot for the company. This is not needed to set up change management on a new repository.
  • Group and organization variables: the minimum role counts on one of the company's repositories in Merge Pilot inside the group (GitHub: organization). No role in the group itself is needed. The project page judges it the same way: someone who holds the minimum role on another of the company's repositories in the group may change the group's variables from any of them. On GitLab a role in the group itself counts too, and is read first. Merge Pilot then reads the person's role on at most 25 of the company's repositories in the group; when the group holds more and none of those gives the role, the refusal says so: …; the group has too many repositories to check: Merge Pilot read your role on 25 of the company's N there, so ask for it on the group itself or ask a company admin. A role found is reused for a minute.
  • Joining a repository or group has no minimum role: it is for people without access.
  • Leaving needs no rule: someone who joined keeps the right to give the access up, also after the rule for joining is turned off or no longer names their role. Reading one's own membership needs no rule either. Auditors still change nothing.
  • Branches under change management keep the protection change management relies on: only company admins may unprotect them or change force pushes on them, in either direction, whatever the rules say. A branch named another way is the same branch: refs/heads/main is main, and a name with spaces around it is refused. On GitLab, the most permissive of the protections matching a branch applies, so a wildcard pattern that could cover a branch under change management (ma*, *) is the company admins' alone too, for protecting, unprotecting and force pushes (see Branches). Patterns are matched as GitLab matches them (* also matches /). A branch counts as under change management when the repository is under change management through any of the company's connections to the same GitLab or GitHub (another connection with the same address included).
  • A connection turned off pauses every change through it, company admins included (409 this connection is turned off: ask a company admin), but taking access back: leaving, cancelling an invitation and revoking a token still work (see Connections).
  • Every operation is audited: who asked, the rule that allowed it (its roles and minimum role, or company admin), the role the person had on the repository, and that Merge Pilot's account did it. Setting up and removing change management, also in bulk, is audited the same way.
  • The saved rules are checked: a role other than User or Policy manager, a minimum that is not one of the VCS's roles, or, on a GitHub connection, turning on Join groups, Create project access tokens or Create deploy tokens, is refused (400). Joining takes no minimum.

Example. To let developers manage their repositories' variables without giving them Maintainer on GitLab: turn on Manage project variables, keep User and Policy manager, and set Minimum role on the repository to Developer. A Developer then adds a variable from the project page; the GitLab bot user creates it; a Reporter is told "this needs at least Developer on this repository in GitLab (you have Reporter)".

The drawer shows only the operations the connection's VCS supports. On GitHub, these are all of them except Join groups, Create project access tokens and Create deploy tokens (GitHub has no such tokens, and organizations are not joined through Merge Pilot; turning any of the three on for a GitHub connection is refused with 400).

Change management​

Operation (label in the UI)What it lets people doDone byAvailable onAPI field
Set up change managementPut a repository under change management or watch it, repair its setup, and list the repositories that can be watched (only those where they hold the minimum role). Also covers bulk moves: each repository is checked when it runsMerge Pilot's accountGitLab, GitHubvcs_permissions.cm_setup
Remove change management (Powerful)Take a repository out of change management (its merge gate is removed). Also covers bulk movesMerge Pilot's accountGitLab, GitHubvcs_permissions.cm_remove

Projects and groups​

Operation (label in the UI)What it lets people doDone byAvailable onAPI field
Join or leave projectsAdd themselves to a repository (at most Developer on GitLab, Write on GitHub), or leave it. On GitHub, people outside the organization get an invitation to accept there, and only access they joined with in Merge Pilot can be left (see Membership). No minimum roleMerge Pilot's accountGitLab, GitHubvcs_permissions.join_projects
Join groupsList groups and add themselves to one (as Developer at most), or leave it. No minimum role. A group role reaches every project of the group and its subgroups, so joining is refused, with the reason, unless every one of them is in Merge Pilot for the company. A group shared with other groups (invited into them on GitLab) gives its direct members access there too, so joining it is refused to everyone but company admins: acme is shared with other groups (partner): joining it would also give access there; ask a company admin. Leaving is always allowedMerge Pilot's accountGitLabvcs_permissions.join_groups

Branch protection​

Operation (label in the UI)What it lets people doDone byAvailable onAPI field
Protect branchesProtect a branch so it changes only through merge requests. On GitHub a protected branch gets a ruleset of its own, Merge Pilot protected: <branch>Merge Pilot's accountGitLab, GitHubvcs_permissions.protect_branches
Unprotect branches (Powerful)Remove a branch's protection. On GitHub only Merge Pilot's ruleset for the branch is deleted. Branches under change management: company admins onlyMerge Pilot's accountGitLab, GitHubvcs_permissions.unprotect_branches
Allow or forbid force pushes (Powerful)Let a protected branch's history be rewritten, or stop that. On GitHub another ruleset may still block force pushes; Merge Pilot then names it. Branches under change management: company admins only, in both directionsMerge Pilot's accountGitLab, GitHubvcs_permissions.force_push

The repository's Branches tab, with its list of branches and of protected branches, shows to someone any of these three operations allows (each with its own minimum role), and to auditors, read only, when one of them is on; each control on it shows only to those its own operation allows. Someone who may only unprotect branches sees the lists and Unprotect, but not Protect.

CI/CD variables​

Operation (label in the UI)What it lets people doDone byAvailable onAPI field
View CI/CD variablesRead the CI/CD variables (secrets by name only) of the repository and of its group (GitHub: organization). Of the group, only the variables the company's repositories can use. Values only of variables the person may also change, and never of masked or hidden ones (to anyone)Merge Pilot's accountGitLab, GitHubvcs_permissions.view_variables
Manage project variablesList, create, change and delete a repository's CI/CD variables (without View CI/CD variables, the list is still shown to do so); on GitHub also secrets, and those of the repository's environments. On GitLab with an environment scope, type, description, protected, masked, hidden and raw; a variable of one environment scope is changed or deleted by its scope, also when several share its keyMerge Pilot's accountGitLab, GitHubvcs_permissions.manage_project_vars
Manage group variables (Powerful)List, create, change and delete a group's CI/CD variables (shared by its repositories). On GitHub these are the organization's variables and secrets; a new one is given only to the organization's repositories in Merge Pilot for the company. On GitLab a new one is created only while every project of the group and its subgroups is in Merge Pilot for the company. Only variables every repository of which is the company's can be changed or deleted; the others are read only (see Variables)Merge Pilot's accountGitLab, GitHubvcs_permissions.manage_group_vars

Tokens​

Operation (label in the UI)What it lets people doDone byAvailable onAPI field
Create project access tokens (Powerful)The repository's Tokens tab: create a GitLab project access token and revoke tokens created there. The token's role is Guest, Reporter or Developer, never above the person's own role on the repository (company admins: Developer at most). Scopes: read_api, read_repository, write_repository, read_registry, write_registry; api (the whole API) and self_rotate (a token that renews itself past its expiry) are never given. An expiry date is required: after today and at most 365 days away. The value is shown once (see Tokens)Merge Pilot's accountGitLabvcs_permissions.create_access_tokens
Create deploy tokensCreate a GitLab deploy token and revoke tokens created there. Scopes: 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 the person's own role on the repository (below). An expiry date is required: after today and at most 365 days away. GitLab itself lets deploy tokens never expire; Merge Pilot does notMerge Pilot's accountGitLabvcs_permissions.create_deploy_tokens

A deploy token scope needs the role GitLab asks of a person, on a private repository, for what the scope does. Company admins count as Developer, so they may give every scope. A scope above the person's role is shown off in the dialog with the reason, and refused (400) through the API.

Deploy token scopeRole needed on the repository
read_repository, read_registry, read_package_registryGitLab Reporter
write_registry, write_package_registryGitLab Developer
read_virtual_registry, write_virtual_registryAny role (GitLab Guest)

A token is revoked by the person who asked for it (even after the rule is turned off), by company admins, or by anyone the rule for its kind allows, with its minimum role on the repository. When two people revoke the same token at once, one revokes it and the other is answered 409 this token is revoked already. The Tokens tab therefore also shows to someone who still has tokens of their own on the repository, so that they can revoke them, when they may no longer create any.

Merge Pilot records the access people get by joining (repositories, and groups on GitLab). When a person leaves the company or unlinks their VCS account, the repository is removed from Merge Pilot, the connection is deleted or the company is deactivated, that access, and the tokens Merge Pilot created, stay on the VCS: company admins see them under People.

Operations marked Powerful let people loosen a repository or reach its secrets through Merge Pilot's account; give them to the roles and minimum role you trust with that. Every operation (joining, leaving, variables, branch protection, tokens, change management) is recorded in the audit log, whether it succeeds or fails on the VCS, and so is a refusal that names its reason there (a branch under change management, a group that holds other teams' projects). A request the rules refuse (the rule is off, the Merge Pilot role is not named, the role on the repository is too low) is answered 403 with the reason and changes nothing; it is not audited.

Video tutorials

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

Self-Service GitLab Operations with GuardrailsYouTube ↗
Protect a Branch and Create a Deploy Token, Self-ServiceYouTube ↗