Skip to content
kix docs

Promote and verify an image pin

Use kix pin set to promote an existing image pin. This guide assumes the pin file is already loaded by your flake and the cluster reads the pin you want to update.

Promote the image

Section titled “Promote the image”

Pass the pin key and the new tag:

Run in kix-project/ 
❱ kix pin set web --tag 1.29-alpine

Kix keeps the pin’s repository, resolves the new tag through the registry, and writes the resulting digest to the pin file. It also records who performed the promotion and when it was resolved.

For a floating release tag such as main, run the same command whenever the tag’s image changes:

Run in kix-project/ 
❱ kix pin set web --tag main

The digest changes even though the tag remains the same. If the tag and digest already match the pin, Kix leaves the file untouched.

Review the committed change

Section titled “Review the committed change”

Inspect the pin before deploying it:

Run in kix-project/ 
❱ git diff -- pins.json

Then read the pin file back:

Run in kix-project/ 
❱ kix pin list --pins-file pins.json
web
  docker.io/nginxinc/nginx-unprivileged:1.28-alpine
  sha256:7377697a821c131a924a7105fafbe7414db4e9fcc77a6f08f776f33f141ec3f8
  promoted by [email protected], 2026-09-09T10:59:45Z

Check the repository, human-readable tag, and resolved digest. A promotion should change the pin you intended and no other key.

If your repository contains more than one pin file, continue passing --pins-file to each command so the target is explicit.

Verify the digest

Section titled “Verify the digest”

Check that the pinned digest is still available from the registry:

Run in kix-project/ 
❱ kix pin check --key web --pins-file pins.json

The check looks up the digest recorded in the file. If the tag now points to a different digest, Kix reports a warning, but the pinned digest remains the content Kubernetes will pull. A missing digest fails the check.

Run the check for every pin by omitting --key:

Run in kix-project/ 
❱ kix pin check

Record and verify the source revision in CI

Section titled “Record and verify the source revision in CI”

When CI builds the image, record the source revision during promotion:

Run in kix-project/ 
❱ kix pin set web --tag main --source-rev "$GITHUB_SHA" --promoted-by "ci:${GITHUB_RUN_ID}"
❱ kix pin check --key web --source-rev "$GITHUB_SHA"

The second command fails if the pin records a different source revision. This catches a workflow that built new source but did not update the pin.

Commit and deploy

Section titled “Commit and deploy”

Commit the pin file before deploying so another checkout evaluates the same image reference:

Run in kix-project/ 
❱ git add pins.json
❱ git commit -m "Promote web image"
❱ kix deploy production

Use the cluster name that consumes this pin in the final command.

Promote with a known digest

Section titled “Promote with a known digest”

In an air-gapped workflow, pass a digest obtained by the image-transfer process:

Run in kix-project/ 
❱ kix pin set web --tag 1.29-alpine --digest sha256:<64-hex-characters>

Kix validates the digest’s shape and records it without contacting a registry.