Skip to main content

​
Overview

In this guide you require a second person to review production changes to flags such as new-checkout. An approval policy holds the requested state separately from active configuration; SDKs keep evaluating the active snapshot until enough eligible reviewers approve. Prerequisites: an Enterprise plan to create a policy, and the admin or owner role to manage it. Existing policies keep protecting changes if your plan changes, and reviews, withdrawals, and policy management remain available for existing workflows.

​
Require production review

1

Create the policy

Open Settings → Organization → Approvals → Policies and choose New policy. Match production environments, require one approval, and leave Allow self-approval off. Lower priority numbers run first; the first matching enabled policy governs a change.
2

Submit a change

An editor changes new-checkout in production and clicks Save environment. The dashboard returns a pending request; the active flag and SDK snapshot stay unchanged. You need enough eligible reviewers other than the requester before a request can be created.
3

Review the immutable change

Reviewers find their assignments in the Approvals inbox. These are durable in-app notifications; shipd does not send approval email notifications. Inspect the requested state, then approve or reject it. Only currently authorized, assigned users can review. Management keys and service account tokens cannot approve.
4

Apply or withdraw

The final required approval applies the change. State, final decision, and audit evidence commit together. The requester can cancel a pending request to withdraw it; authorized admins and owners can also cancel. Submit a new request to change the requested state. Votes never transfer to replacement requests.
A request made through a creator-bound management key still belongs to that human for self-approval and withdrawal. Service accounts retain independent automation authority, but their token issuer is excluded from approving that token’s requests when self-approval is forbidden. Credentials without a known human issuer cannot submit under a no-self-approval policy; rotate the key or token.

​
Requests that need resubmission

Requests expire seven days after creation. Expiry is enforced whenever workflows are read or decided and before new submissions; a queued request cannot be applied after its deadline. Any approval-policy creation, update, or deletion invalidates existing pending requests in the organization. Changes to the flag definition, target state, production classification, or audience revisions in the project also make old requests stale at application. This conservatively includes audience changes unrelated to the requested rule. Resubmit against the new configuration. Identical decision retries return the committed outcome without another vote or audit event. If applying the final approval fails, that final vote and application roll back together; retry the same decision. Previously committed votes remain available, and only currently eligible reviewers count toward the threshold.

​
Push from CI

Terminal
A push containing queued requests exits with code 5 and JSON with outcome: "pending_approval" and approvalRequests. This means the requested defaults are not yet active. Save the request IDs and arrange human review; do not deploy on the assumption that the new defaults are live. --ci, --yes, and --force do not bypass approval. A repeated push with an existing pending request returns a conflict (exit code 3). After review, pull or diff again to inspect active state. Different flags can have different outcomes: unprotected defaults may apply while protected defaults queue.

​
Operations outside the request model

Requests currently represent flag environment state: enabled state, rules, and fallthrough. Definition changes, creation/archival, audience changes, environment production transitions, and project/environment archival are blocked when they affect a policy-protected environment. A config push containing such an unsupported operation fails as a whole, including when pushed against staging but affecting global definitions. Client labels and last-writer attribution never exempt a mutation. Rollout-increase policies use conservative exposure bounds and can require review when targeting overlap cannot be established precisely. Related: Approval workflows · CLI · Sync flags in CI · View the audit log.