Use a versioned tag you control
Push your CI image to your own registry under a tag that names one build, and deploy that tag:xcode-26.2-2026-11-18) or a counter (v14). To roll out a new image, point the VM config or pipeline at the new tag. To roll back, point it at the old one.
Push each change to a new tag
Don’t overwrite a tag you’ve already used. With a new tag for every build:- You can tell which build a job ran from its VM config or pipeline log.
- The previous build stays in the registry under its own tag, ready for a rollback.
- Image caching stays predictable.
orka imagecache addcan skip re-caching an image whose name and tag haven’t changed. See the known issues in Orka image caching.
Avoid latest in CI
An image reference without a tag meanslatest, for both orka vm deploy and orka vm push. latest moves whenever a new build is published. MacStadium’s base images in ghcr.io/macstadium/orka-images move latest when a new build ships, and some, such as golden-gate, are published only as latest.
If one node cached latest before an update and another node cached it after, the same pipeline runs two different builds depending on where each VM lands. Start from latest if you need to, but build your CI image from it and push the result under your own versioned tag. Pin that tag in CI.
Don’t reference images by digest
Orka resolves images by tag. Digest references such as<IMAGE>@sha256:<DIGEST> aren’t supported in orka vm deploy, VM configs, or orka imagecache add. Orka drops the digest and uses the image’s latest tag instead, and on a private registry the deploy can fail with Unauthorized.
To pin a specific build, give it a versioned tag and use the tag.

