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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
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
The same job on other stacks
- Pin and Upgrade Container Images in Docker Compose (Docker Compose)
- Pin and Upgrade Container Images in Kustomize Manifests (Kustomize)
More jobs like this: Upgrade dependencies weekly
- Pin the Python Dependencies of a Streamlit App (Streamlit)