Approver pools
An approver pool is a named group of people, such as a change advisory board or a security team, that a change policy can ask approvals from. A policy that names a pool accepts approvals only from its members, whether they vote in Merge Pilot or approve the change approval in the tracker. Without a pool, the people holding the project's approver roles approve.
Pools belong to the company: the policies of every VCS connection of the company can name them.
Where to find them
- Governance → Approver pools in the sidebar, shown once a company is selected.
- The company's Approvals tab, card Approver pools.
- From a policy's Approval tab, Manage approver pools.
| Role | What they can do |
|---|---|
| Policy manager, company admin, platform admin | See, add, edit and delete pools, and pick their people |
| Auditor | See the pools and who is in them |
| User | See the pools and who is in them |
With four-eyes review on, changes made by policy managers and admins wait for a second person (see Four-eyes review).
The list
Pools are listed by name. Each pool shows:
- its name and description;
- a badge per listed person, by name, for every role that can see the pools. A deactivated person is shown as name (deactivated). Policy managers, admins and auditors also see a person who has not linked their GitLab or GitHub account in My profile marked · not linked: they are not assigned change approvals and cannot vote until they link it;
- the repository roles a member must hold, or Project's roles when none is chosen;
- Everyone with the roles when the pool takes every repository member holding its roles;
- Used by … with the names of the policies (of every VCS connection) that name it, and Company emergency rules when the company's emergency rules name it; or Not used by any policy.
Policy managers and admins see Add pool, and Edit and Delete on each pool. Delete is disabled while the pool is used (Used by a policy).
Without any pool, the list says Without a pool, people holding the project's assignee roles approve change approvals.
Pool settings
Add pool or Edit opens New approver pool or Edit approver pool (Members can approve or reject change approvals of the policies using this pool.). Save pool saves it.
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Name | The pool's name, shown in policies and on merge requests | Empty | Required; surrounding spaces are removed | Policy manager, company admin, platform admin | name |
| Description | Free text, shown in the list | Empty | Any text | Same | description |
| Repository roles | Members must hold one of the checked roles on the change's repository, listed people too. None checked: the project's assignee roles. The checked roles replace the project's roles for this pool's approvals | None checked (the project's approver roles) | The repository roles of the company's VCS connections: GitLab Guest, Reporter, Developer, Maintainer, Owner; GitHub Read, Triage, Write, Maintain, Admin (shown together where they share a level, such as Developer / Write) | Same | vcs_access_levels (10, 20, 25, 30, 40, 50) |
| Also everyone holding these roles | On: every member of the change's repository holding one of the roles is in the pool, listed or not. Off: only the listed people | Off | On or off | Same | role_members |
| People | The people in the pool. Filter people narrows the list by name. Only active people of the company are offered; people marked Not linked cannot be assigned or vote until they link GitLab or GitHub in My profile | None | Active users of the company. Platform admins belong to no company and cannot be members | Same | user_ids |
Saving is refused when:
- the name is empty;
- the pool has no people and Also everyone holding these roles is off (a pool needs people, or everyone holding its roles);
- a role is not a repository role;
- a listed person is not a user of the company (pool members must be users of this company);
- the pool would have fewer listed people than a normal-change policy needs approvals from it (policy "…" needs 3 approvals from this pool; it would have 2 members). Pools that also take everyone holding their roles are not checked this way.
A person listed twice is kept once.
Read-only fields returned by the API: id, company_id, created_at, updated_at, used_by (the names described above) and members (the listed people, each with id, username, display_name and active).
Who counts as a member
For a given merge request, a person may approve as a member of the pool when all of these hold:
- They are listed in People, or the pool takes everyone holding these roles.
- They hold one of the pool's roles (or, with none checked, one of the project's approver roles) on the merge request's repository, through the VCS account they linked in My profile. Roles are matched exactly: a pool for Maintainer does not admit an Owner unless Owner is checked too.
- Their VCS username is not on the connection's or the repository's Exclude list (see VCS connection settings).
The policy's other rules still apply: the author of a change never approves it, and committers may be kept out by separation of duties (see Change approval). Votes in Merge Pilot and approvals in the tracker each count once, and someone in two pools counts once.
Where pools are used
| Where | What the pool does | API field of the policy |
|---|---|---|
| A policy's Approval tab, Who must approve | An approval requirement asks for a number of approvals from the pool (or from the project's approver roles, or from the code owners of the changed files). Requirements combine into approval groups, such as 1 from Security and 2 from Operations, or another way to approve (see Change approval) | controls.approval.groups[].requirements[].pool_id |
| A policy's Checks tab, Who may lift a risk hold | Only the pool's members may accept a held risk. Not set: the policy's approvers when its approval groups name a pool or the code owners, otherwise the company administrators. The author never may | controls.risk.release_pool_id |
| A policy's Checks tab, Let one held change go ahead during a freeze, Who may release a change | Only the pool's members may release a change a freeze holds. Not set: the policy's approvers when its approval groups name a pool or the code owners, otherwise the company administrators. The author never may (see Risk) | controls.freeze.release_pool_id |
| An emergency policy's Who may declare an emergency | Only the pool's members may declare an emergency under the policy (see Who may declare an emergency) | emergency.pool_id |
| The company's Approvals tab, Emergency changes, Who may declare one | The same, for every emergency policy that does not set its own rules | (company setting) |
Saving a policy that names a pool checks that the pool is the company's. For a normal change it also checks that the pool's listed people can give the approvals asked (the highest count at any risk level): fewer is refused; exactly as many is saved with a warning, because when one of them authors a change, the pool cannot give enough approvals without them.
Deleting a pool
A pool can be deleted only when nothing uses it: no policy names it (in an approval group, for lifting risk holds or for emergencies) and the company's emergency rules do not name it. Otherwise the delete is refused with the pool is used by a policy or the company's emergency rules; change them first. Change those policies first.
The confirmation reads The pool is removed; no policy uses it. The pool's last state is kept as a version.
Versions
Every save and the deletion of a pool keep the pool's state as a version, with who made the change and when. The versions are available through the API only: GET /api/v1/companies/{id}/approver-pools/{poolId}/versions returns them newest first, each with pool (the pool as saved), deleted (true for the deletion), by and at.
Four-eyes review
When the company turned on Review control changes (Company → Governance), saving and deleting pools wait for a second person, as for policies: Sent for review: another administrator or policy manager must approve the change. The waiting changes are shown at the top of the Approver pools page, where another policy manager, company admin or platform admin selects Approve or Reject. Nobody decides their own change.
The checks on the pool (name, people, roles, the policies that use it) are made when the change is requested.
Audit log
| Action | When |
|---|---|
approver_pool_created | A pool was created. Details: its name, the number of listed people, the roles and whether it takes everyone holding them |
approver_pool_updated | A pool was saved. Details as above, and what changed |
approver_pool_deleted | A pool was deleted |
config_change_requested, config_change_approved, config_change_rejected | With four-eyes review on: a pool change was sent for review, approved or rejected. When an approved change is applied, the pool action above is also written, by the approver, with requested_by and approved_by |
These entries are recorded under the Change policy resource. See Audit log.
API
All paths are under /api/v1. Reading needs a signed-in member of the company; writing needs a policy manager, company admin or platform admin.
| Method and path | What it does |
|---|---|
GET /companies/{id}/approver-pools | The company's pools by name, each with used_by and members |
POST /companies/{id}/approver-pools | Creates a pool (name, description, user_ids, vcs_access_levels, role_members). Answers 201 |
PUT /companies/{id}/approver-pools/{poolId} | Saves a pool (the whole pool) |
DELETE /companies/{id}/approver-pools/{poolId} | Deletes a pool that nothing uses; 409 when it is used |
GET /companies/{id}/approver-pools/{poolId}/versions | The pool's versions |
With four-eyes review on, POST, PUT and DELETE answer 202 Accepted with {"pending": true, "change": {…}}.
Related pages
- Change approval: approval groups and requirements.
- Change policies: the policies that name pools.
- VCS connection settings: the connection's approver roles and exclude list.
- Roles and users: who may manage pools.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →