Long-lived GitHub Actions self-hosted runner for Raspberry Pi 5 (ARM64).
One custom-runner-nodejs container per repository registers with GitHub and stays up, taking one job after another.
No runner software is installed on the Pi itself — only Docker is required.
myoung34/github-runner— base runner image with ARM64 support- Node.js 22 — for
npx/ Sentry CLI - Deno for Deno tasks
- Supabase CLI — latest ARM64 binary
postgresql-client—psqlfor Supabase Vault secret upserts in CIshellcheck— shell script linter formake qa(dashboard deploy scripts)
- Raspberry Pi 5 with Docker installed
1. Configure environment
cp .env.example .env
# Edit .env and fill in REPO_URLs and GITHUB_TOKENGenerate a classic PAT for GITHUB_TOKEN (docs):
- Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
- Click Generate new token
- Check
repoandworkflowscopes - Click Generate token and paste it into
.env
The container uses this PAT to call the GitHub API and generate a fresh runner registration token on every restart — so a long-lived PAT is required, not the short-lived token from the Actions runner UI.
2. Build and run
make build
make up
make logsIn any workflow you want to run on this runner, set:
jobs:
deploy:
runs-on: [self-hosted, pi5]Pi (Docker only)
└─ container starts
└─ registers with GitHub, holds a long poll
└─ picks up a job → runs → waits for the next one
└─ Compose restarts the container only if it exits
EPHEMERAL=true makes the runner deregister and exit after every single job, so Compose
recreates the container each time. That is a clean workspace per run, and it was the original
setup — but on rootless Docker every recreate is another chance for the daemon to fail
unmounting the old rootfs. Enough of those and the container is left in Dead state, where
docker compose up refuses to start it (container is marked for removal) and only a
manual docker rm -f recovers it. Two runners reached that state after roughly two months.
Ephemeral runners are also the ones affected by
actions/runner#1887, where the runner stays
Idle but silently stops accepting dispatched jobs.
The cost of dropping it is that _work persists between jobs. actions/checkout cleans the
repository itself, and for build-and-push jobs the leftover Docker layer cache is a speedup,
not a hazard. If a job ever needs a guaranteed-clean tree, give it its own container step
rather than turning ephemeral back on.
Because the runner now lives for weeks rather than minutes, DISABLE_AUTO_UPDATE=true matters
more: the runner version is pinned in the Dockerfile's FROM, so updating it means
bumping that pin and running make restart. GitHub eventually refuses connections from runners
that are too far behind, so do not let the pin drift.
RUN_AS_ROOT=false in compose.yml means jobs run as the runner user. The container still
starts as root, because the entrypoint has to: it reads the GID of the mounted docker socket,
groupmods the docker group onto it, then drops privileges. A USER line in the Dockerfile
skips that and the runner loses the docker socket.
Trivy flags the missing USER as DS-0002 and cannot see any of the above, so the check is
excepted in .trivyignore — scoped to this Dockerfile, with the reasoning in the
file. Note also that the daemon is rootless, so uid 0 inside the container is host uid 1001, not
root; see ../docker/README.md.
A runner is briefly stopped whenever it is restarted or its image is rebuilt, so a raw docker system prune can sweep it mid-cycle. Both runner services carry the preserve=true label in compose.yml, which is honored by:
- The scheduled cleanup —
../docker/Makefileprunetarget passes--filter "label!=preserve=true" - Interactive shells — install
../docker/docker-prune-guard.shviamake -C ../docker guard-installto wrapdocker system prune/docker container prunewith the same filter
Without one of these in place, ad-hoc prune commands will delete the runner containers.
By default the runner is scoped to a single repository (RUNNER_SCOPE=repo). To cover additional repos you would need one Compose service per repository, each with its own REPO_URL.
The cleaner alternative is to create a free GitHub Organization, register the runner at org scope (RUNNER_SCOPE=org), and point all your repos there. A single service then handles jobs from every repo in the org — no duplication needed.
# org-level example
environment:
RUNNER_SCOPE: org
ORG_NAME: your-github-org # instead of REPO_URL
GITHUB_TOKEN: ${GITHUB_TOKEN} # needs org admin scope
LABELS: self-hosted,pi5