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 does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Review control changes | When on, the changes listed below are not applied when saved: they wait until another administrator approves them | Off | On, off | Company 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 reviewed | Where the waiting change is shown | Who may decide |
|---|---|---|---|
| Approver pools | Saving and deleting an approver pool | Approver pools page, and the company page | Policy managers, company admins, platform admins |
| The company directory (LDAP) | Any change to the company directory settings, including a new bind password | Company page | Company admins, platform admins |
| Switching this review off | Turning Review control changes off | Company page | Company admins, platform admins |
| Identity providers (single sign-on) | Saving and deleting an identity provider | The identity providers card on the Sign-in tab | Company admins, platform admins |
| Whether people may make personal API tokens | Turning Let people make personal API tokens on or off | Company page | Company admins, platform admins |
| Change policies (adding, editing, deleting, reordering, templates) | Adding, editing, activating or deactivating, deleting and reordering policies, and applying templates | Change policies page | Policy managers, company admins, platform admins |
| Risk settings and change freezes | Any change on the Risk tab, and change windows and change freezes on the Change calendar tab | Company page | Company admins, platform admins |
| How people sign in | The Sign-in tab's settings, except identity providers and the directory, which are their own topics | Company page | Company admins, platform admins |
| Vulnerability exceptions (granting and revoking) | Granting and revoking a vulnerability exception | Insights → Vulnerabilities, in a box at the top of the page | Policy 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.
| Request | Who | What it does |
|---|---|---|
GET /governance/topics | Signed in | The topic keys, sorted: approver_pools, directory, governance_off, identity_providers, personal_api_tokens, policies, risk, sign_in, vulnerability_exceptions |
GET /companies/{id}/config-changes | Every role of the company, platform admins | The 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}/approve | Who may decide (above), signed-in session | Applies 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}/reject | The same | Rejects 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:
| Topic | kind |
|---|---|
| Change policies | policy_create, policy_update, policy_delete, policy_reorder, policy_template |
| Approver pools | pool_save, pool_delete |
| Risk settings and change freezes | risk_config |
| How people sign in | sign_in |
| The company directory (LDAP) | directory |
| Identity providers | identity_provider_save, identity_provider_delete |
| Personal API tokens | personal_api_tokens |
| Vulnerability exceptions | vuln_exception_create, vuln_exception_revoke |
| Switching this review off | governance_off |
Audit log
| Action | When | Who is recorded |
|---|---|---|
config_change_requested | A change was sent for review (with its kind and summary) | The requester |
config_change_approved | A change was approved (with its kind, summary, requester, and status applied or failed with the error) | The approver |
config_change_rejected | A change was rejected | The 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 does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Keep audit log entries for (days) | Entries older than this are removed, about once an hour | 365 | 30 to 3,650 | Company 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.
Related pages
- Companies: the company page and saving.
- Change policies: reviewed policy changes.
- Approver pools: reviewed pool changes.
- Identity providers: reviewed provider changes.
- Roles and users: the roles that may decide.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →