How to make act use a specific Docker image instead of the default one?

[centranoisacs]

My workflow uses runs-on: ubuntu-22.04 and on GitHub Actions it gets the full runner image with pre-installed tools. When I run it with act, it uses a stripped-down image that's missing things like jq, aws-cli, etc.

I know about -P ubuntu-22.04=catthehacker/ubuntu:full-22.04 but that image is 12GB+ and takes forever to pull.

Is there a middle ground? Like a medium-sized image that has the common tools but isn't 12GB? Or can I build my own image that just adds what I need on top of the default?

What do people actually use in practice? The act README lists the image options but doesn't recommend which one to pick for a workflow that needs standard CLI tools.

[yudin-s]

Yes. You have three practical options, and I would not jump straight to the full-* image unless you really need parity with the hosted runner.

For the middle ground, use the act-* image:

act -P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:act-22.04

That image is documented by catthehacker/docker_images as the medium-size image used by nektos/act, intended to keep compatibility with most actions while staying much smaller than the hosted-runner copy. The full-22.04 image is the near-hosted-runner copy and is expected to be huge.

If your workflow mostly needs a few missing CLI tools, I would usually build a small project image on top of the act image instead of pulling full:

FROM ghcr.io/catthehacker/ubuntu:act-22.04

RUN apt-get update \
  && apt-get install -y --no-install-recommends jq awscli \
  && rm -rf /var/lib/apt/lists/*

Build and map it:

docker build -t local/act-ubuntu-22.04-tools .
act -P ubuntu-22.04=local/act-ubuntu-22.04-tools

If you use this regularly, put the platform mapping in .actrc so every run uses the same image:

-P ubuntu-22.04=local/act-ubuntu-22.04-tools

One caveat: if a job depends on exact GitHub-hosted runner paths, preinstalled SDK versions, browser stacks, Android tooling, etc., the full-* image or a very explicit custom image is safer. For common shell tools like jq, awscli, gh, yq, Node, Go, Java, Rust, and similar, the medium/specialized catthehacker tags are usually the better tradeoff.

If this resolves your setup, please mark it as the answer so other act users can find the image mapping quickly.

[centranoisacs]

building a custom image on top of the slim one is the way to go then. thanks for the Dockerfile example