# Pin Docker Base Images by Digest

Yes. An agent resolves every floating FROM and image: tag in your Dockerfiles and Compose files to its digest, adds Dependabot updates for them and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/pin-image-versions/docker/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent first lists every image reference the repository pulls. In a multi-service app like dockersamples/example-voting-app that is four Dockerfiles and three Compose files: `vote/Dockerfile` starts `FROM python:3.11-slim AS base` and builds `dev` and `final` stages on it, `result/Dockerfile` starts `FROM node:18-slim`, `worker/Dockerfile` builds on `mcr.microsoft.com/dotnet/sdk:7.0` with `--platform=${BUILDPLATFORM}` and ships on `mcr.microsoft.com/dotnet/runtime:7.0`, and `seed-data/Dockerfile` uses `python:3.9-slim`. `docker-compose.yml`, `docker-compose.images.yml` and `docker-stack.yml` all name `redis:alpine` and `postgres:15-alpine`, and the five Deployments under `k8s-specifications/` repeat the same two plus the published `dockersamples/examplevotingapp_*` images with no tag at all. None of these carries an `@sha256:` digest, so two builds a week apart can get different bytes under the same tag, and `redis:alpine` can change major version without a diff anywhere in the repository.

For each reference it then asks the registry what the tag points at today. For Docker Hub images that is a token from `auth.docker.io` and a `HEAD` on `registry-1.docker.io/v2/library/<image>/manifests/<tag>` with the OCI index and manifest-list media types accepted, which returns the `Docker-Content-Digest` of the multi-platform index; `mcr.microsoft.com` answers the same request with no token. The index digest is the one to pin, because the `worker` image is built for `linux/amd64`, `linux/arm64` and `linux/arm/v7` through the `dockersamples/.github` reusable workflow the three `call-docker-build-*.yaml` files call, and a per-platform manifest digest would break two of those three. The agent writes each line as `FROM python:3.11-slim@sha256:…`, keeping the tag in front of the digest so a reader still sees which version it is and so Dependabot can offer a newer one, and does the same for `image:` lines in the Compose files and Kubernetes manifests.

Pinning without updates would freeze the app on old bytes, so the agent extends `.github/dependabot.yml`, which today lists only the `github-actions` ecosystem on a monthly schedule, with a `docker` entry per directory that holds a Dockerfile (`/vote`, `/result`, `/worker`, `/seed-data`) and a `docker-compose` entry for `/`, the ecosystem Dependabot documents for Compose files. From then on a new image build under the same tag arrives as a pull request that moves the digest, and a new tag such as a later `postgres:15-alpine` build arrives the same way. While resolving tags the agent also reads the registry's tag lists and reports what it finds there rather than silently upgrading: `node:18` and the .NET 7.0 images are past the end of their support, and `mcr.microsoft.com` lists `8.0`, `9.0` and `10.0` runtime tags; those version moves are a separate decision for the maintainer and are named in the pull request, not made in it.

To check the result the agent installs Docker in its sandbox with `sudo apt-get install -y docker.io` and starts `dockerd`, since the sandbox has none, then runs `docker build` for each of the four Dockerfiles and `docker-compose config` (the v1 binary, since the `docker.io` package does not carry the v2 plugin) on the Compose files to confirm the pinned references parse and pull. It also runs `docker buildx imagetools inspect` on one pinned reference to show that the digest resolves to a multi-platform index, and it diffs the `docker-compose.images.yml` output against the original to show that only `image:` lines changed.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Pin every base image and service image in this repository by digest. Find each FROM line in every Dockerfile and each image: line in the Compose files and Kubernetes manifests, and for each tag resolve the digest of the multi-platform index from its registry, so the pin works for every platform the images are built for. Rewrite each reference as tag@sha256:digest, keeping the tag. Add docker ecosystem entries to the Dependabot configuration, one per directory that holds a Dockerfile, and a docker-compose entry for the repository root, so the digests keep moving. Do not change any image's version; instead list in the pull request any tag whose version is past the end of its support, with the newer tags the registry offers. Install Docker, build each Dockerfile and validate the Compose files with the pinned references, and open a pull request with the build output and a table of every reference, its old form and its digest.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes every `FROM` and `image:` line that named a tag, adds the `docker` and `docker-compose` entries to `.github/dependabot.yml`, and touches no application code. Its description holds a table with one row per reference: the file, the old reference, the digest now pinned and the registry it was read from. Below it are the `docker build` output for each Dockerfile, the `docker-compose config` output and the one `imagetools inspect` listing that shows the platforms behind a pinned index.

A separate section lists the tags whose version is no longer supported and the newer tags the registry offers, so the maintainer can open their own upgrade after this merges. A reviewer checks that each digest is an index digest rather than a single-platform manifest, which the inspect output shows, and that the Dependabot directories match where the Dockerfiles live. After merging, the next Dependabot run opens one pull request per image whose tag has moved to a new build, each with the registry's release notes link where the registry publishes one.

## Run it on every Monday morning

Pinning is a one-time change, but the digests go stale every time a base image is rebuilt, so the ongoing work runs on a schedule. A team adds an automation to the Project with a `schedule` trigger, `cron` set to early Monday in their `timezone`, and a prompt that asks the agent to re-resolve every pinned reference, rebuild the images and report which digests moved and whether any tag has reached end of support. An automation's runs are read-only, so the report lands as the run's answer, and the Dependabot pull requests carry the actual digest moves.

A team that wants the agent to make the moves itself instead of Dependabot starts the run from its own server with this body each Monday, with a `request_id` that is a UUID v5 of the week's date, so a retried start returns the run already running rather than a second pull request.

## Why run it on Rush?

The job is a long list of registry calls that each has one right answer and one wrong one: the index digest or a per-platform one, the tag kept or dropped, the Compose file read or missed. The agent makes every call in its own sandbox, keeps each request and the digest it returned in the run's record, and then installs Docker and builds the images with the pinned references so the pull request shows they pull, instead of a reviewer finding out on the next deploy.

It also stays inside the line the job draws: pins the bytes that already ship and names the version upgrades that are waiting, rather than mixing a digest change nobody needs to review with a runtime upgrade everybody does. Several repositories with several registries get several pull requests, each with its own table and its own list of tags past support.

## Frequently asked questions

### Why pin the index digest rather than the image digest I see in docker images?

The digest `docker images` shows is for the single-platform manifest your machine pulled. A multi-platform build like the worker's, which the repository's workflow builds for three platforms, needs the digest of the index that lists all of them, so the agent asks the registry with the index media types accepted and pins what it answers.

### Does pinning stop me getting security updates?

Not with the Dependabot entries the agent adds. A base image rebuilt under the same tag arrives as a pull request that moves the digest, so you still get the fix, but you see it in a diff and merge it on purpose rather than picking it up on whatever day you happen to rebuild.

### Will it upgrade my end-of-life images?

No. The run changes no version; it lists in the pull request any tag that is past its support window and the newer tags the registry offers, so the maintainer decides. Mixing a version upgrade into a pinning change would make the review harder and the rollback wider.

### What about the images my Kubernetes manifests reference?

They are pinned too, and the published application images that carry no tag at all get a tag and a digest. The two Dependabot ecosystems the pull request adds cover Dockerfiles and Compose files, so the pull request says that the manifest lines move with the weekly run or a manual bump.

## More Docker jobs

- [Reduce a Docker Image's Size for a Flask App](https://getrush.ai/run/reduce-image-size/docker/)
- [Upgrade the Base Images in Your Dockerfiles Every Week](https://getrush.ai/run/upgrade-base-images/docker/)
- [Write Container Structure Tests for Docker Images](https://getrush.ai/run/write-container-structure-tests/docker/)

## The same job on other stacks

- [Pin and Upgrade Container Images in Docker Compose](https://getrush.ai/run/pin-image-versions/docker-compose/)
- [Pin and Upgrade Container Images in Kustomize Manifests](https://getrush.ai/run/pin-image-versions/kustomize/)

## More jobs like this: Upgrade dependencies weekly

- [Pin the Python Dependencies of a Streamlit App](https://getrush.ai/run/pin-python-dependencies/streamlit/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
