Changesets & Runs

This is where the model comes to life. Components describe desired state, but nothing moves until you stage changes, plan them, and apply them. Four resources cover that flow.

Changeset ───▶ Change ───▶ Run (plan + apply) ───▶ Revision
reviewable      one edit      one execution,        immutable
batch, per       to one        two phases            per-component
environment      component                           record

Changeset

A Changeset is a reviewable batch of changes scoped to one environment. It is the only way to mutate the environment's components.

Changesets behave like branches: many can be open at once against the same environment. You stage your work, review it in isolation, and apply when ready. A changeset is not an atomic transaction - it is a planning artifact, an authorization boundary, and an observation window.

admiral changeset create --env checkout/prod --name bump-postgres

Change

A Change is one staged modification to one component. A changeset holds at most one Change per component, and each Change is one of:

• create - add a new component
• update - modify an existing component's values or definition
• destroy - tear down the component's resources and remove it
• orphan - stop managing the component, leave its resources in place

A Change's content can be authored inline, prefilled from a Catalog Item, or copied from another changeset. Variable overrides ride along in the changeset too.

Run

Applying a changeset produces a Run - one execution carrying every changed component. Plan and apply are two phases of one run, not two separate runs.

Planning

When you plan a changeset, the server computes the dependency graph and creates one revision per component:

• components with no unresolved inputs are queued and planned immediately (the first graph layer)
• components that depend on another's outputs are deferred - their inputs do not exist yet

You review the plans that came back. Downstream components stay deferred until the upstream they need has actually applied.

Applying

There is a single approval gate: the transition from planned to applying. You authorize once. After that, the run walks the dependency graph one wave at a time:

1. the current layer applies
2. each component's outputs are captured
3. deferred downstream components render against those concrete outputs
4. they plan, then apply automatically (auto-continue)

...and so on until every component reaches a terminal state.

plan ──► PLANNING ──► PLANNED ──[ approve ]──► APPLYING ──► SUCCEEDED
                         ▲                          │
                         └──── wavefront cascades ──┘
                              (no further approvals)

Revision

Each changed component yields a Revision when it applies: the immutable snapshot of exactly what deployed, including the fully rendered values. Revisions are append-only history.

• A Revision belongs to one Run and one Component.
• A Component accumulates one Revision per run - that ordered history is its timeline.
• Rollback replays a prior Revision rather than mutating in place.

Concurrency: stale rejection

Because many changesets can be open against one environment at once, two of them might touch the same component. Admiral resolves this with optimistic concurrency: each changeset is based on the environment's deployed head at the time it was opened. If a parallel changeset applies first and moves a component you are also touching, your apply is rejected as stale. You discard and recreate against the new head.

This keeps a sight-unseen apply from quietly clobbering someone else's deployment.

Promotion

Promotion moves a tested change from one environment to another in the same application (dev to prod). It is a copy, not a link:

1. Admiral clones the changeset's Changes (and variable changes) into a new open changeset in the target environment.
2. Conflict detection re-bases on the target environment's own deployed head, because the target has its own state.
3. You review the diff against the target and apply.

The promoted changeset carries the same definitions you tested, but per-environment values resolve against the target's own variables, so you ship the same artifact configured for its destination. Promotion is same-application only.

Revert, not rollback

To undo a deployment you revert, following the Git model: reverting generates a new changeset that reverses the prior changes, which you review and apply like any other. It does not silently mutate state backward. Reverting a change that created resources produces create-style entries that an operator reviews before they apply.

Where to go next