> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useshipd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Approval workflows

> Policy scope, request states, reviewer eligibility, audit events, and config push outcomes.

## Overview

Approval enforcement runs on the server for dashboard, API, CLI, and service-account mutations. SDK evaluation uses only active configuration. A notification or supplied request ID never authorizes a write.

## Policy matching

| Field | Meaning |
| - | - |
| Organization | Policies and requests belong to one organization. |
| `projectIds` | Optional project scope; omitted or empty means all projects in the organization. |
| `environmentIds` | Optional environment scope within the selected projects. |
| `environmentProduction` | Match production (`true`) or non-production (`false`); omitted matches either. |
| `minRolloutIncrease` | Minimum increase in percentage points, using conservative targeting bounds. |
| `priority` | Lower numbers run first; the first enabled matching policy wins. |
| `requiredApprovals` | Number of distinct eligible users required, from 1 to 20. |
| `reviewerRoles`, `reviewerTeamIds` | Union of selected roles and teams, restricted to users currently authorized to review the project. |
| `allowSelfApproval` | Whether the responsible human requester or credential issuer can approve. Defaults to false. |

All project, environment, and team references must belong to the organization. Policies apply across dashboard, CLI, API, and service-account changes; they cannot be restricted to a particular client or last writer.

Policies are frozen into requests. Editing, deleting, disabling, or adding any policy invalidates pending requests in the organization rather than changing the meaning of recorded votes.

## Request lifecycle

| Status | Meaning |
| - | - |
| `pending` | Active state is unchanged. Votes are collected against immutable requested state. |
| `approved` | The requested change was applied transactionally. |
| `rejected` | A reviewer rejected the request; it cannot be applied. |
| `cancelled` | The requester withdrew it or an authorized user cancelled it. |
| `stale` | Policy or resource revisions changed; submit a replacement request. |
| `expired` | The seven-day deadline elapsed; submit a replacement request. |

There is at most one pending request per flag/environment pair. To revise intent, cancel and resubmit. Identical decision retries are idempotent; changing the comment or decision of an existing vote is a conflict. Terminal requests cannot be reopened.

Review authorization is checked at decision time. Removed, banned, demoted, or otherwise ineligible users cannot review, and their earlier votes do not count toward application. Reviewer assignments form the durable inbox notification; repeated reads do not duplicate it. Approval emails are not sent.

## Config and CLI outcomes

| Outcome | CLI exit | Meaning |
| - | - | - |
| Applied/no changes | `0` | The requested applicable state is active, or there was no drift. |
| Pending approval | `5` | At least one default change queued; JSON includes `approvalRequests` and `outcome: "pending_approval"`. |
| Conflict | `3` | Examples: existing pending request, stale versions, or an unsupported operation affecting a protected environment. |

`--force` bypasses ordinary sync version conflicts only. It cannot bypass policy, immutable approval revisions, or review authorization. Non-interactive confirmation flags do not constitute approval. Mixed default-only pushes may apply some unprotected defaults and queue others; pushes with unsupported protected definition operations roll back entirely.

## Audit evidence

Request creation, approvals, rejection, cancellation, expiration, policy invalidation, and application produce per-request audit events. Approved mutations also produce the linked `flag.environment.updated` event. Decision comments are included subject to audit redaction. Events and export deliveries commit with their mutation; duplicate decisions do not append duplicate events.

Audit evidence remains subject to its retention policy after organization deletion. See [Audit log](/reference/audit-log#retention) for retention and deletion rules.

Related: [Review production changes](/operations/approvals).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.