# Forgejo Actions Runner Substrate

Last reviewed: 2026-07-03

Status: **in-cluster runner on railiance01** (ADR-004). Supersedes interim coulombcore
host runner.

## Purpose

Forge-owned Actions runner for `https://forgejo.coulomb.social` so `coulomb`
organization repos build and publish without workstation or legacy-host Docker.
Label contract aligns with `docs/gitea-actions-runner-substrate.md` and
`docs/ci-runner-actions-gitops-ownership.md`.

## Production Runner (ADR-004)

| Field | Value |
| --- | --- |
| Runner name | `railiance01-build-01` |
| Scope | `coulomb` organization |
| Placement | `forgejo` namespace, railiance01 k3s |
| Manifest | `railiance-apps/manifests/forgejo-runner.yaml` |
| Images | `code.forgejo.org/forgejo/runner:6.3.1`, `docker:27-dind` |
| Job runtime | DinD sidecar (`DOCKER_HOST=tcp://127.0.0.1:2375`) |
| State PVC | `forgejo-runner-data` |
| Cluster deploy authority | Not included |

### Labels

```text
self-hosted:host,linux:host,linux_amd64:host,container-build:host,registry-publish:host,railiance01:host,ubuntu-latest:docker://node:20-bookworm,docker:docker://node:20-bookworm
```

## Operator Commands

```bash
# S5 deploy (railiance-apps)
cd ~/railiance-apps
make forgejo-runner-registration-deploy   # after SOPS encrypt
make forgejo-runner-deploy
make forgejo-runner-status

# Endpoint smoke
make forgejo-smoke

# Generate registration token (in cluster; do not log token)
KUBECONFIG=~/.kube/config-hosteurope kubectl exec -n forgejo deploy/forgejo-gitea -- \
  forgejo actions generate-runner-token --scope coulomb
```

## Secret Boundaries

- `forgejo-runner-registration` Kubernetes Secret — registration token only.
- Repo/org registry credentials — Forgejo Actions secrets, not in Git.
- No kubeconfig or OpenBao tokens on the runner pod by default.

## Retired: Interim coulombcore Host Runner

`railiance-coulombcore-build-01` on coulombcore was a scheduling proof only.
Disable after in-cluster runner is healthy:

```bash
ssh coulombcore 'sudo systemctl disable --now forgejo-runner'
```

## Evidence

- Host probe (2026-07-03): `coulomb/forgejo-actions-probe` workflow `success`.
- In-cluster (2026-07-03): `railiance01-build-01` 2/2 Ready; `container-probe`
  and `image-build` workflows `success`. Image-build uses static docker-cli on
  the non-root runner host + `DOCKER_HOST=tcp://127.0.0.1:2375` (DinD); org
  secrets `REGISTRY_USER` / `REGISTRY_TOKEN`; pushes to
  `forgejo.coulomb.social/coulomb/forgejo-actions-probe`.
- `actions/checkout@v4` failed on the host runner — use `git clone` in job steps
  until checkout action compatibility is confirmed.

## References

- `railiance-infra/docs/adr/ADR-004-forgejo-in-cluster-actions-runner.md`
- [Forgejo runner installation](https://forgejo.org/docs/v11.0/admin/actions/runner-installation/)