Ray's Knowledge Base

Test a GitHub Actions job locally with act on an Apple Silicon Mac and keep the container

RecipeVerified 29 Sep 2026Holds anywhere
Recipe. When to use it, the steps, and what showed that they work.

When to use#

A CI step fails and each push-and-wait round is slow; you want to run the job on your Mac and fix the step in place.

Steps#

  1. Run natively on ARM: Docker on Apple Silicon is aarch64, and x86 emulation is too slow for a big build.

  2. Copy the workflow to a scratch file. Drop steps that touch the host (a docker image prune step would prune your own images) and stop after the step under test.

  3. Run it with the log saved, and --reuse so the container stays after a failure:

    act pull_request -W $S/ci.yml -j build-and-test -P ubuntu-22.04=catthehacker/ubuntu:act-22.04 --container-architecture linux/arm64 --pull=true --reuse > $S/act.log 2>&1; echo "exit $?" >> $S/act.log

  4. After a failure, run the corrected step in the kept container, then the later steps, without a full rebuild.

  5. Remove the container when done: docker rm -f <id>.

Evidence#

dftracer PR 388, 2026-09-29: the act run found that libraries were in install/lib, not lib64 as a guess had assumed, and the fixed step then built and linked in the kept container. A container cannot show hardware counters: the PAPI check exited 2 with "PAPI runtime is available but exposes 0 hardware counters on this node".