TrueNAS SCALE GitHub Build Runner

This setup runs a single GitHub self-hosted runner as a TrueNAS SCALE custom app and routes the Compile StarPilot workflow onto that runner.

The app container:

registers one repository-scoped GitHub Actions runner
stays visible in the TrueNAS Apps UI
mounts the host Docker socket so ./build can launch the existing larch64 build container flow
persists runner state and build caches in one dataset mounted at /runner

What this workflow does

.github/workflows/compile_starpilot.yaml now:

lets an admin choose a target_ref branch from the Actions UI
checks out that branch on the NAS runner
runs ./build
prunes the tree with scripts/ci_package_prebuilt_tree.sh
commits the result as build
pushes that commit back to the selected branch without force-pushing

Use a branch intended for built output. The prune step removes developer-facing files and is not meant for normal day-to-day development branches.

1. Publish the runner image

You need a registry image for TrueNAS to deploy. The repo includes .github/workflows/publish_truenas_runner.yaml for this.

Open Actions on GitHub.
Run Publish TrueNAS Runner Image.
Leave image_tag as latest unless you want a versioned tag.
After it finishes, the image is available at:

ghcr.io/<repo-owner>/starpilot-truenas-runner:latest

If you prefer to build it locally, run:

docker build -f tools/truenas_github_runner/Dockerfile -t ghcr.io/<repo-owner>/starpilot-truenas-runner:latest .
docker push ghcr.io/<repo-owner>/starpilot-truenas-runner:latest

2. Create a runner token

Generate a repository-scoped self-hosted runner token in GitHub:

Open the repository.
Go to Settings > Actions > Runners.
Click New self-hosted runner.
Choose Linux and x64.
Copy the one-time registration token from the generated setup commands.

That token expires quickly. Paste it into TrueNAS during deployment and restart the app if you need to re-register.

3. Deploy on TrueNAS SCALE

TrueNAS custom apps support Docker Compose YAML through Apps > Discover Apps > Custom App > Install via YAML.

Create a dataset for persistent runner state first, for example:

/mnt/<pool>/apps/starpilot-runner

Then paste this compose YAML into TrueNAS after replacing the placeholders:

services:
  starpilot-runner:
    image: ghcr.io/<repo-owner>/starpilot-truenas-runner:latest
    container_name: starpilot-runner
    restart: unless-stopped
    environment:
      GITHUB_REPOSITORY_URL: https://github.com/<repo-owner>/<repo-name>
      RUNNER_NAME: starpilot-truenas-runner
      RUNNER_LABELS: self-hosted,truenas,starpilot-build
      RUNNER_WORKDIR: /runner/_work
      RUNNER_TOKEN: <paste-one-time-runner-token>
      DOCKER_GID: ""
      REMOVE_RUNNER_ON_EXIT: "0"
    volumes:
      - /mnt/<pool>/apps/starpilot-runner:/runner
      - /var/run/docker.sock:/var/run/docker.sock

If the container starts but cannot talk to Docker, inspect the Docker socket group on TrueNAS and set DOCKER_GID to that numeric group id.

4. Verify runner registration

Confirm all of the following:

the app shows as Running in TrueNAS
the container passes its healthcheck
GitHub shows the runner as online with labels self-hosted, truenas, and starpilot-build

5. Run a build

Open Actions > Compile StarPilot.
Click Run workflow.
Enter the branch name in target_ref.
Optionally set jobs to the parallelism you want for ./build.
Start the run.

On success, the workflow pushes a new commit named build back to that branch.

Operational notes

RUNNER_TOKEN is only required on first registration or when you want to replace a stale runner with the same name.
Runner state is persisted in /runner, so normal restarts do not need a new token.
REMOVE_RUNNER_ON_EXIT=1 enables best-effort deregistration on shutdown, but that only works when the provided token is still valid.
The build cache, GitHub workspace, and .comma_sysroot data all persist under the runner dataset as long as the workflow runs in the same mounted work area.

4.1 KiB Raw Permalink Blame History