Skip to main content

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:

  1. Tracker approvals
  2. Change approval assignment
  3. Approver pools
  4. Emergency changes
  5. Stand-ins for approvers, with the Stand-ins list under it
  6. 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 doesDefaultAllowed valuesSet whereWho can change itAPI field
Approvals made in the trackerOnly 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 checkedOnly from people who linked their VCS accountstrict, lenientCompanyCompany admins, platform adminstracker_approvals
In Jira, only the change approval's assignee decides itApprovals 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 connectionOffOn, offCompanyCompany admins, platform adminstracker_assignee_only
Decide Jira change approvals in Jira onlyChange 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 connectionOffOn, offCompanyCompany admins, platform adminstracker_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 doesDefaultAllowed valuesSet whereWho can change itAPI field
When nobody can be assigned a change approvalWhat 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 itLeave it for someone to takemanual, autoCompany default; a policy can set its own (When nobody can be assigned)Company: company admins, platform admins. Policy: policy managers, company admins, platform adminsno_approver (policy: controls.approval.no_approver)
When an assignee is deactivatedWhat 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_deactivatedAssign them againreassign, keep_and_warnCompanyCompany admins, platform adminsassignee_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 doesDefaultAllowed valuesSet whereWho can change itAPI 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 deadline0 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 adminschange_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 doesDefaultAllowed valuesSet whereWho can change itAPI field
Who may declare oneAnyone 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 itAnyone who may label the changeAnyone, or one of the company's approver poolsCompany default; policy overrideCompany: company admins, platform admins. Policy: policy managers, company admins, platform adminsemergency.pool_id (absent: anyone)
The author may not declare their own change an emergencySomeone else must add the labelOffOn, offCompany default; policy overrideAs aboveemergency.not_author
Limit emergencies per repositoryTurns the limit on. Once a repository has had this many emergencies in the window, further ones follow the next policyOff (no limit)On, offCompany default; policy overrideAs aboveemergency.quota_count (absent or 0: no limit)
EmergenciesHow many emergencies a repository may have in the window. Shown while the limit is on31 to 1,000Company default; policy overrideAs aboveemergency.quota_count
In daysThe length of the window. Shown while the limit is on301 to 365Company default; policy overrideAs aboveemergency.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 doesDefaultAllowed valuesSet whereWho can change itAPI field
Who names stand-insApprovers 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 countingApprovers and administratorsboth, self, admin, offCompanyCompany admins, platform adminsdelegation

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 isDefault
Approver who is awayWhose votes are handed over. Shown to administrators unless the company is set to Approvers only; administrators then add their own stand-in onlyYou. A platform admin is no member of the company, so for them it starts empty: pick someone
Stand-inThe colleague who approves in their place (Choose a colleague)None
FromFirst day, from the start of the dayToday
Until (inclusive)Last day, to the end of the daySeven days from today
ReasonOptional, for example Annual leaveEmpty

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-insApprovers (in My profile)Company admins, platform admins (here or in My profile)
Approvers and administratorsTheir ownTheir own and anyone's
Approvers onlyTheir ownTheir own
Administrators onlyNone (In this company, administrators set up stand-ins.)Their own and anyone's
OffNoneNone

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 doesDefaultAllowed valuesSet whereWho can change itAPI field
Enable approval fatigue detectionTurns the warning onOffOn, offCompanyCompany admins, platform adminsapproval_fatigue.enabled
Lookback daysThe period counted. Shown while detection is on71 to 90 while detection is on (anything else is refused, in the form and with 400 by the API)CompanyCompany admins, platform adminsapproval_fatigue.lookback_days
ThresholdApprovals by one person in the period that trigger the warning. Shown while detection is on51 to 1,000 while detection is on (anything else is refused, in the form and with 400 by the API)CompanyCompany admins, platform adminsapproval_fatigue.threshold

API fields​

All on the company (GET and PUT /api/v1/companies/{id}), except the stand-ins.

FieldValues
tracker_approvalsstrict (default), lenient
tracker_assignee_onlytrue, false (default)
tracker_decisions_onlytrue, false (default)
no_approvermanual (default), auto
assignee_deactivatedreassign (default), keep_and_warn
change_approval_due_hours0 (default: no deadline) to 2160
emergencypool_id (an approver pool of the company), not_author, quota_count (0 to 1,000), quota_days (1 to 365 with a quota)
delegationboth (default), self, admin, off
approval_fatigueenabled, lookback_days, threshold

Audit log​

ActionWhen
update_companyThe company's settings were saved, with what changed
delegation_created, delegation_deletedA stand-in was added or removed
approver_pool_created, approver_pool_updated, approver_pool_deleted, config_change_requestedAn approver pool changed, or a pool change waits for four-eyes review (see Approver pools)

See Audit log.