GitHub Actions "Container action is only supported on Linux"

By Daniel Zoghalchali·Latchkey

A Docker container action (runs.using: docker) can only run on Linux runners. Using it on a windows- or macos- runner fails because those runners cannot execute Linux container actions.

What this error means

A step calling a Docker-based action fails immediately on a Windows or macOS runner with "Container action is only supported on Linux", before the action does anything.

Error: Container action is only supported on Linux

Common causes

Docker action on a non-Linux runner

Actions with runs.using: docker (or Dockerfile-based) need a Linux runner. windows-latest and macos-latest cannot run them.

A matrix that includes non-Linux OSes

A cross-OS matrix that uses a Docker action on every leg fails on the Windows/macOS legs even if Linux passes.

How to fix it

Run the Docker action on Linux only

Gate the Docker-action step (or the whole job) to Linux runners.

jobs:
  scan:
    runs-on: ubuntu-latest      # Docker action requires Linux
    steps:
      - uses: some/docker-action@v1

Use a cross-platform alternative

1. Prefer a JavaScript or composite action that runs on all OSes.
2. In a cross-OS matrix, add if: runner.os == 'Linux' to Docker-action steps.
3. Replicate the action logic with run: steps on Windows/macOS where no portable action exists.

How to prevent it

• Use JavaScript/composite actions for cross-OS workflows.
• Pin Docker-based actions to Linux jobs.
• Guard Docker steps with runner.os checks in mixed matrices.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions