Docker Github Actions Runner

This will run the new self-hosted github actions runners.

Komodo / local quick-start

This fork includes a self-contained local path for Komodo proof runs:

1. Copy .env.example to .env and fill in the repo-scoped values. If you use GitHub App auth, set APP_PRIVATE_KEY as a single .env line with literal \n escapes for newlines; do not paste a raw multiline PEM.
2. Build the single image that compose uses by default:

   docker build -t komodo-github-actions-runner:local -f Dockerfile .

3. Start the runner:

   docker compose up -d --build

4. Stop it when finished:

   docker compose down

To run more than one runner, set RUNNER_REPLICAS in .env (e.g. RUNNER_REPLICAS=3) before starting — Compose scales the single runner service to that many containers automatically. See "Scaling the fleet" below for details. Because replicas can't share a fixed container name, containers are now named automatically by Compose (e.g. docker-github-actions-runner-runner-1) instead of a fixed COMPOSE_CONTAINER_NAME.

Please see the wiki Please read the contributing guidelines

Included software and configuration

While this project is not perfectly 1:1 with the software upstream, the included packages etc are available here. Documentation can be found in the wiki

Notes

Security

It is known that environment variables are not safe from exfiltration. If you are using this runner make sure that any workflow changes are gated by a verification process (in the actions settings) so that malicious PR's cannot exfiltrate these.

Docker Support

Please note that while this runner installs and allows docker, github actions itself does not support using docker from a self hosted runner yet. For more information:

• actions/runner#406
• actions/runner#367

Also, some GitHub Actions Workflow features, like Job Services, won't be usable and will result in an error.

Containerd Support

Currently runners do not support containerd

Komodo proof isolation

For a repo-scoped proof, use a unique label such as mri2ct-test-repo-komodo-proof in RUNNER_LABELS. LABELS is still read as a fallback, but RUNNER_LABELS is the preferred setting in this fork.

Proof-safe flow:

1. Push the workflow first.
2. Confirm the job is queued for the unique label.
3. Only then start the matching runner.

This keeps the job targeted to the new Komodo/local runner instead of letting the other MRI2CT self-hosted runner pick it up first. The unique proof label only isolates runner selection; because this compose setup still bind-mounts /var/run/docker.sock and runs with RUN_AS_ROOT=true by default, only trusted workflows should be allowed to reach it. This applies equally to every replica when running more than one (see "Scaling the fleet" below) — they all share the same label and the same safety caveat.

Scaling the fleet

Scale within a host with one variable: set RUNNER_REPLICAS in .env to the desired count, then docker compose up -d (or --build the first time). Compose's deploy.replicas spins up that many containers from the single runner service — no per-replica service blocks to write or maintain.

Two things make this safe without any per-replica configuration:

• Runner names: leave RUNNER_NAME blank (the default in .env.example). With RANDOM_RUNNER_SUFFIX=true, each replica generates its own random suffix at boot, so names never collide. Only set a fixed RUNNER_NAME when RUNNER_REPLICAS=1.
• Work directories: RUNNER_WORKDIR now names a shared parent directory for the whole fleet, bind-mounted identically into every replica. fleet-entrypoint.sh (the container's entrypoint in this compose setup) carves out a uniquely-named subdirectory per replica — named after that container's own hostname, which Docker assigns uniquely per replica — before the runner configures or starts. Each replica's actual workdir is still a real, identical host==container path (it's nested inside the shared mount), so container-action jobs that mount $PWD keep working exactly as documented below, and concurrent jobs on different replicas never collide.

Once one host's CPU/IO is saturated, prefer adding another Komodo-managed host over stacking many replicas on a single one — each additional runner replica still contends for the same host's Docker daemon, disk, and network. (A larger, org-scoped, multi-server version of this is sketched in INTEGRATION.md, not yet executed.)

uv package-manager caching

The image ships with uv preinstalled, and this compose setup mounts a persistent host directory for its cache, shared by every replica in the fleet:

• UV_CACHE_DIR_HOST — the host path for the cache (.env), must already exist. Unlike RUNNER_WORKDIR, this should be the same single directory shared by every replica — uv's cache is designed for safe concurrent access, and sharing it is what makes repeat installs fast across the whole fleet.
• UV_CACHE_DIR — set automatically to the same path, because the cache is bind-mounted at an identical host==container path. Not something you configure.
• UV_LINK_MODE — set to symlink, so environments built from the cache point into it instead of copying it.

That last one is not cosmetic. uv normally hardlinks from the cache and falls back to copying, but the fallback fires unconditionally here: the cache and any environment built from it are separate bind mounts, and the kernel refuses hardlinks across mount points even on one filesystem (same st_dev, ln still returns EXDEV). The fallback is silent, so environments were being materialised in full — a 15 GB env duplicating a 15 GB cache per host, re-copying a ~1 GB libtorch every time one was built. Symlinks cross mount points, which fixes it.

The cost of symlink mode is that the cache's absolute path is written into every environment, so it must mean the same thing inside and outside the container — hence the identical host==container mount — and uv cache prune will break environments that point into what it removes.

Any workflow step that runs uv sync, uv pip install, etc. benefits automatically — no workflow changes required. (These variables aren't in the "Environment Variables" table below since they're consumed by uv inside job steps, not by entrypoint.sh.)

Docker Artifacts

Container Base	Supported Architectures	Tag Regex	Docker Tags	Description	Notes
ubuntu focal	x86_64,arm64	/\d\.\d{3}\.\d+/ /\d\.\d{3}\.\d+-ubuntu-focal/	latest ubuntu-focal	This is the latest build (Rebuilt nightly and on master merges). Tags without an OS name are included. Tags with -ubuntu-focal are included and created on upstream tags.
ubuntu noble	x86_64,arm64	/\d\.\d{3}\.\d+-ubuntu-noble/	ubuntu-noble	This is the latest build from noble (Rebuilt nightly and on master merges). Tags with -ubuntu-noble are included and created on upstream tags.
ubuntu jammy	x86_64,arm64	/\d\.\d{3}\.\d+-ubuntu-jammy/	ubuntu-jammy	This is the latest build from jammy (Rebuilt nightly and on master merges). Tags with -ubuntu-jammy are included and created on upstream tags.	There is currently an issue with jammy from inside a 20.04LTS host which is why this is not latest
debian buster (now deprecated)	x86_64,arm64	/\d\.\d{3}\.\d+-debian-buster/	debian-buster	Debian buster is now deprecated. The packages for arm v7 are in flux and are wildly causing build failures (git as well as liblttng-ust#. Tags with -debian-buster are included and created on upstream tags.
debian bookworm	x86_64,arm64	/\d\.\d{3}\.\d+-debian-bookworm/	debian-bookworm	This is the latest build from bookworm (Rebuilt nightly and on master merges). Tags with -debian-bookworm are included and created on upstream tags.
debian trixie	x86_64,arm64	/\d\.\d{3}\.\d+-debian-trixie/	debian-trixie	This is the latest build from trixie (Rebuilt nightly and on master merges). Tags with -debian-trixie are included and created on upstream tags.
debian sid	x86_64,arm64	/\d\.\d{3}\.\d+-debian-sid/	debian-sid	This is currently disabled as it is failing until forky is included in https://download.docker.com/linux/debian/dists/ This is the latest build from sid (Rebuilt nightly and on master merges). Tags with -debian-sid are included and created on upstream tags.

These containers are built via Github actions that copy the dockerfile, changing the FROM and building to provide simplicity.

Environment Variables

Environment Variable	Description
RUN_AS_ROOT	Boolean to run as root. If true: will run as root. If True and the user is overridden it will error. If any other value it will run as the runner user and allow an optional override. Default is true
RUNNER_NAME	The name of the runner to use. Supersedes (overrides) RUNNER_NAME_PREFIX
RUNNER_NAME_PREFIX	A prefix for runner name (See RANDOM_RUNNER_SUFFIX for how the full name is generated). Note: will be overridden by RUNNER_NAME if provided. Defaults to github-runner
RANDOM_RUNNER_SUFFIX	Boolean to use a randomized runner name suffix (preceded by RUNNER_NAME_PREFIX). Will use a 13 character random string by default. If set to a value other than true and RUNNER_NAME_PREFIX is set to an empty string, it will attempt to use the contents of /etc/hostname or fall back to a random string if the file does not exist or is empty. Note: will be overridden by RUNNER_NAME if provided. Defaults to true.
ACCESS_TOKEN	A github PAT to use to generate RUNNER_TOKEN dynamically at container start. Not using this requires a valid RUNNER_TOKEN
APP_ID	The github application ID. Must be paired with APP_PRIVATE_KEY and should not be used with ACCESS_TOKEN or RUNNER_TOKEN
APP_PRIVATE_KEY	The github application private key. Must be paired with APP_ID and should not be used with ACCESS_TOKEN or RUNNER_TOKEN. In .env, keep it on one line and use literal \n escapes for line breaks.
APP_LOGIN	The github application login id. Can be paired with APP_ID and APP_PRIVATE_KEY if default value extracted from REPO_URL or ORG_NAME is not correct. Note that no default is present when RUNNER_SCOPE is 'enterprise'.
RUNNER_SCOPE	The scope the runner will be registered on. Valid values are repo, org and ent. For 'org' and 'enterprise', ACCESS_TOKEN is required and REPO_URL is unnecessary. If 'org', requires ORG_NAME; if 'ent', requires ENTERPRISE_NAME. Default is 'repo'.
ORG_NAME	The organization name for the runner to register under. Requires RUNNER_SCOPE to be 'org'. No default value.
ENTERPRISE_NAME	The enterprise name for the runner to register under. Requires RUNNER_SCOPE to be 'enterprise'. No default value.
RUNNER_LABELS	A comma separated string to indicate the labels. Preferred over LABELS in this fork. Default is 'default'
LABELS	Legacy label setting; read as a fallback when RUNNER_LABELS is not set.
REPO_URL	If using a non-organization runner this is the full repository url to register under such as 'https://github.com/myoung34/repo'
RUNNER_TOKEN	If not using a PAT for ACCESS_TOKEN this will be the runner token provided by the Add Runner UI (a manual process). Note: This token is short lived and will change frequently. ACCESS_TOKEN is likely preferred.
RUNNER_WORKDIR	The working directory for the runner. Runners on the same host should not share this directory. Default is '/_work'. This must match the source path for the bind-mounted volume at RUNNER_WORKDIR, in order for container actions to access files.
RUNNER_GROUP	Name of the runner group to add this runner to (defaults to the default runner group)
GITHUB_HOST	Optional URL of the Github Enterprise server e.g github.mycompany.com. Defaults to github.com.
DISABLE_AUTOMATIC_DEREGISTRATION	Optional flag to disable signal catching for deregistration. Default is false. Any value other than exactly false is considered true. See here
CONFIGURED_ACTIONS_RUNNER_FILES_DIR	Path to use for runner data. It allows avoiding reregistration each the start of the runner. No default value.
EPHEMERAL	Optional flag to configure runner with --ephemeral option. Ephemeral runners are suitable for autoscaling.
DISABLE_AUTO_UPDATE	Optional environment variable to disable auto updates. Auto updates are enabled by default to preserve past behavior. Any value is considered truthy and will disable them.
START_DOCKER_SERVICE	Optional flag which automatically starts the docker service if set to true. Useful when using sysbox. Defaults to false.
NO_DEFAULT_LABELS	Optional environment variable to disable adding the default self-hosted, platform, and architecture labels to the runner. Any value is considered truthy and will disable them.
DEBUG_ONLY	Optional boolean to print debug output but not run any actual registration or runner commands. Used in CI and testing. Default: false
DEBUG_OUTPUT	Optional boolean to print additional debug output. Default: false
UNSET_CONFIG_VARS	Optional flag to unset all configuration environment variables after runner setup but before starting the runner. This prevents these variables from leaking into the workflow environment. Set to true to enable. Defaults to false in the compose/local path so shutdown can still deregister the runner cleanly; enabling it reduces env leakage, but also removes those values from the workflow environment.

Repo-scoped proof requirements

For the Komodo/local path in this fork, the minimum repo-scoped settings are:

• RUNNER_SCOPE=repo
• REPO_URL=https://github.com/MRI2CT/<repo>
• ACCESS_TOKEN or RUNNER_TOKEN
• RUNNER_WORKDIR set to a host path that exists on the machine (this is a shared parent directory for the whole fleet — see "Scaling the fleet" above)
• UV_CACHE_DIR_HOST set to a host path that exists on the machine (also shared by the whole fleet)
• RUNNER_LABELS set to the unique proof label, for example mri2ct-test-repo-komodo-proof

Host mount requirements for Docker jobs

The compose file mounts /var/run/docker.sock and binds RUNNER_WORKDIR to the same absolute path inside the container. Keep both in place if the workflow needs Docker jobs, Docker builds, or writable runner workspaces.

The host path used for RUNNER_WORKDIR must already exist. Unlike a typical single-runner setup, it is deliberately shared across every replica in the fleet — fleet-entrypoint.sh gives each replica its own subdirectory underneath it at startup (see "Scaling the fleet" above), so replicas never write into the same subdirectory even though the top-level mount is shared. UV_CACHE_DIR_HOST is also shared across every replica, by design.

Tests

Tests are written in goss for general assertions. It's expected that all pull-requests have relevant assertions in order to be merged.

Prereqs: Ensure that docker, goss and dgoss are set up Note: while testing locally works, github actions will test all variations of operating systems and supported architectures.

The test file expects the image to test as an environment variable GH_RUNNER_IMAGE to assist in CI

To test:

$ # need to set minimum vars for the goss test interpolation
$ echo "os: ubuntu" >goss_vars.yaml
$ echo "oscodename: focal" >>goss_vars.yaml
$ echo "arch: x86_64" >>goss_vars.yaml
$ docker build -t my-base-test -f Dockerfile.base .
$ # Use the base image in your final
$ sed -i.bak 's/^FROM.*/FROM my-base-test/g' Dockerfile
$ docker build -t my-full-test -f Dockerfile .
$ # Run the full test from Dockerfile.base on the current git HEAD
$ GOSS_VARS=goss_vars.yaml GOSS_FILE=goss_full.yaml GOSS_SLEEP=1 dgoss run --entrypoint /usr/bin/sleep \
  -e DEBUG_ONLY=true \
  -e RUNNER_NAME=huzzah \
  -e REPO_URL=https://github.com/myoung34/docker-github-actions-runner \
  -e RUN_AS_ROOT=true \
  -e RUNNER_NAME_PREFIX=asdf \
  -e ACCESS_TOKEN=1234 \
  -e APP_ID=5678 \
  -e APP_PRIVATE_KEY=2345 \
  -e APP_LOGIN=SOMETHING \
  -e RUNNER_SCOPE=org \
  -e ORG_NAME=myoung34 \
  -e ENTERPRISE_NAME=emyoung34 \
  -e LABELS=blue,green \
  -e RUNNER_TOKEN=3456 \
  -e RUNNER_WORKDIR=/tmp/a \
  -e RUNNER_GROUP=wat \
  -e GITHUB_HOST=github.example.com \
  -e DISABLE_AUTOMATIC_DEREGISTRATION=true \
  -e EPHEMERAL=true \
  -e DISABLE_AUTO_UPDATE=true \
  my-full-test 10