> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pin CI images to versioned tags

> Deploy CI VMs from versioned image tags you control instead of latest or digests, so every job runs the image you tested and rollbacks are one change.

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:

```bash theme={null}
orka vm push <VM_NAME> <SERVER_ADDRESS>/<IMAGE>:<VERSION>
orka vm-config create <VM_CONFIGURATION_NAME> --image <SERVER_ADDRESS>/<IMAGE>:<VERSION> --cpu <CPU_COUNT>
```

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](https://docs.macstadium.com/orka/orka-resources/image-caching.md#known-issues).

## 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:

```bash theme={null}
orka imagecache add <SERVER_ADDRESS>/<IMAGE>:<VERSION> --all
orka imagecache info <SERVER_ADDRESS>/<IMAGE>:<VERSION>
```

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.

```bash theme={null}
orka imagecache remove <SERVER_ADDRESS>/<IMAGE>:<OLD_VERSION> --all
```

## Related pages

* [Orka image caching for faster VM deployments](https://docs.macstadium.com/orka/orka-resources/image-caching.md)
* [Deploy Orka VMs from an OCI image registry](https://docs.macstadium.com/orka/oci-images/oci-images-deploy-vms.md)
* [Save Orka VM changes to a local or OCI image](https://docs.macstadium.com/orka/oci-images/oci-images-preserve-changes.md)


## Related topics

- [Update macOS by rebuilding on a new base image](https://docs.macstadium.com/orka/orka-best-practices/new-images-for-macos-updates.md)
- [Prepare a VM before you push it to an image](https://docs.macstadium.com/orka/orka-best-practices/prepare-vm-before-push.md)
- [Bazel remote build execution for iOS and macOS with Orka](https://docs.macstadium.com/orka/orka-devops-integrations/bazel-rbe.md)
- [Manage macOS VM images with the Orka CLI](https://docs.macstadium.com/orka/orka-cli-reference/image-management.md)
- [Harness CI on Orka: Orka-side setup](https://docs.macstadium.com/orka/orka-devops-integrations/harness.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.