Approvals
The company's Approvals tab holds the approval settings that apply to every change policy of the company: whose approvals made in the tracker count, what happens to a change approval nobody can be assigned, the approver pools, who may declare an emergency, who may name a stand-in for an approver who is away, and the warning when one person approves too much. A policy decides who must approve its changes (see Approval); this tab sets the company-wide rules around it.
Where to find it
Administration → Company (platform admins: Administration → Companies → the company), tab Approvals. The company page opens for company admins and platform admins only.
The tab has six cards, in this order:
- Tracker approvals
- Change approval assignment
- Approver pools
- Emergency changes
- Stand-ins for approvers, with the Stand-ins list under it
- Approval fatigue guard
Saving
- The settings of Tracker approvals, Change approval assignment, Emergency changes, Who names stand-ins and Approval fatigue guard are part of the company form: they are saved with Save changes in the bar at the bottom of the page, together with the other tabs (
PUT /api/v1/companies/{id}). While a change is unsaved, the tab shows a dot and leaving the page asks first. - Approver pools and the Stand-ins list are saved one by one, as you add, edit or remove them.
- With four-eyes review on (company Governance tab), changes to approver pools wait for a second person (another administrator or a policy manager). The other settings on this tab are applied when saved.
Tracker approvals
Whose decisions in the tracker count. A change approval is approved or rejected in the tracker by moving it to its approving or rejecting status; Merge Pilot then checks who did it. How tracker decisions are counted is described in Approval → In the tracker.
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Approvals made in the tracker | Only from people who linked their VCS account: an approval or rejection in the tracker counts only when the tracker names who made it and that person is an active Merge Pilot user of the company (found by user name, e-mail or the tracker account set for them) who linked their account on the merge request's VCS and holds one of the approver roles on the repository (as for a vote in Merge Pilot); otherwise the change approval goes back for a decision. From any Merge Pilot user: an approval counts when the tracker names a Merge Pilot user of the company, even without a linked VCS account (separation of duties then knows them by e-mail); an approval by someone Merge Pilot does not know never counts, and rejections are not checked | Only from people who linked their VCS account | strict, lenient | Company | Company admins, platform admins | tracker_approvals |
| In Jira, only the change approval's assignee decides it | Approvals and rejections in Jira by anyone but the change approval's assignee are ignored, and the change approval goes back for a decision. The built-in tracker always works this way. It governs moves in the tracker only: anyone who may vote can still vote in Merge Pilot. Shown only while the company has an active Jira connection | Off | On, off | Company | Company admins, platform admins | tracker_assignee_only |
| Decide Jira change approvals in Jira only | Change approvals in Jira are approved and rejected in Jira only (for example when its workflow asks for fields a vote in Merge Pilot cannot fill): the merge request page offers no Approve, Reject or Withdraw and says Change approvals are decided in Jira only at this company: approve or reject KEY there. Off: either place. The built-in tracker is not affected. Shown only while the company has an active Jira connection | Off | On, off | Company | Company admins, platform admins | tracker_decisions_only |
How a person in the tracker is matched to a Merge Pilot account is set on the company's People tab (see People).
Change approval assignment
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| When nobody can be assigned a change approval | What happens when nobody holding the approver roles may take the change approval (its author, committers the policy keeps out and people without a linked account are left out). The change approval is opened unassigned either way, and the merge request says so. Leave it for someone to take: it stays unassigned until someone who may approve takes it with Assign to me. Assign it as soon as someone can: the periodic re-check gives it to the first person who may take it | Leave it for someone to take | manual, auto | Company default; a policy can set its own (When nobody can be assigned) | Company: company admins, platform admins. Policy: policy managers, company admins, platform admins | no_approver (policy: controls.approval.no_approver) |
| When an assignee is deactivated | What happens to the open change approvals of a person deactivated in Merge Pilot. Assign them again: each is assigned again by its policy's assignment rule, to someone else who may take it; when nobody may, the setting above decides. Keep them assigned and warn: they stay assigned to the deactivated person, and the merge request says <person>, its assignee, was deactivated until someone takes it over. Company admins get the Change approvals of a deactivated person notification either way, and each change approval is recorded as change_approval_assignee_deactivated | Assign them again | reassign, keep_and_warn | Company | Company admins, platform admins | assignee_deactivated |
How a policy assigns change approvals, and taking or taking over one, are described in Approval → Assignment.
Change approval deadline
In the same card:
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Change approval deadline (hours) | How long a normal change's change approval may stay open before it is overdue: 0 for no deadline, at most 2160. When a quarter of the time is left (at most a day before the deadline) change_approval_due_soon is sent, once it passes change_approval_overdue. A reopened change approval gets a new deadline. Emergency changes keep their policy's review deadline. A policy can set its own. | 0: no deadline | 0 to 2,160 hours (90 days); anything else is refused (400) | Company default; a policy can set its own (Change approval deadline) | Company: company admins, platform admins. Policy: policy managers, company admins, platform admins | change_approval_due_hours (policy: controls.approval.due_hours) |
The deadline is set when a change approval is created, so a change applies to change approvals created afterwards. See Approval → Change approval deadline and Events → Change approval deadlines.
Approver pools
Groups of people a change policy may ask approvals from. They belong to the company: policies of every connection can name them.
The card lists the company's approver pools, with Add pool, Edit and Delete for company admins and platform admins. It is the same list as Governance → Approver pools in the sidebar. The pool fields, who counts as a member, deletion rules and four-eyes review are described in Approver pools.
A pool named by the company's emergency rules (below) is shown as used by Company emergency rules and cannot be deleted while it is.
Emergency changes
A change an emergency policy covers (usually by its "emergency" label) merges without waiting for approval and is reviewed afterwards. By default anyone who may label the change declares an emergency, so a hotfix never waits; every declaration is recorded with who made it, audited (emergency_declared) and announced. This card limits who may declare one. An emergency policy can set its own rules instead (This policy sets its own rules); see Approval → Who may declare an emergency.
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Who may declare one | Anyone who may label the change: no limit. An approver pool: only people of that pool may declare an emergency. A label added by someone else does not make the change an emergency: the next matching policy covers it | Anyone who may label the change | Anyone, or one of the company's approver pools | Company default; policy override | Company: company admins, platform admins. Policy: policy managers, company admins, platform admins | emergency.pool_id (absent: anyone) |
| The author may not declare their own change an emergency | Someone else must add the label | Off | On, off | Company default; policy override | As above | emergency.not_author |
| Limit emergencies per repository | Turns the limit on. Once a repository has had this many emergencies in the window, further ones follow the next policy | Off (no limit) | On, off | Company default; policy override | As above | emergency.quota_count (absent or 0: no limit) |
| Emergencies | How many emergencies a repository may have in the window. Shown while the limit is on | 3 | 1 to 1,000 | Company default; policy override | As above | emergency.quota_count |
| In days | The length of the window. Shown while the limit is on | 30 | 1 to 365 | Company default; policy override | As above | emergency.quota_days |
Saving is refused when the pool is not an approver pool of the company (emergency.pool_id is not an approver pool of this company), or when a limit is set without a window of 1 to 365 days.
Stand-ins for approvers
Who may name a colleague to approve in an approver's place while they are away. A stand-in is assigned the change approvals and votes in the approver's place for the period, for the requirements whose repository roles the stand-in holds themselves; the vote shows by …, standing in. How stand-ins vote is described in Approval → Stand-ins.
Who names stand-ins
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Who names stand-ins | Approvers and administrators: approvers name their own stand-in in My profile; administrators can name one for anyone. Approvers only: each approver names their own stand-in in My profile. Administrators only: only company administrators name stand-ins, on this tab. Off: nobody votes for someone else; existing stand-ins stop counting | Approvers and administrators | both, self, admin, off | Company | Company admins, platform admins | delegation |
The Stand-ins list below follows the saved setting: save first, then add stand-ins under the new rule.
The Stand-ins list
While an approver is away, a colleague approves in their place: the vote counts for the approver's pools, and someone who committed to a change cannot approve it this way either.
The list shows every current and future stand-in of the company as Stand-in approves for Approver, with the period and the reason. Ended stand-ins are not listed. With Off and no stand-in left, the card is not shown.
To add one, fill in:
| Field (label in the UI) | What it is | Default |
|---|---|---|
| Approver who is away | Whose votes are handed over. Shown to administrators unless the company is set to Approvers only; administrators then add their own stand-in only | You. A platform admin is no member of the company, so for them it starts empty: pick someone |
| Stand-in | The colleague who approves in their place (Choose a colleague) | None |
| From | First day, from the start of the day | Today |
| Until (inclusive) | Last day, to the end of the day | Seven days from today |
| Reason | Optional, for example Annual leave | Empty |
Add stand-in saves it at once. The people lists show the first 200 active people of the company by name; when there are more, Find a person searches by name or user name (The lists show the first 200 people by name; search to find others.). The bin icon (Remove stand-in) ends a stand-in at once.
A stand-in is refused when:
- the two are the same person, or either is not an active user of the company (both people must be active users of the company);
- the period does not end after it starts, has already ended, or is longer than 180 days;
- the approver already hands over their votes in an overlapping period (one stand-in at a time);
- the stand-in is away themselves in that period (… hands over their own votes in that period: someone away cannot stand in), which also refuses two people standing in for each other;
- the approver stands in for someone else in that period (… stands in for someone in that period: give that over to someone else first): votes pass one step only.
Who may add and remove stand-ins:
| Who names stand-ins | Approvers (in My profile) | Company admins, platform admins (here or in My profile) |
|---|---|---|
| Approvers and administrators | Their own | Their own and anyone's |
| Approvers only | Their own | Their own |
| Administrators only | None (In this company, administrators set up stand-ins.) | Their own and anyone's |
| Off | None | None |
A stand-in can be removed by the approver, by whoever set it up, or by an administrator. Stand-ins are created and removed by a signed-in person or a personal API token, not by a service token.
API: GET /api/v1/delegations (administrators see the company's stand-ins, others those they give or receive; meta.mode is the saved setting), POST /api/v1/delegations with user_id (optional: the approver, by default the caller), delegate_id, from, until, reason, DELETE /api/v1/delegations/{id}, and GET /api/v1/delegations/people (q searches).
Approval fatigue guard
Warns when the same person has approved N or more change approvals within the lookback period (approvals in the tracker and in Merge Pilot count alike). It only warns; nothing is blocked. What the warning shows and where it is sent is described in Approval → Approval fatigue.
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Enable approval fatigue detection | Turns the warning on | Off | On, off | Company | Company admins, platform admins | approval_fatigue.enabled |
| Lookback days | The period counted. Shown while detection is on | 7 | 1 to 90 while detection is on (anything else is refused, in the form and with 400 by the API) | Company | Company admins, platform admins | approval_fatigue.lookback_days |
| Threshold | Approvals by one person in the period that trigger the warning. Shown while detection is on | 5 | 1 to 1,000 while detection is on (anything else is refused, in the form and with 400 by the API) | Company | Company admins, platform admins | approval_fatigue.threshold |
API fields
All on the company (GET and PUT /api/v1/companies/{id}), except the stand-ins.
| Field | Values |
|---|---|
tracker_approvals | strict (default), lenient |
tracker_assignee_only | true, false (default) |
tracker_decisions_only | true, false (default) |
no_approver | manual (default), auto |
assignee_deactivated | reassign (default), keep_and_warn |
change_approval_due_hours | 0 (default: no deadline) to 2160 |
emergency | pool_id (an approver pool of the company), not_author, quota_count (0 to 1,000), quota_days (1 to 365 with a quota) |
delegation | both (default), self, admin, off |
approval_fatigue | enabled, lookback_days, threshold |
Audit log
| Action | When |
|---|---|
update_company | The company's settings were saved, with what changed |
delegation_created, delegation_deleted | A stand-in was added or removed |
approver_pool_created, approver_pool_updated, approver_pool_deleted, config_change_requested | An approver pool changed, or a pool change waits for four-eyes review (see Approver pools) |
See Audit log.
Related pages
- Approval: who must approve a change, votes, separation of duties, emergency changes.
- Approver pools.
- People: how people are found in the tracker.
- Governance: four-eyes review of control changes.
- Company overview.