81 lines
2.8 KiB
Markdown
81 lines
2.8 KiB
Markdown
# 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
|