vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hyperhive/docs/ci.md

2.8 KiB
Raw Blame History

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

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:

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