# act_runner setup (octowow.st)

Stands up a self-hosted Gitea Actions runner as a container. One runner
registered at the **user level** serves all of your repos (`GlueXML`,
`mpq-packager`, …).

## Prerequisites on the runner host

- **Docker** running. On Windows/macOS that means Docker Desktop with the Linux
  engine (WSL2 backend on Windows). Settings → Advanced → keep "Allow the
  default Docker socket to be used" enabled so the socket mount works.

## 1. Get a registration token

In the Gitea web UI, as your user:

> avatar → **Settings** → **Actions** → **Runners** → **Create new Runner**

Copy the **registration token** (a long string). This is user-scoped, so the
runner picks up jobs from any of your repos.

Direct link: <https://octowow.st/git/user/settings/actions/runners>

> A repo-scoped token (repo → Settings → Actions → Runners) also works if you
> only want the runner tied to one repo.

## 2. Configure

```sh
cp .env.example .env
# edit .env: paste RUNNER_TOKEN, set RUNNER_NAME
```

## 3. Start

```sh
docker compose up -d
docker compose logs -f        # watch it register
```

The runner should appear as **Idle / online** in the Runners list within a few
seconds.

## 4. Enable Actions on each repo

Per repo: **Settings → Actions →** enable. New repos have it off by default.

## 5. Verify

Push a tag (or run a workflow) and watch it execute under the **Actions** tab.
For `mpq-packager`'s release flow, a `v*` tag on a consuming repo builds the MPQ
and attaches it to a release.

## Notes

- **First job is slow** — it pulls `catthehacker/ubuntu:act-latest` (~1 GB) the
  first time; cached afterward.
- **`runs-on` labels** must match `GITEA_RUNNER_LABELS`. We map
  `ubuntu-latest` → `catthehacker/ubuntu:act-latest`. Add more pairs
  (comma-separated) to support other labels.
- **Docker actions** (e.g. `uses: paste/mpq-packager@v1`) work out of the box:
  act_runner builds and runs them via the mounted host socket.
- **Workflows that run `docker` CLI in a step** (like this repo's own
  `.gitea/workflows/ci.yml`) need the job container to reach Docker too. The
  release workflow does not — it only *uses* the Docker action — so it's fine.
  Ask if you want the CI's docker-in-job case wired up.
- **Re-registering**: delete `./data` and `docker compose up -d` again with a
  fresh token.