blackoutsecure/github-runner

•Updated 4 months ago

Image

10K+

blackoutsecure/github-runner repository overview

⁠blackoutsecure/github-runner

Unofficial community image for the GitHub Actions Runner⁠, built with LinuxServer.io⁠ style container patterns (s6-overlay supervision, hardened defaults, multi-arch amd64 / arm64 builds) and first-class Balena deployment support. Sponsored and maintained by Blackout Secure⁠.

Important
This repository is not an official LinuxServer.io image release. Want to help make it an officially supported LinuxServer.io Community image? Add your support in [linuxserver/discussions/128](https://github.com/orgs/linuxserver/discussions/128).

Links: Docker Hub⁠ · Balena block⁠ · GitHub⁠ · Upstream Runner⁠

⁠Table of Contents

blackoutsecure/github-runner⁠

⁠Quick Start

docker run -d \
  --name=gh-runner \
  --restart unless-stopped \
  -e TZ=Etc/UTC \
  -e RUNNER_URL=https://github.com/OWNER/REPO \
  -e RUNNER_TOKEN=YOUR_REGISTRATION_TOKEN \
  -v runner-config:/config \
  blackoutsecure/github-runner:latest

Note — --security-opt no-new-privileges:true is intentionally omitted. It is incompatible with the image's default RUNNER_SUDO=true (the kernel PR_SET_NO_NEW_PRIVS bit blocks sudo from elevating regardless of /etc/sudoers.d/), and turning it on without also setting RUNNER_SUDO=false breaks every workflow step that runs sudo apt-get install …. See Privileges required by feature⁠ for the full trade-off.

Then docker logs gh-runner should show a startup banner ending with Listening for Jobs.

For compose, ephemeral, hardened, fixed-pool, and dynamic-scaling configurations, see Usage⁠.

⁠Image Availability

Docker Hub: blackoutsecure/github-runner⁠
Multi-arch manifests (linux/amd64 + linux/arm64) — Docker selects the right architecture automatically.

docker pull blackoutsecure/github-runner:latest        # rolling latest
docker pull blackoutsecure/github-runner:2.333.1       # pinned upstream runner version
docker pull blackoutsecure/github-runner:sha-<commit>  # pinned source revision

One image, two roles. The image ships with both the GitHub Actions runner and the gh-runner-autoscale script baked in. The role is chosen at launch time — pick whichever fits your orchestrator most cleanly; all three forms produce an identical container:

Role	How to launch	Container PID 1
Full self-hosted runner (default)	No env var, no command arg	s6-overlay (`/init`) → `Runner.Listener` (dropped to `abc`/uid 911)
Autoscaler sidecar — env var	`RUNNER_ROLE=autoscaler`	`bash` autoscaler loop (root)
Autoscaler sidecar — CMD arg	`docker run IMAGE autoscaler`	`bash` autoscaler loop (root)
Autoscaler sidecar — explicit (advanced)	`entrypoint: ["/usr/local/bin/gh-runner-autoscale"]`	`bash` autoscaler loop (root)

Prefer RUNNER_ROLE=autoscaler for most deployments — it's a single env var that survives every orchestrator's ergonomics (Balena fleet env vars, Kubernetes Deployment templates, Nomad task env, ECS task definitions). The CMD-arg form is convenient for one-shot docker run invocations. The explicit entrypoint: form remains supported for callers already wired that way; you don't have to migrate.

The baked-in gh-runner-healthcheck⁠ auto-detects sidecar mode by inspecting /proc/1/cmdline, so the same HEALTHCHECK works in every form — no healthcheck: disable: true workaround required.

docker buildx build -t blackoutsecure/github-runner:local .

Tag	Meaning
`latest`	Latest release on top of Ubuntu 24.04 Noble; multi-arch
`<runner-version>` (e.g. `2.333.1`)	Pinned upstream actions/runner release
`sha-<commit>`	Pinned to a specific commit of this repository
`amd64-latest` / `arm64v8-latest`	Architecture-specific aliases for `latest`

For production, pin to a <runner-version> or sha-<commit> tag and update on a schedule.

⁠Supported Architectures

Architecture	Platform	Alias tag
x86-64	`linux/amd64`	`amd64-latest`
ARM 64-bit	`linux/arm64`	`arm64v8-latest`

The description above is a condensed version. View the full README on GitHub: https://github.com/blackoutsecure/docker-github-runner/blob/3f5c4a9de2c42aca6ba4909f41fff6dd098f2ba4/./README.md⁠

Tag summary

Recent tags

Content type

Image

Digest

sha256:a6b68c901…

Size

339.3 MB

Last updated

4 months ago

docker pull blackoutsecure/github-runner