GitHub Actions container action requires uses with a Dockerfile/image

By Kaveh Alemi·Latchkey

A Docker container action (runs.using: docker) must point runs.image at a Dockerfile or a registry image. Omitting it leaves the runtime with nothing to build or pull.

What this error means

The action fails to start, reporting that a Docker action requires an image reference, after an action.yml declares using: docker without image.

Error: Docker container action is missing 'image' (expected a Dockerfile or registry image reference).

Common causes

Missing runs.image

using: docker requires image: pointing at Dockerfile or a registry image.

Wrong relative path to Dockerfile

A Dockerfile path that does not resolve relative to action.yml fails the build.

How to fix it

Declare the Docker image source

1. Set image: Dockerfile to build from the action directory.
2. Or set image: docker://ghcr.io/owner/img:tag for a prebuilt image.
3. Verify the Dockerfile path is relative to action.yml.

# action.yml
runs:
  using: docker
  image: Dockerfile

How to prevent it

• Validate action metadata with actionlint or a schema check.
• Keep the Dockerfile beside action.yml for predictable paths.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions