All jobs

Add Hadolint to CI for a Docker Compose Repository

Yes. An agent runs hadolint over every Dockerfile in a Compose repository, fixes what blocks the linter, adds a workflow for pull requests and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads what the repository builds before it lints anything. In a Compose sample collection like docker/awesome-compose there are 37 compose.yaml files, two older compose.yml under the WasmEdge samples, and 35 Dockerfiles, most of them with the # syntax=docker/dockerfile:1.4 header, multi-stage builds with a builder stage, a dev-envs stage that installs git and a vscode user through a RUN <<EOF heredoc, and a final stage that copies the built artifact. .github/workflows/codeql-analysis.yml is the only workflow, a CodeQL scan of Go, TypeScript and Python on pushes to master, with its actions pinned to commit SHAs; .github/CODEOWNERS names two maintainers; .npmrc sets ignore-scripts=true and .yarnrc.yml sets enableScripts: false; CONTRIBUTING.md asks each sample for its own README and a line in the root README.

Then it downloads the hadolint binary, 2.15.1 at the time of writing, and runs it over all 35 files with --no-fail -f json to see the baseline before any change. The counts drive the plan. 23 of the files do not parse at all: hadolint's parser needs a blank line after a heredoc terminator, and these files follow EOF directly with a comment or the next instruction, such as # install Docker tools (cli, buildx, compose) before COPY --from=gloursdocker/docker / / in flask/app/Dockerfile. The other findings are DL3018 and DL3019, apk add without a pinned version and without --no-cache, in the Alpine-based Go and Flask backends; DL3067 and DL3022 on the COPY --from=gloursdocker/docker / / line, which copies a whole filesystem from an image that is not a stage of the build; DL3059 for consecutive RUN lines; and DL3042 and DL3013 for pip install without --no-cache-dir or a version.

The agent makes the smallest change that gets every file through the parser, one blank line after each heredoc EOF, and rebuilds a sample from each language family with docker build to confirm the image is unchanged; the sandbox has no Docker, so it installs docker.io with apt, starts dockerd, and uses docker-compose v1 where a sample needs Compose. It then writes .hadolint.yaml at the root. The COPY --from=gloursdocker/docker / / pattern is the repository's own convention for its dev-envs stages, so DL3067 and DL3022 go under ignored with a comment saying why; listing gloursdocker under trustedRegistries would not be enough on its own, because the rule is about copying a filesystem, not about where the image comes from. DL3018, DL3019, DL3042 and DL3013 stay on: pinning apk and pip versions in 35 sample Dockerfiles is a change for the maintainers to make sample by sample, so failure-threshold: warning would block the workflow on day one, and the agent sets failure-threshold: error, so those warnings show in the log and the annotations without failing the check until the samples are pinned.

The workflow goes in .github/workflows/hadolint.yml: one job on pull_request and on pushes to master, with actions/checkout and hadolint/hadolint-action@v3.1.0, dockerfile: Dockerfile, recursive: true so every sample is covered, format: sarif and output-file: hadolint.sarif, followed by github/codeql-action/upload-sarif so findings appear as annotations on the pull request's files tab next to the CodeQL results the repository already uploads. It pins both actions to commit SHAs with a version comment, the way the existing workflow does. Last it adds a Hadolint line to CONTRIBUTING.md under the list of what a new sample needs, and runs the binary once more with the new config to confirm the result is zero errors and the expected warnings.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add Hadolint to CI for this Docker Compose repository. Read every compose.yaml and Dockerfile, .github/workflows, CODEOWNERS and CONTRIBUTING.md first. Download the current hadolint binary and run it over every Dockerfile with --no-fail -f json; record the counts per rule and per file before changing anything. Fix whatever stops a file from parsing with the smallest edit, such as a blank line after a heredoc terminator, and rebuild one sample per language with docker build to confirm nothing else changed; the sandbox has no Docker, so install docker.io, start dockerd and use docker-compose v1. Write .hadolint.yaml at the root: ignore only rules that conflict with a convention the repository uses on purpose, with a comment saying which, and keep version-pinning rules on as warnings rather than failures. Add .github/workflows/hadolint.yml on pull_request and push with hadolint/hadolint-action in recursive mode, SARIF output uploaded with github/codeql-action/upload-sarif, both pinned to commit SHAs like the existing workflow. Add a Hadolint line to CONTRIBUTING.md. Run hadolint again with the final config and open a pull request that lists the before and after counts per rule.",
  "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

A pull request with four kinds of change: the blank lines that make the heredoc Dockerfiles parse, .hadolint.yaml with each ignored rule explained in a comment, .github/workflows/hadolint.yml, and the CONTRIBUTING.md line. Its description has a table of findings per rule before and after, the list of files that did not parse, and the docker build output for the samples it rebuilt; the full hadolint JSON for every file is in the run's record.

A reviewer checks three things: that no edit to a Dockerfile changes what it builds, which the rebuild output answers; that each rule in ignored is a deliberate convention and not a shortcut, which the comments beside them answer; and that the workflow's threshold matches what the maintainers want to enforce now, since lowering it later to warning is a one-line change once the apk add and pip install lines are pinned.

Run it on every terminal hand-off

A maintainer who wants the linter in place before the next batch of sample pull requests starts this from the terminal with this body and the repository in resources, and goes back to reviewing. The run reads the real workflows and the real Dockerfiles, so the config it writes reflects the conventions the samples already follow rather than a generic ruleset.

Send a request_id, a UUID, with the body so a retried start returns the run it already began. When the turn ends, GET /o/{org}/sessions/{id} names the pull request, and a follow-up to the same session can ask it to pin the apk add lines in one sample as a model for the rest, or to raise the threshold to warning once that is done.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Adding a linter to a repository with 35 Dockerfiles is a question of what it finds, not whether it runs, and the only way to answer is to run it over all of them and read the output. The agent does that in its own sandbox, with the binary, Docker and the rebuilds all inside it, and the pull request carries the before and after counts so the maintainers can see what the check will enforce and what it will only report.

The same run fits any repository that keeps several Dockerfiles: a monorepo of services, a collection of base images, a course with one Dockerfile per lesson. Each gets a config derived from its own files and a workflow pinned the way its other workflows are, and every run keeps the full record of what it found and changed.

Frequently asked questions

Why does hadolint fail to parse so many of these Dockerfiles?

They use RUN <<EOF heredocs, and hadolint's parser expects a blank line after the terminator before the next comment or instruction. Docker builds them fine. A blank line after each EOF is the whole fix, and the rebuilds in the pull request show the images are unchanged.

Will the workflow fail every pull request on day one?

No. The threshold is set to error, with the version-pinning rules downgraded to warnings in the config, so they show in the SARIF annotations without blocking. Once the samples pin their apk and pip packages, raising the threshold is a one-line edit to the config.

Does it edit the sample Dockerfiles beyond the parse fix?

No. Pinning packages, adding --no-cache and merging RUN lines are changes the maintainers should make sample by sample, and the pull request lists where each applies. The run changes only what the linter cannot read.

Can I use a different output than SARIF?

Yes. The action supports tty, json, checkstyle, codeclimate and sarif. SARIF with upload-sarif puts findings on the pull request's files tab and in the Security tab beside the CodeQL results the repository already has, which is why the agent picks it; a follow-up can switch it.

More Docker Compose jobs

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading