What the agent does
The agent clones the repository into its own cloud sandbox and finds every build context before writing anything. In an app like dockersamples/example-voting-app there are four: vote/Dockerfile on python:3.11-slim with three stages, base, dev and final, where dev adds watchdog and final runs gunicorn on port 80; result/Dockerfile, a single stage on node:18-slim that installs nodemon globally, runs npm ci and moves node_modules up a level before tini starts server.js; worker/Dockerfile, which builds with FROM --platform=${BUILDPLATFORM} mcr.microsoft.com/dotnet/sdk:7.0 and dotnet publish -a $TARGETARCH into a runtime:7.0 image; and seed-data/Dockerfile, a python:3.9-slim image with apache2-utils that only the seed Compose profile uses. It reads docker-compose.yml, where vote builds with target: dev and mounts its source for live reload, docker-compose.images.yml and docker-stack.yml, which pull dockersamples/examplevotingapp_vote, _result and _worker, and the three .github/workflows/call-docker-build-*.yaml files, each calling the reusable dockersamples/.github workflow with two image names, one on Docker Hub and one on ghcr.io, tag rules for latest and a pull request tag, and platforms: linux/amd64,linux/arm64,linux/arm/v7.
It writes docker-bake.hcl at the repository root. Two variables, REGISTRY defaulting to dockersamples and TAG defaulting to latest, feed every tag so one TAG=pr-42 docker buildx bake retags everything. There is a target per image: vote with context = "./vote" and target = "final", result, worker and seed, each with the two tags its workflow publishes and the platforms list copied from that workflow, and a vote-dev target that inherits vote and sets target = "dev" so the development image Compose uses is also buildable from the file. A default group lists vote, result and worker, the three images the stack deploys, and a dev group lists vote-dev and result; seed stays out of both groups, as the seed profile keeps it out of a plain docker compose up. Common labels, org.opencontainers.image.source pointing at the repository and revision from a GIT_SHA variable, go in a shared _common target every image inherits.
The worker is the one place Bake has to say something the Dockerfiles do not. Its FROM --platform=${BUILDPLATFORM} line and the TARGETARCH publish are already cross-compilation aware, and the workflow's comment about arm/v7 failing under QEMU refers to .NET Core 3.1 while Worker.csproj targets net7.0, so the agent keeps all three platforms in the target, flags the stale comment in the pull request, and leaves the decision about dropping linux/arm/v7 to the maintainers rather than making it inside a build-file change. The result context has the repository's only .dockerignore; the agent notes that Bake changes nothing about contexts and that the missing ignore files are a separate job.
To prove the file, the agent installs docker.io, the docker-buildx plugin and docker-compose-v2 in its sandbox, starts dockerd, and runs docker buildx bake --print to show the fully resolved JSON for every target, which catches a wrong context path or a tag typo without building anything. It then builds the default group for the sandbox's own platform with --set '*.platform=linux/amd64' --load, so the three images exist locally, and runs docker compose -f docker-compose.images.yml config to confirm the tags match what the Compose and Swarm files pull. Multi-platform output needs a registry or the containerd image store, so the cross-platform build is left to CI, where the agent adds a bake.yaml workflow that runs docker/bake-action with push: false on pull requests to check every target builds from the one definition, leaving the three publishing workflows as they are.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a Docker Bake file to this repository. Read every Dockerfile, every Compose and Swarm stack file, and every GitHub Actions workflow that builds an image first. Write docker-bake.hcl at the root with a variable for the registry and one for the tag, a target per image with its context, build stage, the tags the workflows publish and the platforms they build for, an inherited common target with OCI source and revision labels, and groups for the images the stack deploys and for the development images Compose uses. Where a Dockerfile or workflow comment contradicts the current code, flag it in the pull request without changing the platforms. Install Docker, the buildx plugin and Compose v2 in your sandbox, start the daemon, run docker buildx bake --print, build the default group for the sandbox's platform with --load, and check the resulting tags against the Compose file that pulls prebuilt images. Add a workflow that runs the bake with push disabled on pull requests. Do not change the existing publishing workflows or Dockerfiles. Open a pull request with the resolved bake output and the build log.",
"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
What comes back is a pull request adding docker-bake.hcl and one workflow file, .github/workflows/bake.yaml, with no change to the four Dockerfiles, the Compose files or the three publishing workflows. The description pastes the docker buildx bake --print output so a reviewer can read every resolved context, stage, tag and platform list in one place, and the build log for the default group.
It names each image with the workflow it was derived from, so the tags and platforms can be checked line by line, and lists what it chose not to decide: the worker's arm/v7 platform under a stale comment, and the contexts without a .dockerignore. The bake.yaml workflow's first run on the pull request itself shows all three images building for every platform from the one file.
Before merging, a reviewer decides whether the publishing workflows should eventually call docker/bake-action instead of the reusable workflow, which is a later change the Bake file makes possible, and whether the seed image should join the default group.
Run it on every new Dockerfile in the repository
In the console, an automation in the Project that has the repository, with a github trigger on pull_request.opened, starts one run per pull request with the event after the prompt. The prompt asks the run to finish at once unless a Dockerfile was added or a Compose build block changed, and otherwise to add or update the matching target in docker-bake.hcl on the pull request's branch, run docker buildx bake --print and leave a review comment with the resolved target, so the Bake file never drifts behind the images it is supposed to describe.
From your own server, send this body as POST /o/{org}/sessions with the repository in resources for each repository that builds more than one image, with a request_id that is a UUID v5 of the repository name so a retried call returns the run it already started. Set a webhook_url on the key to receive run.completed with data.session_url when each pull request is open.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A Bake file is only correct if every context, stage and tag in it matches what the Dockerfiles and workflows already do, and the proof is a resolved print and a real build, not a careful read. The agent's sandbox is a fresh Linux machine where it installs Docker, starts the daemon, resolves the file and builds the images, and every command and its output is in the run's record beside the pull request, so a reviewer reads the resolved JSON instead of reconstructing it from three workflow files.
The same request runs across every repository in an organisation that builds images, each in its own sandbox with its own set of Dockerfiles, which is how a team gets one docker buildx bake entry point everywhere in one review cycle instead of repository by repository.
Frequently asked questions
Does this replace my Compose build or the publishing workflows?
No. Compose keeps its build blocks, the publishing workflows keep calling the reusable workflow, and the Bake file sits beside them as the one place that names every image. The new bake.yaml workflow only checks that every target builds on pull requests, with push off.
Why keep arm/v7 for the worker when the workflow comment says it fails?
The comment refers to .NET Core 3.1 and the project now targets net7.0, with a Dockerfile that already cross-compiles through BUILDPLATFORM and TARGETARCH. Changing the platform list is a release decision, so the agent keeps what the workflow builds today and flags the comment for the maintainers.
Can Bake read my docker-compose.yml directly instead?
It can, and the agent says so, but the Compose file builds vote at the dev stage with a source mount for local work, which is not the image you publish. A separate HCL file lets the production stage, the publish tags and the platforms live in one place without changing how Compose runs locally.
Why build only for one platform in the sandbox?
Loading a multi-platform image into the local Docker image store needs the containerd store or a registry push. The agent builds the default group for the sandbox's own platform to prove the contexts and stages, and leaves the full platform matrix to the pull request workflow, where BuildKit builds all of them.
What does the TAG variable change?
Every tag in every target, since they are all written as ${REGISTRY}/<image>:${TAG}. TAG=pr-42 docker buildx bake or --set '*.tags=...' on the command line retags the whole set, which is what the pull request workflow uses to avoid touching latest.
More Docker jobs
More jobs like this: Hand off a long task
- Move Compose Passwords into Docker Secrets (Docker Compose)
- Add a Dockerfile to an AdonisJS App (AdonisJS)
- Add a Dockerfile to an aiohttp App (aiohttp)