Skip to main content
Every CI job should run on the image you tested. That holds only if the image reference in your pipeline points at one build, and nothing can change what it points at without you knowing.

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:
Any scheme works if it’s unique per build and easy to read, such as a date (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 add can 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 means latest, 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.

Cache the pinned tag before rollout

Once a tag is pinned, cache it on your nodes before you switch pipelines to it, so the first job on each node doesn’t wait for the download:
When you retire a tag, remove it from the nodes to free disk space (Orka 3.6.3 and later). Don’t remove an image while VMs are deploying from it.