feat: add hive-ci module — Forgejo Actions runner for CI

Adds `services.hyperhive.ci` NixOS module that spins up a `hive-ci`
nixos-container running `gitea-actions-runner` against the hive-forge
Forgejo instance. Off by default; opt in with `ci.enable = true` after
generating a runner registration token in Forgejo.

Also adds `.forgejo/workflows/ci.yml` with four jobs: nix flake check,
formatting (nix fmt + cargo fmt), cargo test, and cargo clippy. Jobs
target the `hive-ci` runner label.

Container design mirrors hive-forge (shared host netns, non-ephemeral
state, loopback reach to forge). sandbox-fallback = true since nspawn
containers can't create user-namespaces for nix sandbox.

Closes #175.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.forgejo/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  check:
+    name: nix flake check
+    runs-on: [hive-ci]
+    steps:
+      - uses: actions/checkout@v3
+      - name: check
+        run: nix flake check --no-build
+
+  fmt:
+    name: formatting
+    runs-on: [hive-ci]
+    steps:
+      - uses: actions/checkout@v3
+      - name: nix fmt
+        run: nix fmt -- --check .
+      - name: cargo fmt
+        run: cargo fmt --all -- --check
+
+  test:
+    name: cargo test
+    runs-on: [hive-ci]
+    steps:
+      - uses: actions/checkout@v3
+      - name: test
+        run: cargo test --workspace
+
+  clippy:
+    name: cargo clippy
+    runs-on: [hive-ci]
+    steps:
+      - uses: actions/checkout@v3
+      - name: clippy
+        run: cargo clippy --workspace -- -D warnings

flake.nix

@@ -246,6 +246,7 @@
           agentBaseToplevel = self.packages.x86_64-linux.agent-base-toplevel;
           managerToplevel = self.packages.x86_64-linux.manager-toplevel;
         };
+        hive-ci = ./nix/modules/hive-ci.nix;
         hive-forge = ./nix/modules/hive-forge.nix;
         # Convenience alias: one import covers the full hyperhive host
         # stack (hive-c0re + hive-forge, since hive-c0re already pulls

nix/modules/hive-c0re.nix

@@ -22,6 +22,7 @@ in
   # opt-in (off by default) and asserts that `services.hyperhive.domain`
   # is set before it can be enabled.
   imports = [
+    ./hive-ci.nix
     ./hive-forge.nix
     ./hive-gateway.nix
     ./hive-matrix.nix
@@ -99,34 +100,40 @@ in
   # `identity.rs::peers()` + the dashboard's `peer_hives` state field
   # (feeds the P33RS dashboard tab).
   options.services.hyperhive.peers = lib.mkOption {
-    type = lib.types.attrsOf (lib.types.submodule {
+    type = lib.types.attrsOf (
-      options = {
+      lib.types.submodule {
-        domain = lib.mkOption {
+        options = {
-          type = lib.types.str;
+          domain = lib.mkOption {
-          example = "lab.example.com";
+            type = lib.types.str;
-          description = ''
+            example = "lab.example.com";
-            DNS domain of the peer hive. Used to construct the peer's
+            description = ''
-            dashboard URL (`http://''${domain}/`) and for Matrix
+              DNS domain of the peer hive. Used to construct the peer's
-            federation auto-discovery (`matrix.''${domain}`).
+              dashboard URL (`http://''${domain}/`) and for Matrix
-            Must be reachable from this host.
+              federation auto-discovery (`matrix.''${domain}`).
-          '';
+              Must be reachable from this host.
+            '';
+          };
+          tlsCertFile = lib.mkOption {
+            type = lib.types.nullOr lib.types.path;
+            default = null;
+            description = ''
+              Optional path to a PEM cert/bundle to trust for this peer's
+              TLS. Null = system CA bundle (for Let's Encrypt peers). Set
+              to the peer's self-signed cert for `selfSignedTls = true`
+              peers. Forward-compat slot; not yet used in v0.
+            '';
+          };
         };
-        tlsCertFile = lib.mkOption {
+      }
-          type = lib.types.nullOr lib.types.path;
+    );
-          default = null;
-          description = ''
-            Optional path to a PEM cert/bundle to trust for this peer's
-            TLS. Null = system CA bundle (for Let's Encrypt peers). Set
-            to the peer's self-signed cert for `selfSignedTls = true`
-            peers. Forward-compat slot; not yet used in v0.
-          '';
-        };
-      };
-    });
     default = { };
     example = {
-      lab = { domain = "lab.example.com"; };
+      lab = {
-      edge = { domain = "edge.corp"; };
+        domain = "lab.example.com";
+      };
+      edge = {
+        domain = "edge.corp";
+      };
     };
     description = ''
       Peer hives in the same swarm. The attrset key is a short label
@@ -345,24 +352,29 @@ in
         # links; when false it falls back to direct `<host>:<port>` TCP.
         HIVE_GATEWAY_ENABLED = "1";
       }
-      // lib.optionalAttrs (config.services.hyperhive.forge.enable && config.services.hyperhive.forge.behindGateway) {
+      //
-        # Public URL of the forge vhost served by hive-gateway. The
+        lib.optionalAttrs
-        # dashboard uses this to build browser-facing forge links
+          (config.services.hyperhive.forge.enable && config.services.hyperhive.forge.behindGateway)
-        # instead of hardcoding `<hostname>:3000`, which breaks when
+          {
-        # the operator accesses the dashboard through the gateway
+            # Public URL of the forge vhost served by hive-gateway. The
-        # (forge sub-domain has no port; direct port URL would be
+            # dashboard uses this to build browser-facing forge links
-        # wrong). Absent when `behindGateway = false` — dashboard
+            # instead of hardcoding `<hostname>:3000`, which breaks when
-        # falls back to `<hostname>:3000`.
+            # the operator accesses the dashboard through the gateway
-        HIVE_FORGE_PUBLIC_URL = "https://${config.services.hyperhive.forge.domain}";
+            # (forge sub-domain has no port; direct port URL would be
-      }
+            # wrong). Absent when `behindGateway = false` — dashboard
+            # falls back to `<hostname>:3000`.
+            HIVE_FORGE_PUBLIC_URL = "https://${config.services.hyperhive.forge.domain}";
+          }
       // lib.optionalAttrs (config.services.hyperhive.peers != { }) {
         # Peer hives serialised as a JSON array of {label, domain} objects.
         # Consumed by hive-ag3nt::identity::peers() + the dashboard's
         # peer_hives StateSnapshot field (P33RS tab). tlsCertFile is
         # nix-side-only (host nginx/trust config); rust never needs the path.
         HYPERHIVE_PEERS = builtins.toJSON (
-          lib.mapAttrsToList (label: p: { inherit label; inherit (p) domain; })
+          lib.mapAttrsToList (label: p: {
-            config.services.hyperhive.peers
+            inherit label;
+            inherit (p) domain;
+          }) config.services.hyperhive.peers
         );
       };
       serviceConfig = {

nix/modules/hive-ci.nix

@@ -0,0 +1,191 @@
+{
+  pkgs,
+  lib,
+  config,
+  ...
+}:
+let
+  cfg = config.services.hyperhive.ci;
+  forgeCfg = config.services.hyperhive.forge;
+in
+{
+  # Forgejo Actions runner in a `hive-ci` nixos-container.
+  # Shares host netns (same as hive-forge), so the runner reaches
+  # the forge at `http://127.0.0.1:<httpPort>` without extra plumbing.
+  # Container is non-ephemeral: the runner's registered credentials
+  # survive restarts (gitea-actions-runner writes them to its stateDir
+  # on first registration and reuses them on every subsequent start).
+  #
+  # Nix builds inside the container use the shared /nix/store (standard
+  # nixos-container behaviour) with sandbox-fallback = true, because
+  # nspawn containers can't create the user-namespaces that nix sandboxing
+  # requires. See docs/gotchas.md.
+  #
+  # Operator bootstrap: generate a runner registration token in Forgejo
+  # (Site Administration → Runners → Registration Token), store it in
+  # a secrets file on the host, and point `runnerTokenFile` at it.
+  # The token is consumed on first start; the runner's persistent
+  # credentials live in the container state dir afterwards.
+
+  options.services.hyperhive.ci = {
+    enable = lib.mkOption {
+      type = lib.types.bool;
+      default = false;
+      example = true;
+      description = ''
+        Run a Forgejo Actions runner in a `hive-ci` nixos-container.
+        Disabled by default; requires `services.hyperhive.forge.enable = true`
+        (the runner registers against the hive-forge instance) and a
+        registration token at `runnerTokenFile`.
+      '';
+    };
+
+    runnerTokenFile = lib.mkOption {
+      type = lib.types.path;
+      example = "/run/secrets/ci-runner-token";
+      description = ''
+        Host path to a file containing the Forgejo runner registration
+        token (one token per line, no trailing whitespace). Obtain it
+        from Forgejo: Site Administration → Runners → Registration Token.
+
+        The file is bind-mounted read-only into the container and consumed
+        on first start. After registration the runner's actual credentials
+        are persisted in the container's state dir; the token file can be
+        deleted or revoked from Forgejo without affecting the running
+        runner.
+      '';
+    };
+
+    name = lib.mkOption {
+      type = lib.types.str;
+      default = "hive-ci";
+      example = "my-hive";
+      description = ''
+        Runner name as shown in the Forgejo admin panel.
+        Defaults to "hive-ci"; override when multiple hives share a
+        Forgejo instance to keep them distinct.
+      '';
+    };
+
+    concurrency = lib.mkOption {
+      type = lib.types.ints.positive;
+      default = 1;
+      example = 4;
+      description = ''
+        Maximum number of workflow jobs the runner executes in parallel.
+        Each job gets its own temporary working directory; multiple parallel
+        jobs share the container's nix store and cargo registry cache.
+        Higher values trade memory + CPU headroom for throughput.
+      '';
+    };
+
+    labels = lib.mkOption {
+      type = lib.types.listOf lib.types.str;
+      default = [
+        "hive-ci:host"
+        "ubuntu-latest:host"
+        "ubuntu-22.04:host"
+      ];
+      example = [
+        "hive-ci:host"
+        "nix:host"
+      ];
+      description = ''
+        Runner labels. Each entry has the shape `<name>:<scheme>`. The
+        `host` scheme means the runner executes commands directly on the
+        container (no docker/podman). Workflow files target this runner
+        with `runs-on: [hive-ci]` (or whichever label the operator picks).
+
+        The `ubuntu-latest` and `ubuntu-22.04` aliases let upstream
+        workflow files that hardcode GitHub-style runner names work
+        unchanged — the host runner is a reasonable substitute for
+        CI steps that only need git + nix + cargo and don't depend on
+        Ubuntu-specific APT packages.
+      '';
+    };
+
+    package = lib.mkOption {
+      type = lib.types.package;
+      default = pkgs.gitea-actions-runner;
+      defaultText = lib.literalExpression "pkgs.gitea-actions-runner";
+      description = ''
+        gitea-actions-runner package. Defaults to `pkgs.gitea-actions-runner`
+        (the nixpkgs release tracking Forgejo's runner releases).
+      '';
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    assertions = [
+      {
+        assertion = forgeCfg.enable;
+        message = ''
+          services.hyperhive.ci.enable = true requires
+          services.hyperhive.forge.enable = true — the runner registers
+          against the hive-forge Forgejo instance. Either enable the forge
+          or leave ci.enable at its default of false.
+        '';
+      }
+    ];
+
+    containers.hive-ci = {
+      autoStart = true;
+      ephemeral = false;
+      # Shared host netns: runner reaches hive-forge at localhost without
+      # any port-forwarding dance. Same pattern as hive-forge itself.
+      privateNetwork = false;
+
+      # Bind the token file read-only into the container at a stable
+      # internal path the NixOS module option below references.
+      bindMounts."/run/hive-ci/runner-token" = {
+        hostPath = toString cfg.runnerTokenFile;
+        isReadOnly = true;
+      };
+
+      config =
+        { pkgs, lib, ... }:
+        {
+          system.stateVersion = "25.11";
+
+          # nspawn containers can't create user-namespaces, so nix
+          # sandboxing always fails. Fall back to unsandboxed builds
+          # rather than erroring out. See docs/gotchas.md.
+          nix.settings.sandbox-fallback = lib.mkForce true;
+
+          # Flakes + nix-command needed by workflow steps.
+          nix.settings.experimental-features = [
+            "nix-command"
+            "flakes"
+          ];
+
+          services.gitea-actions-runner.instances.hive = {
+            enable = true;
+            name = cfg.name;
+            # Reach hive-forge on loopback — shared netns means this
+            # is always reachable regardless of firewall / DNS config.
+            url = "http://127.0.0.1:${toString forgeCfg.httpPort}";
+            tokenFile = "/run/hive-ci/runner-token";
+            labels = cfg.labels;
+            settings = {
+              runner.capacity = cfg.concurrency;
+              # Generous timeout for nix builds that may be cold-cache.
+              runner.timeout = "3h";
+            };
+            package = cfg.package;
+          };
+
+          # Tools available to workflow steps. Rust toolchain covers
+          # cargo test + cargo clippy. nix covers flake check + fmt.
+          # git is required by the runner and actions/checkout.
+          environment.systemPackages = [
+            pkgs.git
+            pkgs.nix
+            pkgs.cargo
+            pkgs.rustc
+            pkgs.rustfmt
+            pkgs.clippy
+          ];
+        };
+    };
+  };
+}