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

docs(ci): document actions/checkout mirror + forge.mirrors option

Browse source 
feat(#2072) auto-seeded an actions/checkout pull-mirror when
forge.ci.enable is set, pointing Forgejo DEFAULT_ACTIONS_URL at the
local instance so CI uses: steps resolve on loopback. Also added a
general-purpose forge.mirrors option for pre-seeding any upstream
repo as a pull-mirror. Neither feature was documented in docs/ci.md.
This commit is contained in:
iris 2026-07-02 15:32:34 +02:00 • committed by mara
commit 6999217c29
1 changed files with 34 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

34
docs/ci.md
View file

@ -33,6 +33,40 @@ Set `services.hyperhive.forge.ci.enable = true` in the host NixOS config. That's
3. If `.runner` is absent (first boot or purged above): fetch a fresh registration token from `GET /api/v1/admin/runners/registration-token`. Retries for 30s in case forge is still starting. Writes `TOKEN=<real>` to `/run/hive-ci/runner-token`.
4. Container starts with `/run/hive-ci/runner-token` bind-mounted read-only. `gitea-actions-runner` reads the token, registers itself, and persists credentials to `.runner`. On subsequent boots step 2 validates these credentials and fast-paths past registration.
## Actions checkout mirror
When `forge.ci.enable` is set, hive-c0re auto-seeds an
`actions/checkout` pull-mirror on the local forge and sets Forgejo's
`DEFAULT_ACTIONS_URL` to point at the local instance. This means CI
`uses: actions/checkout@vN` steps resolve entirely on loopback — no
external DNS on the CI critical path.
The mirror is seeded by **hive-c0re** itself during its forge
provisioning sweep (`forge.rs::ensure_mirrors`). The nix module
forwards the effective mirror list as `HYPERHIVE_FORGE_MIRRORS` in the
`hive-c0re` service environment (JSON-encoded `[{upstream, dest}]`
list). hive-c0re already holds the admin token for the rest of the
forge provisioning sweep (orgs, agent accounts, etc.), so mirror
seeding lives in the same place rather than a separate host-side unit.
**General-purpose mirrors**: you can pre-seed any external repo as a
pull-mirror via `services.hyperhive.forge.mirrors`:
```nix
services.hyperhive.forge.mirrors = [
{ upstream = "https://github.com/actions/checkout"; dest = "actions/checkout"; }
{ upstream = "https://github.com/example/tool"; dest = "mirrors/tool"; }
];
```
Each entry is created as a real Forgejo pull-mirror — not a one-off
clone. Forgejo re-syncs the mirror on every pull (`git-upload-pack`
request), so a DNS blip during that sync will propagate back to the
runner as a hard `git clone` failure. The
`<owner>` org in `dest` is auto-created. Keep mirror dests out of the
hive-c0re-managed namespaces (`config/`, `shared/`, `agents/`, `core/`)
to avoid provisioning collisions.
## CI workflow
The single CI job is defined in `.forgejo/workflows/ci.yml`: