Skip to main content
This page covers workspace image releases. For v0.13 incremental deployments, use app release rollback and rig app-release ls.
A workspace image release is an immutable record of what ran: an image digest plus its run-config. Every reproducible rig deploy (one whose rig.yaml sets reproducible: true) auto-records a release, giving you retained history to choose from. Because the image is content-addressed and frozen, activating an old release boots the workspace from the exact environment that release captured — not an approximate rebuild.

​
How releases are recorded

When rig deploy takes the reproducible path, it freezes the install: result into a content-addressed image and records a release pointing at that digest. Incremental deployments produce separate managed app releases, listed with rig app-release ls, rather than workspace image releases.

​
List release history

For a specific workspace, pass --workspace:

​
Roll back to a previous release

To return to a known-good version, activate its release. rig rollback --release activates an image release; without --release, rollback reverses a preview promotion:
Activating a release boots the workspace from that release’s frozen image digest. Review source mode and recorded run configuration: local-source overlays and Git-built image contents differ. Verify code and data compatibility after activation.
Rolling back changes the image and run-config, not your persistent volumes. Data under $DATA_DIR is unaffected by an activate — the image and recorded run configuration change. Verify the behavior of any local-source overlay separately.

​
Pin a release manually

If you have an image digest in hand — for example, from a rig build — you can create a release that points at it without going through a full deploy:
This is useful for promoting an image you built and tested separately, or for codifying a specific digest as a named release before activating it.

​
rig build: the explicit image build

rig build image is the explicit, standalone image build. It runs an install script once in an ephemeral builder VM on top of a base image (the same content-addressed mechanism rig deploy uses for reproducible: true) and returns a digest and cache key:
rig build ls lists your recent builds (including failed ones) and rig build logs <build-id> streams the builder VM’s install output — the first place to look when a freeze fails. rig build image is complementary to the auto-build inside rig deploy: deploy freezes and mounts in one step, while rig build image lets you produce a digest first and then pin it as a release with rig release create --image-digest. To pre-warm the cache for a project’s own rig.yaml instead, use rig deploy --build-only.

​
Putting it together

A typical reproducible workflow:
1

Deploy

rig deploy freezes (or reuses) the image and records a release automatically.
2

Inspect history

rig release ls --workspace my-project shows the linear history and which release is active.
3

Roll back if needed

rig rollback --workspace my-project --release <id> boots the previous release’s frozen image without rebuilding the image.
4

Pin a tested image

Build separately with rig build image, then rig release create --image-digest <d> to capture it as a release before activating.

​
Next steps