All jobs

Fix "docker-compose: command not found" in GitHub Actions

Yes. An agent switches each workflow step from docker-compose to docker compose, checks the flags and the Compose file under v2, and updates the docs to match.

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

What the agent does

GitHub's hosted Ubuntu runners used to ship two Compose commands: the standalone docker-compose binary, which is Compose v1, and the docker compose plugin, which is v2. The v1 binary was removed from the runner images in 2024. A workflow that had passed for years then fails on the step that calls it, with docker-compose: command not found and exit code 127, without a single commit to the repository. The fix is a space where the hyphen was. Doing it properly means finding every place the old command is typed and confirming that v2 treats the project's Compose file and flags the same way.

fh1ch/node-bacstack shows the shape. Its .github/workflows/ci.yml has a compliance job on ubuntu-latest with two steps: actions/checkout@v2, then run: docker-compose up --abort-on-container-exit --exit-code-from bacnet-client. The docker-compose.yml beside it defines a bacnet-device service from a published image and a bacnet-client service built from the repository's Dockerfile, joined with links. The same command appears a second time in CONTRIBUTING.md, after docker-compose build, as the way to run the compliance tests locally. The agent changes all three occurrences, because a workflow that says one thing and a contributor guide that says another is how the next person reintroduces the hyphen.

Before trusting the edit it checks what v2 does with this file. It runs docker compose config to see the resolved project and reads the warnings: this file starts with version: '3', a key current Compose releases report as obsolete and ignore. It confirms that the two flags the job depends on exist in v2 with the same meaning, since --exit-code-from bacnet-client is what turns a failing test container into a failing job. It looks for anything that depends on v1's container naming, where names were joined with underscores and v2 uses hyphens; a later step that runs docker logs project_service_1 would break. This workflow has none. The test code addresses the other container as bacnet-device, the service name, which resolves the same under both versions.

The agent's sandbox has no Docker, so it installs it first with sudo apt-get install -y docker.io and starts dockerd. That package does not include the v2 plugin, which is the thing under test, so it also downloads a Compose v2 release binary into ~/.docker/cli-plugins/ before running anything. With both in place it runs the exact command from the workflow. If the published device image can no longer be pulled, or the build fails for a reason unrelated to Compose, such as the node:16-alpine base in the Dockerfile or a lockfile problem, it reports that as a separate finding with the output and still delivers the command fix.

Start it with one API call

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

{
  "agent": "claude",
  "input": "A GitHub Actions job fails with \"docker-compose: command not found\" (exit code 127) because hosted runners no longer include Compose v1. Find every use of the docker-compose command in this repository: workflow files under .github/, composite actions, shell scripts, Makefiles, package.json scripts, and documentation such as README and CONTRIBUTING. Replace each with the v2 form, docker compose, keeping every flag and argument. Do not rename any docker-compose.yml file; only the command changes. Do not add a step that installs Compose v1, and do not add a third-party action to provide it. Then check v2 compatibility: run docker compose config for each Compose file and report its warnings; confirm each flag used in the workflows exists in v2; search for anything that depends on v1 container names with underscores (docker logs, docker exec, docker inspect, wait scripts, hard-coded hostnames) and update those to the v2 hyphenated names or, better, to docker compose logs and docker compose exec with the service name. Install Docker and the Compose v2 plugin in your environment and run the exact commands from the changed workflow steps. Include the commands and their output. If a command fails for a reason that is not the Compose version, such as an image that cannot be pulled or a build error, report it separately with the output and do not attempt a wider fix. List, without changing, any other step in the same workflows that relies on software GitHub has removed or deprecated on hosted runners. Open a pull request.",
  "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 that changes the same token in several files. For a repository like the example it is three lines: one in the workflow and two in the contributor guide. The description lists each file and line, so a reviewer can confirm nothing was missed by searching the branch for the hyphenated command and finding only file names such as docker-compose.yml.

The description also carries what the agent learned by running the job's command under v2: the docker compose config warnings, the result of the command itself, and its exit code. Where the run exposed a second problem, it is in its own section with the failing output, because the workflow may stay red after this merge for that other reason and the reviewer should know before they see it.

The check that settles it is the workflow's own run on the pull request. The step that previously ended at exit code 127 should now get as far as starting containers. The reviewer looks at that step's log, not only at the summary icon, to see that Compose ran and that the job's result now reflects the tests.

Run it on every failed workflow run

Add an automation to the Project with a github trigger on workflow_run.failure and the prompt above. When a workflow in the repository fails, Rush starts a run and places the event after the prompt as text. The prompt already tells the agent what to look for, so on a failure with a different cause it should report that it found no use of the old command and stop.

Set branch_patterns on the trigger to your default branch if you only want failures there, and keep max runs per hour low: a broken workflow fails on every push, and one pull request is enough. Runs from forks never fire the trigger, so a contributor's failing fork build starts nothing.

The use case this job follows, with its automation and trigger: Fix a bug from an alert.

Why run it on Rush?

The change is trivial to type and awkward to test from a developer machine, because most laptops still have a docker-compose shim that makes the old command work. The failure only exists where v1 is truly absent. The agent sets up exactly that environment, Docker with the v2 plugin and no v1 binary, and runs the workflow's command there, so the output in the pull request comes from the same conditions the runner has.

It also finishes the search. The hyphenated command hides in scripts that workflows call, in Makefile targets and in onboarding documents, and a fix that touches only the failing step leaves the rest to fail later or to mislead a new contributor. One run covers the repository and returns a list of every occurrence it changed, with the commands it executed kept in the session record.

Frequently asked questions

Do I need to rename docker-compose.yml?

No. Compose v2 still reads docker-compose.yml and docker-compose.yaml, and also accepts compose.yaml. Only the command changes, from docker-compose to docker compose. The agent leaves file names alone.

Can I install docker-compose v1 on the runner instead?

You can add a step that downloads it, and some workflows do. Compose v1 no longer receives updates, so that keeps the job tied to software that is no longer maintained and adds a download to every run. Switching the command removes the dependency.

Will my flags still work with docker compose?

The common ones do, including up -d, --build, --abort-on-container-exit, --exit-code-from, -f and run --rm. The agent checks each flag your workflows use against v2 and runs the commands, so a difference shows up in its report and not in your next push.

What else changes between v1 and v2?

Container names use hyphens where v1 used underscores, so app_web_1 becomes app-web-1. Scripts that call docker logs or docker exec with a full container name need updating. Using docker compose logs web or docker compose exec web avoids the name entirely, and that is the form the agent writes.

Does this apply to self-hosted runners?

Only if v1 is missing there too. A self-hosted runner has whatever you installed, and the agent cannot see it. The v2 command works on any runner with a current Docker installation, so the change is safe to make either way.

More GitHub Actions jobs

More jobs like this: Fix a bug from an alert

Keep reading