Pin the Digest Your GitLab Job Pulled, Not the Tag You Remember

A Friday job appeared green, but the same commit failed on Monday. The issue may lie in the base image moving while the repository remained unchanged. Tags such as node:22 and python:3.12-slim represent names, not fixed images. A registry can replace the contents under the same name at any time.

This guide is for individuals who manage a single service repository on GitLab CI and examine agent-written YAML files. You will learn to resolve a public image to a digest, choose between index and platform options, and reject a job file that remains unchanged.

A tag points to a manifest, which could be a single image or a multi-architecture index. The index digest and the linux/amd64 digest are distinct objects. Pinning the incorrect one will result in the job failing on the runner you are using or succeeding on your local machine but failing in CI. The executor also plays a role. A Docker or Kubernetes executor pulls the image directly, while a shell executor does not. If the job log does not mention a pull, pinning the digest will not affect the job's root filesystem.

The GitLab Runner accepts an image reference containing @sha256: followed by 64 hexadecimal characters. Confirm the current keyword rules in the CI/CD YAML reference before modifying the YAML file based on a syntax detail. A pull policy is still applicable, but a digest specifies the content. Using pull_policy: always on a floating tag will fetch the latest content served by the registry.

To complete the task, you need three essential components: the image line from .gitlab-ci.yml, the runner architecture you are actually scheduling (often linux/amd64), and a host that can reach the public registry with crane or skopeo installed. Do not include registry passwords, deploy tokens, or CI_JOB_TOKEN in your communication. Public images do not require authentication, while private images should be run on a trusted runner, not in a draft session.

Follow these six steps to successfully pin the digest:

1. Copy the reference exactly as it appears in the .gitlab-ci.yml file, including the registry host if it is not Docker Hub.

2. Determine the executor architecture by reviewing a recent job log for that job name. Search for a pull or a line that names the image used by the executor. If the log shows a digest, note it down. If the log displays a shell executor with no pull, write "image key unused" in the review and skip pinning for that job.

3. Resolve both digests using a machine with crane. Run the following commands (proposal):

a. crane digest --platform linux/amd64 $ref

b. crane manifest $ref | head -c 400

If the outputs match, you are dealing with a single-platform image. If they differ, choose the appropriate digest based on your runner configuration.

4. Pin the chosen digest by adding it to the merge request in a single line, such as pinned index or pinned linux/amd64. Keep the tag as a human-readable hint, but the digest is the actual pin.

5. Update the image line in the YAML file, replacing the tag with the digest. The digest now takes precedence over the tag.

6. Add a reject rule in the review process to prevent future floating image references. Create a script called reject-floating-images.sh to automate this process and ensure all images in the repository are properly pinned.

By following these steps, you can ensure that your GitLab CI jobs are running with the correct digests, avoiding potential issues caused by image name changes and ensuring consistent results across different runners.