Skip to main content
Video tutorial · 1:42

Governance tab

The controls that govern changes can themselves be changed: a policy relaxed, a pool widened, a change freeze removed. Four-eyes review of controls makes such changes wait until a second person approves them, so no single person can weaken the controls alone.

Company page → Governance, card Four-eyes review of controls: Changes to the controls themselves wait until a second person approves them.

The setting​

Setting (label in the UI)What it doesDefaultAllowed valuesWho can change itAPI field
Review control changesWhen on, the changes listed below are not applied when saved: they wait until another administrator approves themOffOn, offCompany admins of the company and platform admins, from a signed-in session (API tokens are refused)governance.config_approval
  • Turning it on takes effect when the page is saved.
  • Turning it off is itself reviewed: the save sends Stop reviewing control changes for review, and the review stays on until another administrator approves it.

What waits for review​

Below the switch, the card lists what waits for a second person when the review is on (When it is on, changes to these wait until a second person approves them (an administrator; for policies, approver pools and vulnerability exceptions also a policy manager):):

Topic (as listed)What is reviewedWhere the waiting change is shownWho may decide
Approver poolsSaving and deleting an approver poolApprover pools page, and the company pagePolicy managers, company admins, platform admins
The company directory (LDAP)Any change to the company directory settings, including a new bind passwordCompany pageCompany admins, platform admins
Switching this review offTurning Review control changes offCompany pageCompany admins, platform admins
Identity providers (single sign-on)Saving and deleting an identity providerThe identity providers card on the Sign-in tabCompany admins, platform admins
Whether people may make personal API tokensTurning Let people make personal API tokens on or offCompany pageCompany admins, platform admins
Change policies (adding, editing, deleting, reordering, templates)Adding, editing, activating or deactivating, deleting and reordering policies, and applying templatesChange policies pagePolicy managers, company admins, platform admins
Risk settings and change freezesAny change on the Risk tab, and change windows and change freezes on the Change calendar tabCompany pageCompany admins, platform admins
How people sign inThe Sign-in tab's settings, except identity providers and the directory, which are their own topicsCompany pageCompany admins, platform admins
Vulnerability exceptions (granting and revoking)Granting and revoking a vulnerability exceptionInsights → Vulnerabilities, in a box at the top of the pagePolicy managers, company admins, platform admins

Saving a reviewed setting with the value it already has sends nothing for review. Everything not listed (connections, notifications, scanning, approval settings, people, repositories, general settings) is applied as soon as it is saved.

How each page announces a held change:

  • Company page: the save bar says Goes to a second administrator: … before saving, and Saved. Sent for review: … after. The rest of the save is applied (see Four-eyes review on the company page).
  • Change policies and Approver pools: Sent for review: another administrator or policy manager must approve the change (see Change policies and Approver pools).
  • Identity providers: Sent for review: a second administrator approves the change (see Identity providers).
  • Vulnerability exceptions: Sent for review: another administrator or policy manager must approve it.

A change is checked when it is requested, as if it were saved: a change that could not be applied is refused at once and nothing waits.

Waiting changes​

Each page shows its waiting changes in a box at the top, hidden when there are none: 1 change waits for a second administrator (or 3 changes wait for a second administrator). Each change shows its summary (such as Change the risk settings, Change how people sign in, Allow personal API tokens), Requested by and the requester's name and how long ago.

What the box offers depends on who looks:

  • The person who requested the change: Another administrator must decide your change.
  • Someone whose role may not decide this kind of change: Waits for an administrator.
  • Anyone else who may decide: Reject and Approve.

Approve applies the change as it was requested (Approved and applied: …); Reject drops it (Rejected: …). The page then reloads to show the result.

Who may decide​

  • A second person: nobody decides their own change. A change requested with a service API token counts as requested by the person who made the token.
  • Not someone the requester prepared: an administrator whose account the requester created, gave its role or set the password of cannot decide the requester's changes either (your account was created, given its role or had its password set by the requester, so you cannot approve their change).
  • The right role for the topic (table above).
  • A signed-in session: API tokens cannot approve or reject.

Waiting changes do not expire: each waits until someone approves or rejects it. Turning the review off does not decide them; they still wait.

When an approved change cannot be applied​

The change is applied when it is approved, and checked again then. When applying fails (for example, an approver pool it names was deleted meanwhile, or a policy it edits was saved by someone else since), the approval answers the change could not be applied: … and the change is marked failed. Nothing of it is applied; make the change again.

Each waiting change holds the whole setting as it was saved (all the risk settings, all the sign-in settings, the whole directory configuration). Approving it applies that whole state.

If the server stops while a decision is being applied, the change can be decided again after 10 minutes.

API​

All paths start with /api/v1.

RequestWhoWhat it does
GET /governance/topicsSigned inThe topic keys, sorted: approver_pools, directory, governance_off, identity_providers, personal_api_tokens, policies, risk, sign_in, vulnerability_exceptions
GET /companies/{id}/config-changesEvery role of the company, platform adminsThe company's changes, newest first (at most 200). status=pending, applied, rejected or failed filters. The payload (what the change sets) is shown only to people who may decide that change
POST /companies/{id}/config-changes/{changeId}/approveWho may decide (above), signed-in sessionApplies the change. 200 with the change; 403 for your own change, a change you may not decide or a requester who prepared your account; 409 when it was decided already; 422 when applying it failed
POST /companies/{id}/config-changes/{changeId}/rejectThe sameRejects the change. The same answers, without 422

A request that is held for review answers 202 Accepted: for company settings {"company": {…}, "pending": [ … ]} (see Company API); for policies, pools, identity providers and vulnerability exceptions {"pending": true, "change": {…}}.

A change has id, kind, target, summary, payload, requested_by, requested_by_id, status (pending, applied, rejected, failed), decided_by, decided_at, error and created_at.

Kinds of change:

Topickind
Change policiespolicy_create, policy_update, policy_delete, policy_reorder, policy_template
Approver poolspool_save, pool_delete
Risk settings and change freezesrisk_config
How people sign insign_in
The company directory (LDAP)directory
Identity providersidentity_provider_save, identity_provider_delete
Personal API tokenspersonal_api_tokens
Vulnerability exceptionsvuln_exception_create, vuln_exception_revoke
Switching this review offgovernance_off

Audit log​

ActionWhenWho is recorded
config_change_requestedA change was sent for review (with its kind and summary)The requester
config_change_approvedA change was approved (with its kind, summary, requester, and status applied or failed with the error)The approver
config_change_rejectedA change was rejectedThe person who rejected it

When an approved change is applied, the action of the change itself is written too, by the approver, with requested_by and approved_by: update_company for company settings, the policy and pool actions for policies and pools, identity_provider_updated or identity_provider_deleted, vuln_exception_created or vuln_exception_revoked. See Audit log.

How long the audit log is kept​

The Audit log card on the same tab sets how long the company's audit log entries are kept.

Setting (label in the UI)What it doesDefaultAllowed valuesWho can change itAPI field
Keep audit log entries for (days)Entries older than this are removed, about once an hour36530 to 3,650Company admins and platform admins, from a signed-in session (API tokens are refused: 403 API tokens cannot change audit_retention_days)audit_retention_days

A value outside the range is refused (400 the audit log is kept 30 to 3650 days). The platform's own entries (those of no company) are kept 365 days.

Video tutorial

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

Four-Eyes Review of Control ChangesYouTube ↗