# hive-ci — Forgejo Actions runner

The `hive-ci` module adds a Forgejo Actions runner to the hive so
workflows in the hyperhive repo (and any operator-managed repos on
the hive forge) can run on the same host. Disabled by default.

## Enabling

```nix
services.hyperhive.forge.ci = {
  enable = true;
  name   = "prod-hive";    # shows in Forgejo admin panel; default = hostname
};
```

Requires `services.hyperhive.forge.enable = true` (the runner
registers against the hive-forge Forgejo instance). The module
asserts this at eval time.

## Options

| option | default | description |
|---|---|---|
| `forge.ci.enable` | `false` | opt-in; off by default |
| `forge.ci.name` | hostname | runner name in Forgejo admin panel |
| `forge.ci.concurrency` | `2` | maximum parallel jobs |
| `forge.ci.labels` | `["hive-ci:host"]` | runner labels (`<name>:<scheme>`) |
| `forge.ci.package` | `pkgs.gitea-actions-runner` | override the runner binary |

The `host` scheme in labels means jobs run directly inside the
`hive-ci` container (no docker/podman). Workflow files target this
runner with:

```yaml
runs-on: [hive-ci]
```

## Container shape

`hive-ci` is an ephemeral-false nixos-container sharing the host
network namespace (`privateNetwork = false`) so it reaches the
hive-forge Forgejo instance at `localhost:<forge-http-port>` without
needing a routed address.

Bind mounts:
- `/run/hive-ci/core-token` ← `coreTokenPath` (host's forge
  admin token, read-only). Used only on first boot for registration.

The container has `git` in `systemPackages`; everything else a
workflow needs (rust tools, nix, etc.) is either pulled in by the
workflow itself via `nix flake check` or is part of the base NixOS
closure.

Nix sandboxing is disabled in the container (`sandbox-fallback =
true`) because nspawn containers can't create the user namespaces
that the Nix sandbox requires. See `docs/gotchas.md` for the
general nspawn sandbox note.

## Auto-registration

On first boot an `ExecStartPre` script (`hive-ci-autoregister`) runs
before the runner service:

1. Reads the hive-c0re admin token from `/run/hive-ci/core-token`.
2. Calls `GET /api/v1/admin/runners/registration-token` on the forge
   (retrying for up to 30 s while forge starts).
3. Writes the registration token to `/run/hive-ci/runner-token`.
4. The runner service picks it up and registers, writing credentials
   to `/var/lib/gitea-runner/hive/.runner`.

On subsequent boots the `.runner` credentials file already exists;
the script writes a dummy token and exits — the runner ignores it
and reuses its stored credentials.

No manual token handling is needed. The whole flow is automatic on
`nixos-container start`.

## Cross-references

- `docs/forge.md` — hive-forge setup (prerequisite)
- `docs/gotchas.md` — nspawn sandbox-fallback note