Docker actions: total environment control at the cost of Linux-only and image overhead

Total environment control

When composite and JavaScript actions fall short — because you need cosign, a specific glibc, or a compiled binary with no npm equivalent — the Docker action is not a workaround: it is the only type designed to own its entire environment. The question is not whether Docker is powerful enough; it is whether the cost is worth it for your use case.

A Docker action declares runs.using: "docker" and either image: "Dockerfile" (built on the runner) or image: "docker://ghcr.io/org/img:tag" (pulled pre-built). Inside the container you control everything — base OS, system libraries, any language runtime, exact tool versions — which is the one thing composite and JavaScript actions cannot give you. If your action needs cosign, a specific glibc, a compiled Go or Rust binary, or a tool with no npm equivalent, the container is the only type that packages it reproducibly:

FROM alpine:3.20
RUN apk add --no-cache cosign skopeo
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

# action.yml
runs:
  using: "docker"
  image: "Dockerfile"
  args:
    - ${{ inputs.tag }}
  env:
    REGISTRY_TOKEN: ${{ inputs.token }}

The runtime contract differs from a JavaScript action. Inputs arrive as INPUT_* environment variables in the container (an input tag becomes INPUT_TAG), and you can also pass them positionally via args:. Outputs are written by appending to the file named by $GITHUB_OUTPUT — echo "result=ok" >> "$GITHUB_OUTPUT" from inside the entrypoint — and the workspace is bind-mounted at $GITHUB_WORKSPACE. There is no toolkit; you speak the protocol directly through env vars and these files.

The cost: Linux-only and image overhead

The container’s power has two prices, both paid on every run. First, Docker actions run only on Linux runners — not macOS, not Windows. An action you want usable everywhere cannot be a Docker action; that alone pushes many reusable actions toward JavaScript. Second, the container has to materialize before your code runs. With image: "Dockerfile", the runner builds the image on every invocation unless layers are cached — commonly 40-90 seconds. With image: "docker://...", it pulls a pre-built image — faster, but still tens of seconds for a cold pull of a non-trivial image. Compare that to a composite (milliseconds) or a JavaScript action (sub-second node boot): the Docker action adds a flat, per-run tax that is invisible in a long job and brutal in a fast one triggered hundreds of times a day.

When you add a Docker action to a fast workflow triggered hundreds of times a day, ask yourself: does the logic actually require an arbitrary container environment, or could a JavaScript action handle it? If the answer is yes, it needs Docker — then the next question is how to cut the image startup cost. The mitigation is to publish a pre-built image to a registry (GHCR) and reference it with docker://, turning a per-run build into a per-run pull and letting layer caching help. But that adds a release pipeline for the image itself. Two security notes inherit from the container world and matter more here than for the other types: pin the base image by digest (FROM alpine:3.20@sha256:...) so the build is reproducible and a re-tagged upstream base can’t change your action silently; and pin any actions your workflow uses to invoke this one by commit SHA, the same supply-chain hygiene as the other action types. The decision rule is blunt: choose Docker only when you genuinely need an environment composite and JavaScript cannot provide, and accept Linux-only plus the startup tax as the cost of that control.