Approve changes and set deploy freezes
Decide pending approvals for protected environments, set the organization's change policy, skip approval for one service, schedule weekly deploy freezes and cap concurrent deployments in a project.
Every deploy, rollback, promotion and change set in a protected environment waits for an approval. This page covers deciding approvals, tuning the rules around them and unblocking a request nobody can approve. For how the pieces fit together, see Change sets and approvals.
Before you begin
| Action | Minimum role |
|---|---|
| Read approvals and the policy | viewer |
| Approve or reject | admin |
| Change the policy, turn on Skip production approval | admin |
| Change Deploy concurrency | admin |
A protected environment is one created with Protected: deploys here need an approval checked. A new project's Production environment is protected. The flag cannot be changed after creation.
Decide an approval
Open Approvals. The list has the filters Pending, Decided and All. Each row shows what was requested, who asked and the environment.
Select a request. The detail shows what runs now and what will run, the Checks, and the tabs Blast radius and Timeline. The tabs Commits and Config appear when the request carries commits or configuration changes.
Optionally type a note, then select Approve and deploy or Reject. A toast reads "Approved · TITLE" with "Rolling out now.", or "Rejected · TITLE" with "Nothing changes. The requester sees your note in Activity."
A service's Deployments tab also shows Review and Approve on a row that is waiting. Approve opens a dialog titled "Approve r-N for ENVIRONMENT?"; select Approve to confirm.
After you approve, the deployment leaves Awaiting approval and starts. After you reject, it ends Rejected and the current release keeps serving.
Rules that decide who can approve
- Only an
adminorownercan decide. Other roles see "Deciding needs the admin role or higher. Ask an admin to review it." - With Approvers can't approve their own requests on, you cannot decide a request you made. The page says "You requested this change, and your organization's policy forbids approving your own request. Another admin has to decide it."
- With it off, an admin or owner who makes a request has it approved at the moment they make it. It appears in Decided as "Approved automatically".
- A request made by a push to a tracked branch has no requester. It waits unless the service skips approval and the policy lets requesters approve their own requests.
- A request expires 24 hours after it was made. It then shows Expired, and its deployment is cancelled with "Approval expired after 24 h". Request the change again for a new approval. Approving an expired request fails with a message that begins "approval … expired at …".
During a deploy freeze, approving a request is refused, except a rollback. Rejecting is never refused.
Change the policy
Open Settings > Security & policy. Under Change policy you see three switches.
Turn a switch on or off. Each change saves at once and a toast confirms it, for example "Rollbacks now skip approval".
| Switch | Default | When on |
|---|---|---|
| Rollbacks skip approval | Off | A deployer rolls production back at once. Other changes still wait. |
| Approvers can't approve their own requests | On | Someone other than the requester decides, even if the requester is an admin. |
| Weekend deploy freeze | Off | Production deploys are refused in the freeze windows. |
Protected environments, on the same page, lists each protected environment and the rule that applies, such as "1 approval from Admins · not the requester".
Skip approval for one service
Open the service and select the Settings tab.
Turn on Skip production approval. The row reads "On · turned on by NAME".
Production deploys of this service, pushes included, start without waiting. Each is still recorded as an approval in the name of whoever turned the switch on. A change set skips approval only when every service it redeploys has the switch on.
If Approvers can't approve their own requests is on, the switch has no effect. The row says "On, but your organization requires a second person for production approvals, so deploys still wait".
Over the API, the operation is setServiceProductionApproval: PUT /api/v1/services/SERVICE_ID/production-approval with {"skip": true}.
Set a deploy freeze
A freeze refuses production deploys, redeploys, promotions and change-set requests in recurring weekly windows. Rollbacks stay allowed. Other environments are unaffected.
Open Settings > Security & policy and turn on Weekend deploy freeze. It saves at once. If no window exists yet, it adds one, Fri 16:00 → Mon 08:00. The time zone is UTC until you choose another.
Choose your Time zone. Each window has a start day and time and an end day and time, in the organization's time zone, as HH:MM from 00:00 to 23:59.
Select Add window for more windows, or the ✕ on a window to remove it. Select Save windows. A toast reads "Freeze windows saved".
- A window includes its start and excludes its end. A window that ends earlier in the week than it starts wraps through Saturday night into Sunday.
- A window cannot end where it starts. An organization takes at most 28 windows and one IANA time zone, such as
Europe/Berlin. - While a freeze is active, a frozen until badge appears beside the switch.
A refused request returns 403 with a message that begins:
production is in a deploy freeze until Mon 08:00 UTC; rollbacks are still allowed, or change the freeze windows in the organization's policyTo end a freeze early, turn off Weekend deploy freeze or edit the windows. Over the API, set freeze in updateOrganizationPolicy: enabled, timezone and windows of {"fromDay", "fromTime", "toDay", "toTime"}. Days run from 0 (Sunday) to 6 (Saturday).
Cap concurrent deployments
Open the project and select Project settings.
Enter a whole number of 1 or more in Deploy concurrency, then select Save. A toast reads "Saved" followed by the project's slug.
The default is unlimited. The limit counts deployments in progress across every environment of the project. It does not count deployments that wait for an approval, or the same service's own deployments in the same environment. One past the limit is refused, not queued, with 409 and a message that begins "N of M already running; wait for one to finish or raise the limit in project settings". Rollbacks count too.
You cannot clear a limit once set. Raise it instead. Over the API, the operation is updateProject with {"deployConcurrency": 3}.
Fix "no one else in this organization can approve it"
A request can wait for a decision nobody is allowed to give. With the default policy, you are the only admin or owner and you made the request, so the deployment shows:
Waiting for approval, but no one else in this organization can approve it: your policy forbids approving your own deploys and you are its only admin. Invite another admin, or turn off "Approvers can't approve their own requests" in Settings > Security & policy.Pick one fix:
- Invite another admin or owner. See Members and teams. They decide the request in Approvals.
- Turn off Approvers can't approve their own requests in Settings > Security & policy, then approve your request yourself in Approvals. A pending request is judged under the policy in force when it is decided.
Turning the switch off removes the second-person check for every protected environment in the organization. Skip production approval does not help while the switch is on.
If you do nothing, the request expires after 24 hours.
Get notified
When a request waits, every admin and owner except the requester receives an approval notification titled like "Approval needed: roll back SERVICE to ENVIRONMENT". A request that is approved at once sends none. To route these to Slack or PagerDuty, see Notifications.
Verify
- A decided request appears under Decided in Approvals, and its deployment leaves Awaiting approval.
- After a policy change,
getOrganizationPolicyreturns the new values. While a freeze is active, it also returnsfrozenUntil.
Next steps
Deploy a preview for each pull request
Turn on pull request previews for a project so every same-repository pull request gets its own environment, deployed from its branch and deleted when the pull request closes or goes idle.
Read logs and metrics
Tail and search a service's logs, read build and deploy logs, and read the Metrics tab and the numbers on each canvas card. Also covers opting a worker's own metrics in.