The GitHub Actions self-hosted runner reference plugin for SmoothNAS. The plugin runs one controller container that starts disposable one-job runner containers against the configured repo or organisation.
This is the second reference plugin built against the SmoothNAS plugin system. It exercises three things llama.cpp doesn't:
- Ephemeral workers — operators commonly need several runners for queue throughput, but long-lived runner registrations and workspaces get stale. The controller keeps a configured number of one-shot worker containers available and replaces each worker after it handles one job.
- No SmoothNAS UI to embed — GitHub.com is the UI.
ui.embedis omitted entirely. - Outbound-only workload — no inbound
ports, no nginx route. The bridge network's NAT egress is enough.
In the SmoothNAS UI:
- Get a token from GitHub. Either:
- Create a fine-grained PAT with
actions:writescope on the target repo, use a GitHub App installation token, or use an OAuth token fromgh auth tokenwith sufficient access. Paste it asGH_RUNNER_TOKEN. Short-lived registration tokens from the GitHub UI are not supported in controller mode because each worker needs a fresh registration token.
- Create a fine-grained PAT with
- Install → paste this manifest into the wizard, set
GH_REPO_URL(e.g.https://github.com/my-org/my-repo) andGH_RUNNER_TOKEN, pick a tier with SSD slot capacity, and chooseGH_RUNNER_WORKERSfor concurrency. SetGH_RUNNER_CPUSandGH_RUNNER_MEMORYto cap each runner worker, or leave them at0for unrestricted CPU and memory. - Start → click Start on the plugin card; tierd materialises the controller container. The controller uses the SmoothNAS runtime socket to start worker containers. Each worker registers with GitHub as ephemeral, appears in the runner list while idle or running, handles one job, then exits and is removed with its ephemeral workspace.
- Use → target the runners from a workflow:
jobs: build: runs-on: [self-hosted, smoothnas]
- Scale → change
GH_RUNNER_WORKERS,GH_RUNNER_CPUS, orGH_RUNNER_MEMORYand restart the plugin. The controller reconciles the worker pool and applies resource limits to newly created workers.
Uninstall via the UI's Danger Zone stops the controller. The controller stops/removes workers, workers deregister through the SIGTERM path, and SmoothNAS removes the plugin image and workspace volume.
The actions/runner tarball ships with config.sh (registration) and run.sh (the runner loop) but no glue that fits SmoothNAS' lifecycle. The wrapper/ Go binary has two modes:
GH_RUNNER_MODE=controller(default): inspect the controller container and use the SmoothNAS runtime socket to create/remove worker containers.GH_RUNNER_MODE=worker: register one ephemeral GitHub runner, run exactly one job, clean local runner/action/tool state, and exit.
The controller and its spawned workers use the same Debian 13 image. Keep this aligned with the SmoothNAS appliance base so self-hosted CI jobs do not run against a different distro than production.
Controller mode requires SmoothNAS' runtime-control plugin profile. That profile mounts /run/smoothnas-runtime/docker.sock at /var/run/docker.sock and sets DOCKER_HOST=unix:///var/run/docker.sock; it intentionally does not grant Wolf's device or capability set.
The worker path:
- Reads
GH_REPO_URL/GH_RUNNER_TOKEN/GH_RUNNER_LABELS/GH_RUNNER_GROUPfrom env. - Detects whether the supplied token is a GitHub API token (
ghp_,github_pat_,gho_,ghu_, orghs_) or already a registration token. - For API tokens, calls the GitHub API:
- Repo URL →
POST /repos/{owner}/{repo}/actions/runners/registration-token - Org URL →
POST /orgs/{org}/actions/runners/registration-token
- Repo URL →
- Runs
./config.sh --url $GH_REPO_URL --token $REG_TOKEN --labels $GH_RUNNER_LABELS --runnergroup $GH_RUNNER_GROUP --name "smoothnas-${HOSTNAME}-..." --unattended --replace --ephemeral. - Traps
SIGTERM/SIGINT; on receipt, fetches a removal token with the API credential and runs./config.sh remove --token $REM_TOKENbefore exiting. - Runs
./run.sh; when the one job completes, the runner exits and the worker container is removed by the controller.
The wrapper code is Go with unit tests covering the token-type heuristic, repo-vs-org URL parsing, Docker runtime helpers, and the GitHub API call shape against an httptest server.
By default, each worker uses /home/runner/_work inside its own ephemeral container rootfs. The whole worker container is removed after one job, so GitHub checkout state, _actions, _temp, _tool, and any job-created files are removed with it.
Set GH_RUNNER_BIND_WORKSPACE=true to put worker workspace directories under the controller's tier-bound volume instead:
/mnt/<tier>/.plugins/gh-runner/workspace/workers/<worker-name>/ → /home/runner/_work
Bound workspaces are still not shared and are deleted after the worker exits. The default ephemeral-rootfs mode avoids keeping active GitHub checkouts on SmoothFS.
# wrapper smoke build + tests
cd wrapper && go vet ./... && go test -race ./...
# image build
docker buildx build -t smoothnas-plugin-gh-runner:dev .
# run a single registration locally (won't actually register without a real token)
docker run --rm \
-e GH_RUNNER_MODE=worker \
-e GH_REPO_URL=https://github.com/owner/repo \
-e GH_RUNNER_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
smoothnas-plugin-gh-runner:devTo sideload a dev image into a SmoothNAS dev VM, edit smoothnas-plugin.yaml's artifact.image to your local tag and use tierd-cli plugin install.
.github/workflows/release.yml runs on tag push (v*):
- Runs
go vet+go test -raceagainst the wrapper. - Builds and pushes a single image to
ghcr.io/rakuensoftware/smoothnas-plugin-gh-runner:VER. - Resolves the pushed digest and rewrites
artifact.digestin the manifest. - Creates a GitHub release attaching the rewritten manifest.
The smoke test that actually installs the plugin against a SmoothNAS dev VM lives in the SmoothNAS repo's CI, not here. Triggered nightly: spins up SmoothNAS, sideloads the manifest with count: 1, supplies a CI-secret PAT against a private test repo, asserts the runner picks up a one-line workflow within 5 minutes, then uninstalls and verifies the runner deregisters.
The Dockerfile pins RUNNER_VERSION and RUNNER_SHA256 as build-args. To upgrade:
- Find the desired version on actions/runner releases.
curl -fsSLO https://github.com/actions/runner/releases/download/vX.Y.Z/actions-runner-linux-amd64-X.Y.Z.tar.gz && sha256sum *.tar.gz- Bump
RUNNER_VERSIONandRUNNER_SHA256inDockerfile. - Tag a new release; CI rebuilds and republishes.
Add a LICENSE file at publish time. The wrapper code in this repo is original; the actions/runner downloaded into the image carries its own license terms (MIT).
This plugin is licensed under the AGPL-3.0.