static-musl-builds/docs/runner-setup.md

Gitea Actions runner setup for this repo

This repository expects a Gitea Actions runner with the label:

• alpine-latest:docker://node:20-alpine

That label is intentional:

• actions/checkout@v4 needs a Node-capable job image
• the build itself wants apk, which is easiest on Alpine
• the workflow then compiles a static musl binary directly inside the job container

Recommended placement in your infra

Best fit: your NL dedicated Debian 12 server.

Why:

• separate from the Gitea host, which is the recommended topology
• always-on box
• Docker is straightforward there
• enough resources for lightweight source builds

Home server also works, but the NL dedicated host is the cleaner default.

1. Confirm Actions are enabled in Gitea

Your Gitea is 1.26.1, so instance-level Actions support is already built in by default.

Still verify:

• repo: xnullzz/static-musl-builds
• open Settings -> Actions
• ensure Enable Repository Actions is on

The workflow is already detected by Gitea, so the remaining missing piece is the runner.

2. Get a registration token

You can create either:

• an instance runner token in Site Administration -> Actions -> Runners, or
• a repository runner token in xnullzz/static-musl-builds -> Settings -> Actions -> Runners

For this project, a repository runner is enough.

3. Install Docker on the runner host

On Debian 12:

sudo apt-get update
sudo apt-get install -y ca-certificates curl docker.io
sudo systemctl enable --now docker

4. Run act_runner in Docker

Create a directory:

sudo mkdir -p /opt/gitea-runner
sudo chown "$USER":"$USER" /opt/gitea-runner
cd /opt/gitea-runner

Create docker-compose.yml:

services:
  runner:
    image: docker.io/gitea/act_runner:0.2.11
    restart: always
    environment:
      CONFIG_FILE: /config.yaml
      GITEA_INSTANCE_URL: "https://g.o4kosebezablokiruyte.ru"
      GITEA_RUNNER_REGISTRATION_TOKEN: "PUT_TOKEN_HERE"
      GITEA_RUNNER_NAME: "nl-dedicated-static-builder"
    volumes:
      - ./config.yaml:/config.yaml
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock

Generate a starter config:

docker run --rm --entrypoint="" docker.io/gitea/act_runner:0.2.11 \
  act_runner generate-config > config.yaml
mkdir -p data

Then edit config.yaml and replace the default runner.labels block with:

runner:
  labels:
    - "alpine-latest:docker://node:20-alpine"
    - "ubuntu-latest:docker://node:20-bookworm"

This matters because when config.yaml already contains runner.labels, the container startup env GITEA_RUNNER_LABELS is ignored.

Then start it:

docker compose up -d

5. Verify the runner

In Gitea, confirm the runner appears as online.

You should see labels including:

• alpine-latest
• ubuntu-latest

6. Trigger a test build

After the runner is online, either:

• re-run the queued workflow from the Actions UI, or
• push any small commit to main

Expected result:

• workflow builds iperf3
• a release tagged like iperf3-v3.21 appears
• release assets include the static binary, tarball, and sha256 file

Notes

• The queued run already visible in Gitea means repo Actions are working; only execution capacity is missing.
• If you later add more binaries, the same runner can be reused.
• If you want stricter isolation later, you can move to ephemeral runners, but for a personal infra repo this persistent Docker runner is a good starting point.