Change sets and approvals

A change set is one person's staged edits to one environment, reviewed as a diff and applied together. An approval is the sign-off a protected environment requires before a deploy, rollback, promotion or change set takes effect. Together they decide when a change reaches your cluster and who is accountable for it.

Change setsCopy Anchor Link

When you edit a service or an environment in the console, the edit is staged, not applied. The console keeps your staged edits in a draft for that environment, and a staged bar appears at the bottom of the canvas and the service panel: 3 staged changes, Discard, and the action that ships them.

A change set holds edits of these kinds:

• variables you set or delete,
• replicas, instance size and volume size,
• the auto-deploy setting,
• releases, and the first deploy of a newly created service,
• a Postgres database's automatic-failover setting.

Review and applyCopy Anchor Link

1. Select the staged bar's count to list every staged line under the service it belongs to.
2. Select the action: Deploy N changes in an unprotected environment, Request approval in a protected one. The Review N staged changes dialog opens.
3. Optionally write a commit message of up to 500 characters in Describe this change (optional). Each line has an undo.
4. If a service mounts a volume, select Accept downtime. The running release stops before the new one starts, so the service is briefly unavailable.
5. Select Deploy N changes or Request approval in the dialog to apply. Choose Discard all to drop the draft, or Keep editing to go back.

Applying starts one deployment per affected service, in dependency order, databases first. In a protected environment, applying instead creates one approval for the whole change set.

The apply is atomic. If a value changed under you since you staged it, for example because someone else edited the same variable, nothing is applied and the dialog says to undo or restage the lines that drifted. Your draft is kept.

A change set is in one state: draft, pending-approval, applied, rejected, discarded or failed. Discarding a draft that created a service removes that service, because it only existed in the draft.

Changes that arrive as change setsCopy Anchor Link

Other ways to change an environment stage the same kind of draft, so they get the same review:

• Installing a template or importing a Compose file stages the new services, with their first deploys, for you to review.
• Adding a service from a project's canvas stages its first deploy.
• A project nebula.toml stages one change set per environment on every push to the tracked branch. Those change sets belong to the project, not to a person, and anyone who may deploy to the environment can apply them.

ApprovalsCopy Anchor Link

Only protected environments, those marked as production, need approvals. Every action that starts a deployment there creates one: a deploy, a redeploy, a rollback, a promotion, a release made by a build, and an applied change set. The deployment stays in awaiting-approval, and nothing reaches the cluster, until someone decides.

An admin or owner decides on the Approvals page, which lists requests under Pending and Decided, or from the Approve button next to the blocked release. Approving starts the deployment. Rejecting ends it as rejected. A request nobody decides expires after 24 hours, and the deployment it gated is cancelled.

Approving a request also ends older pending requests for the same service, because the deployment it starts supersedes them. A waiting approval raises a notification in members' inboxes, and it can go to Slack or PagerDuty channels too. See Notifications.

When an approval passes at onceCopy Anchor Link

An approval is still created and recorded, with who passed it and why, but it's decided the moment it is requested when one of these holds:

Rule	Passes when
Rollbacks skip approval	The organization's Rollbacks skip approval policy is on and the request is a rollback.
Requester can decide	The requester is an admin or owner and the organization's Approvers can't approve their own requests policy is off.
Skip production approval	The service has Skip production approval on, set by an admin, and self-approval isn't forbidden. It covers every production deploy of the service, including pushes, which have no requester. A change set passes this way only when every service it redeploys has the setting on.

The self-approval policy is on by default. With it on, someone other than the requester must approve every production request that isn't a rollback allowed to skip. If you're the only admin, no one else can approve, and 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.

Deploy freezeCopy Anchor Link

A deploy freeze is a recurring weekly window, in a time zone you choose, during which production deployments are refused. Rollbacks stay allowed, because a rollback returns production to something that already ran there. A request during a freeze is refused at once with the end of the freeze. It isn't queued.

You turn on Weekend deploy freeze under Settings > Security & policy in Change policy and edit its windows there.

Concurrency limitCopy Anchor Link

Deploy concurrency in a project's settings caps how many deployments run at once across the project. It's unlimited until you set it. A deployment past the limit is refused rather than queued. See Deployments.

BoundariesCopy Anchor Link

• An unprotected environment has no approvals. A deploy there starts when you apply it.
• The freeze, the self-approval rule and the concurrency limit apply to every path, including pushes and change sets.
• An API token with the admin role can decide approvals, and the decision is recorded under the person who created the token. Cluster agents can't decide approvals.

RelatedCopy Anchor Link

• Approvals and freezes: the console steps and every setting.
• Deployments: what happens after an approval.