Drive deploy-tools from CI#

In normal use, nobody should run sync, validate or compare by hand. Those commands touch a shared deployment area, so they belong to a CI pipeline in the configuration repository, gated by change review. End users only edit configuration and open a change; merging it deploys.

This guide describes what that pipeline must do. It is deliberately independent of any particular CI system — translate the responsibilities below into your own.

On a proposed change#

When someone opens a change (before it is merged), run, without altering the area:

  • deploy-tools compare <area> — confirm the area still matches its last snapshot, so the change is being checked against a known-healthy baseline.

  • deploy-tools validate <area> <config> — confirm the new configuration is valid and its lifecycle transitions are permitted. Add --test-build to build every changed Module in a temporary directory, catching build failures before merge.

This gives reviewers a green light that the change is deployable without changing anything on the filesystem.

On acceptance#

When the change is merged to the main branch, deploy it:

  • deploy-tools compare <area> — re-check the area is healthy immediately before the sync.

  • deploy-tools sync <area> <config> — validate again, build, and move the results into place.

Run one at a time#

deploy-tools has no locking of its own. The pipeline must ensure only one run touches the area at a time — two concurrent syncs, or a sync racing a compare, can corrupt the area or report false drift. Serialise the relevant jobs (and, if possible, restrict them to a single runner).

Manual operations#

Some tasks fall outside the automatic flows and are best run from a manually-triggered pipeline, exposing the relevant options as parameters:

  • The first deployment. A brand-new area has no snapshot to compare against, so it is run manually rather than triggered by a merge. Use --from-scratch, which assumes the area is empty: compare --from-scratch to confirm it, then sync --from-scratch to deploy. This path is walked through in your first deployment.

  • Comparing against an earlier snapshot. compare --use-ref <ref> compares the area against the snapshot from an earlier commit (e.g. HEAD~1), to check how it matches the configuration from before the last sync.

  • Forcing blocked transitions. --allow-all (on validate/sync) permits lifecycle transitions that are otherwise rejected, such as removing a live version. The area must still be healthy.

See snapshots and the compare safety net for how these fit into recovery.