Approvals, freezes and schedules
Require approvals, freeze deploys, and schedule releases for a chosen time.
Decide who may ship and when: require approvals before a release reaches traffic, freeze deploys for an app or organization, and schedule a release for a time your team is around to watch.
Release approvals
Require people to approve each production release before it takes more than its first canary stage:
# Two owners or admins, other than the deployer, approve every release.
gregale release approval require --approvals 2 --notify releases
# One person, developers included, within four hours.
gregale release approval require --approvals 1 --approvers developer --timeout 4h --notify releases
gregale release approval pending # releases waiting right now
gregale release reject <deployment> --reason "checkout latency is up"
gregale release approval status <deployment>
gregale release approval disable
A production release is one to the default scope or to the project's
production environment (--environment production); both serve the app's
production traffic, so the policy gates both. Other environments and scopes
are not gated.
The release starts its canary as usual. At the stage the policy names
(--after-stage, default 1), it waits. gregale deploy shows the wait. The
canary still judges the waiting stage, so a regression aborts the release
even while it waits. Once enough people approve, the rollout continues on its
next step.
A release with a release command (a migration) waits earlier: after its
build, before the command runs, because a migration changes production data
the moment it runs and aborting a canary does not undo it. It is listed in
gregale release approval pending like any waiting release, for the same
timeout. Once approved, the command runs and the release rolls out without
waiting again. If it is rejected or times out, the deployment fails without
running the command and production keeps the current release. When it is
approved, Gregale checks again before running the command:
- A newer release: if you deployed a newer release of the app to the same environment meanwhile, this one is superseded and its command never runs.
- The break-glass pause: it waits until the pause is lifted.
- A deploy freeze: a freeze that started after you deployed fails it
with
release_frozen. A freeze you overrode when deploying does not. - Its schedule: a scheduled release whose schedule ended (expired an hour after its time, blocked or cancelled) before it was approved fails without running its command. Deploy and schedule it again.
A newer release that failed or was cancelled does not replace one that waits; only a newer release that can still ship does.
The app's first production release has no canary to wait in, so its command runs at once.
A person approves on the release's approval page in the dashboard
(/dashboard/releases/<deployment>/approval, linked from the notification),
signed in (with MFA when the account uses it). An API key, the CLI's login token or a CI job cannot
approve: gregale release approve answers 403 release_approval_session_required with the page's link. Rejecting works
from anywhere, because stopping a release needs no second person.
The policy stays in force until an owner or admin removes it. Changing or
removing it needs the admin scope (signed in, the CLI's login or an admin
key), so a CI key with deploy:write cannot switch it off; the same holds for
deleting a release gate. An app with a policy cannot leave request mode
(409): a service, worker or job has no canary stage to wait in, so its
releases would ship unapproved. Remove the policy first.
Waiting ends in one of three ways:
- Enough approvals: the rollout continues.
- A rejection: the rollout is aborted at once (rule
abort_approval_rejected), and the previous release takes its traffic back. - The timeout passes (default 24 hours): the rollout is aborted in the
same way (rule
abort_approval_timeout).
While a release waits, nothing gives it more traffic: not canary advance,
rollouts recover --action promote, traffic set, or
POST /v1/deployments/{id}/promote. Rollbacks and aborts are never held.
Who may approve:
- Approvers: with
--approvers admin(the default), organization owners and admins;developeradds developers. - The deployer: their own approval does not count unless you pass
--allow-self-approval. An app outside an organization has one person, whose own approval always counts. A GitHub push names a GitHub login, not a Gregale account, so its author can't be recognised; without--allow-self-approvala pushed release needs one more approval than the policy asks. - Once approved: a release that has its approvals is decided. Further approvals and rejections are refused; to stop it, abort its rollout.
- Changing the policy: only owners and admins can change or remove it.
Tell people when a release waits, is approved or rejected, or times out:
echo "https://hooks.slack.com/services/…" | gregale alert channel create --name releases --kind slack --secret-stdin
gregale release approval require --approvals 2 --notify releases
--notify takes one to five Slack or email channels and is required, so the
approvers learn a release is waiting; PagerDuty channels are refused, because a
release waiting for approval is not an incident. Each
event is sent once per release.
The Slack message for a waiting release has Approve, Reject and
Review buttons, and the email has the same links. They open
/dashboard/releases/<deployment>/approval in Gregale; if you are not signed
in, Gregale asks you to sign in first. The decision is made on that page,
under your own Gregale account, so your organization role, MFA and the
self-approval rule apply exactly as in the CLI. The buttons grant nothing by
themselves.
Releases need a canary to wait in. While the policy is on, a production
release with --rollout immediate or --traffic-percent is refused with
release_approval_canary_required. A release deployed with --no-traffic
can't be given traffic by hand either; start it with
gregale release schedule set <release> --at now, which rolls it out
through a canary that waits for approval.
Production means the default scope and a project's production
environment, as for freezes. Releases that have no canary to wait in are
refused the same way:
gregale release retryof a release that had no canary;- a project apply that would release the app;
- a promotion into a
productionenvironment that is not protected.
Protect the environment (gregale environment protect <project> production) and its promotion approval stands in for the app's policy.
That approval comes from a person signed in, not an API key or token, and on
a company app from someone whose role the policy lets approve.
A GitOps source releases into production only once a person approved the
revision in Gregale (approval policy manual); with protected_branch the
sync waits until you remove the app's policy or switch the source to manual
approval. That one approval stands in for the app's policy only when a person
gave it, the policy asks for one approval and, in an organization, the
approver holds a role the policy lets approve; otherwise the sync waits. An
API key's approval of the revision does not count: approve the same revision
on the environment's GitOps page in the dashboard.
While a policy or a pending scheduled release names a channel as its last
Slack or email channel, that channel can't be deleted (409 notification_channel_in_use): name another channel there first.
The app's Release safety page in the dashboard
(/dashboard/apps/<app>/release-safety) shows the policy and the releases
waiting for approval, next to the app's freezes, gates and scheduled
releases.
Deploy freezes
A freeze stops new production releases of one app, or of all of its owner's apps, while it is active:
# Freeze one app for two hours, starting now.
gregale release freeze create --app my-api --for 2h --reason "incident 4711"
# No releases from Friday 16:00 to Monday 08:00 (64 hours), Istanbul time, for every personal app.
gregale release freeze create --all-apps --weekly fri --at 16:00 --for 64h --tz Europe/Istanbul --reason "no weekend releases"
# After Gregale rolls a release back on its own, freeze the app for an hour.
gregale release freeze create --app my-api --after-rollback 1h --reason "settle after automatic rollbacks"
# Freeze every app of the company organization acme for three days.
gregale release freeze create --org acme --for 72h --reason "holiday freeze"
gregale release freeze status --app my-api
gregale release freeze list [--app my-api | --org acme]
gregale release freeze lift <id> [--app my-api | --org acme]
A company organization owns the freezes of its apps, whoever created the app.
A freeze on all apps with --org covers every app of that organization; a
freeze with --all-apps covers only your personal apps. On a company app,
every member sees its freezes, and a member who deploys can freeze it with a
window and lift a window they created. Weekly and after-rollback freezes are
standing policies, so only owners and admins create them, and they can lift
any freeze. A company's freezes stay when the member who created them leaves,
and they appear in the organization's activity.
While a freeze is active, every way of releasing to production is refused
with release_frozen, which names the freeze, its reason and its creator:
gregale deployand the deployment API;- GitHub push deploys;
gregale deploy --project;- promotions into
production; gregale release retryand the dashboard's retry button. A retry can't carry an override; deploy again with--override-freezeinstead.- giving traffic to a release deployed without traffic before the freeze
began (
traffic, promote, or a rollback to it): it has never served, so it waits like a new deploy. A release deployed during the freeze, or one that served before, is not refused. - a rollback to a release that never served, even after a newer release replaced it. A rollback can't carry an override, and a rollback to a rejected release is always refused.
A GitOps source managing the production environment keeps its sync
unconverged while a freeze covers one of its apps, and activates the new
revision once the freeze ends.
A freeze covers the default deployment scope and the production
environment.
It never blocks:
- rollbacks;
- rollouts that were already in progress;
- previews and other environments;
- env and secret changes.
To release anyway, give a reason:
gregale deploy --override-freeze "hotfix for incident 4711"
gregale environment promote shop --from staging --to production --override-freeze "hotfix"
The override is recorded in the audit log (release.freeze_overridden) with
the freezes it overrode and the deployment it created. A company
organization's freeze is overridden only by someone who may lift it: an owner
or admin, or the member who created the window, signed in or with an admin
key. Anyone else, and a key that can only deploy, gets 403 release_freeze_override_not_allowed. Lifting a freeze needs the admin scope
too; a CI key with deploy:write cannot lift one. A GitHub push can't carry an override, so a frozen
push fails, and the commit shows why.
An --after-rollback freeze is a policy. Each time the rollout circuit
breaker, the post-release watch, the first-wake 5xx guard or an alert rule
rolls an app back, Gregale freezes that app for the given time. The freeze
names the release that was rolled back, and you can lift it like any other.
If that rollback does not restore the previous release, Gregale lifts the
freeze again: the release still serves, and its fix has to ship.
Platform release pause
While Gregale handles a security incident, it may pause new releases for
every account. Deploys
and new schedules then fail with 503 platform_release_paused, which nothing
in the request overrides. A release you deployed earlier with --no-traffic
can't take its first traffic during the pause either. Queued builds wait, and
scheduled releases start once the pause is lifted. A release deployed before
the pause still finishes its build, but its release command (a migration)
waits for the pause to be lifted. Your running apps keep
serving, rollbacks to a release that served before still
work, and you can still change env vars and secrets, so you can rotate a
credential during the incident. Retry the deploy after the pause is lifted.
Scheduled releases
Build a release now and start it later: at a quiet hour, at a launch time, or when the team is around to watch:
# Build now; start the rollout at 02:00 local time and tell #releases how it went.
gregale deploy --at 02:00 --release-notify releases
# Other ways to say when: +2h, "2026-10-22 09:00" (local time), or an RFC 3339 time.
gregale deploy --at "2026-10-22 09:00" --rollout fast
gregale release schedule list
gregale release schedule get v44 --app my-api
gregale release schedule set v44 --app my-api --at +30m # move it
gregale release schedule set v44 --app my-api --at now # start it on the next pass
gregale release schedule cancel v44 --app my-api
The build, readiness check and snapshot happen right away, so a broken build
shows up while you are still there. The release then waits live without
traffic; production stays on the current release, and nothing wakes the
waiting one. At its time, Gregale starts the rollout the deploy would have
had: the same canary (--rollout safe or fast, or the app's release
policy), or all traffic at once for --rollout immediate.
Because the build and any release command (a migration) run as soon as you
deploy (once approved, when the app requires approvals), a freeze active
right now refuses a scheduled release just as it refuses an immediate one,
even when the scheduled time falls after the freeze. Wait for it to end, or deploy with --override-freeze REASON.
Just before it starts, Gregale checks again:
- Freezes. A freeze active at that moment stops the release, including a
freeze created after you scheduled it. Scheduling into a freeze you know
about needs
--override-freeze REASON, which covers exactly the freezes active at the scheduled time. Overriding a company organization's freeze this way needs the same right as an immediate override: someone who may lift the freeze. - Approvals. If the app requires approvals, the release must roll out through a canary, and it waits for approval in that canary like any other release. A policy added while the release waited applies to it.
- Newer releases. If a newer release serves traffic by then, the scheduled one is superseded and never starts.
If the build is still running, or another rollout is still in progress,
Gregale waits for up to an hour past the scheduled time, then gives up
(expired). A release that could not start stays built without traffic:
schedule it again, or promote it by hand. --release-notify channels (Slack
or email, up to five) hear when the release starts and when it can't.
While a release waits for its time, gregale release traffic set and gregale traffic promote refuse it with release_scheduled; move or cancel the
schedule instead. gregale release traffic promote --release v44 --at 09:00
schedules a release you deployed with --no-traffic.
A scheduled release is a production release of a request app: previews, named environments, services, workers and jobs release immediately. An app has one pending schedule at a time; scheduling another release cancels the earlier schedule and leaves that release waiting without traffic.
Spotted a problem on this page? Tell us