# Forgejo-native CI: a `ci-box` tenant and a `forgejo-runner` command family Status: proposed (#109) Date: 2026-07-27 ## The shape of the thing A fleet machine hosts boxes. One of those boxes is the CI box. The Forgejo runner lives inside it, and CI jobs run in containers on that box's own dockerd. ``` +-----------------------------+ outbound HTTPS (long-poll) | Forgejo (Coolify) | <---------------------------------+ | forgejo.heavyduty.builders | | +-----------------------------+ | +------------------------------+---+ No inbound path to the box. | staging-server (host=yes) | The runner polls out. | +---------------------------+ | | | ci-box (tenant) | | | | forgejo-runner (systemd)| | | | dockerd -> job containers| | | +---------------------------+ | +----------------------------------+ ``` Three pieces, in two repos. ## 1. A forge-agnostic registry fetch (`commands/lib/templates.sh`) `templates_resolve` builds three candidate URLs, all on `github.com`. A registry hosted anywhere else cannot be fetched. The fix is a fourth knob beside `_DIR` / `_REF` / `_REPO`: ```sh RIG_TEMPLATES_HOST the forge origin (default https://github.com) ``` The candidate list becomes the host's fact rather than a constant, because the two forges genuinely differ: | | GitHub | Forgejo | |---|---|---| | Candidates | `archive/refs/tags/.tar.gz`, `archive/refs/heads/.tar.gz`, `archive/.tar.gz` | `archive/.tar.gz` — one form, which resolves tags, branches and SHAs alike | | Archive top-level dir | `-` | `` | Both were measured against `forgejo.heavyduty.builders`, not assumed. The existing "exactly one top-level directory" assert survives untouched — it globs `*/` rather than reconstructing the name, so the differing directory name costs nothing. Its **comment** was wrong for Forgejo and is corrected. `templates_source_desc` grows the host, so a misconfigured origin shows up in the unknown-role refusal instead of reading like a typo. The GitHub default means every existing caller behaves exactly as before. `install.sh`'s `snapshot_templates` duplicates the same candidate list for its install-time cache. It gets the same knob, from the same environment variable, so the snapshot and the live fetch cannot disagree about where the registry is. ### The blocker this exposed — since cleared **Resolved 2026-07-27, after this was written.** The operator set `REQUIRE_SIGNIN_VIEW=false`, and the mint-time path was then verified live: a credential-less `templates_resolve` with `RIG_TEMPLATES_HOST=https://forgejo.heavyduty.builders` fetches and extracts a real archive. Piece 1 is proven end to end on the target instance, not merely argued. The requirement below stands for *any* instance hosting a registry, and the refusal text still names it — it is a property of the mint's creds-free contract, not of one server's configuration. What follows is the original analysis, kept because it is why the knob exists. ### The blocker, as originally measured `templates_resolve` documents a hard contract: > the fetch is unauthenticated by contract (box auto-runs bootstrap at mint, > holding nothing) Measured: on `forgejo.heavyduty.builders`, anonymous requests for `heavy-duty/rig` — reported by the API as `private: false` — return **404** for the API, the web page, the git remote and the archive endpoint. Only an authenticated request succeeds. The instance requires sign-in to view. A mint holds no credentials, so **a Forgejo-hosted registry is unreachable at mint time** until the instance serves public repos anonymously: ``` FORGEJO__service__REQUIRE_SIGNIN_VIEW=false ``` This is a Coolify env-var change on the Forgejo service, next to the `FORGEJO__actions__ENABLED=true` that Actions already needs. It is recorded here and in the README as a prerequisite. Nothing in this change silently assumes it: with the gate up, the fetch fails the way any unreachable ref fails, listing every URL tried. ## 2. The `ci-box` tenant definition Data, not mechanism — it belongs in the registry repo. It is staged in this PR under `docs/templates/ci-box/` so it can be reviewed and linted here, and moves to the registry verbatim once that repo exists on Forgejo. ``` USER="ci" CONTEXT_PATH=".ci/CONTEXT.md" CLI_NAME="forgejo-runner" CLI_SRC="/usr/local/bin/forgejo-runner" PATH_LINE="export PATH="$HOME/.local/bin:$PATH"" NEEDS_NODE="no" ``` `CLI_SRC` is absolute rather than `~/`-relative, which is the one place this definition departs from the agent tenants. Their CLI lives in the tenant's home; this binary is executed by a systemd unit, and a tenant-writable binary that a root-installed unit runs is a trivial path to root inside the box. So it lands root-owned under `/usr/local/bin`. `test/cli.sh` pins `CLI_SRC` against the path `install.sh` actually writes — a drifted pair converges to a CLI that exists and cannot run, which is the scar `grok-box` left. `NEEDS_NODE="no"` because the runner is a static Go binary. Jobs get their Node from the container image, which is the whole point of the label mapping below — installing a second Node on the host would be a toolchain nobody reads. `install.sh` fetches the release binary for the architecture and **verifies the published `.sha256` before installing it**. Forgejo ships bare binaries with `.sha256` and `.asc` beside them rather than a tarball, so a checksum is available for free; taking it makes the install auditable in the way `coolify install`'s version pin is. This satisfies the tenant schema honestly rather than by paperwork: `bootstrap-tenant.sh` asserts ` --version` answers **as the tenant user**, and `forgejo-runner --version` does. `creds.md` states the box holds no Forgejo credential and that registration is a separate, operator-run act — which is true, and is what the rendered context file needs to say. ### Why the box replaces docker-in-docker The setup guide this design came from builds a `docker:dind` sidecar with `privileged: true` and a plaintext `tcp://…:2375` daemon socket. Inside a tenant that is redundant: `bootstrap-tenant.sh` already installs Docker on every tenant and adds the tenant user to the `docker` group. The runner talks to that daemon over its own socket. The isolation argument that justifies dind on a shared CI server is already paid for here by the box: it is network-isolated, disposable, and has no inbound path. Stacking dind inside it would add a privileged container to buy a boundary that already exists. Note the trade this makes explicit: `docker` group membership is root-equivalent *within the box*. `rig runner install` refuses Docker for exactly that reason — but it converges a fleet **machine**, where the blast radius is the machine. Here the blast radius is a guest that is thrown away. That is the difference that makes the same trade correct in one place and wrong in the other. ## 3. `rig forgejo-runner install|status|remove` A new family beside `rig runner`, which is left untouched. ```sh box shell ci-box sudo rig forgejo-runner install \ --instance https://forgejo.heavyduty.builders \ --name ci-runner-1 ``` Default labels: ``` ubuntu-latest:docker://ghcr.io/catthehacker/ubuntu:act-22.04,docker:docker://node:22-bookworm ``` so `runs-on: ubuntu-latest` works in a workflow written for GitHub. ### Why not `rig runner --forge forgejo` GitHub's runner registers against a repository URL, and `assert_runner_repo` converges toward `--repo`: re-running against the same repo is a no-op, a different repo is refused because silently restarting on the old one would leave the requested repo with jobs queued forever. Forgejo has no such argument. The runner registers against an **instance**, and whether the registration is instance-wide, org, or single-repo is a property of the *token*, decided in Forgejo's UI before rig ever sees it. There is no repo to converge toward and nothing to compare. Folding that into one command would make every guard bimodal to share a flag name, while the contract underneath differs. Two families is the smaller lie. ### `register` is deprecated upstream, and is still the right call Measured on v12.13.2: both `forgejo-runner register` and `create-runner-file` carry `(deprecated)` in their help. The successor is `daemon --url --uuid --token-url `, which requires the runner to **already exist on the instance** — the operator creates it via the API or UI and carries a UUID back. `register` is chosen anyway: - It still works, and this was verified rather than assumed. A planted `.runner` made `daemon` resolve the instance from the file, connect to a live Forgejo, and fail with `Unauthenticated: unregistered runner` — the transport and the file format are intact; only the credential was fake. - The successor asks the operator for a second, differently-shaped credential dance for no gain today. - `register` writes a file `status` can read back. Under the successor, "what is this box registered to" has no on-disk answer that is not merely rig's own copy of what it was told. When upstream removes it: the unit line gains `--url`/`--uuid`, and the readers in `forgejo-runner-config.sh` move to whatever holds the UUID. `assert_runner_instance`'s contract survives either spelling, because it asks about the instance — which both record. Not verified here, and left to the drill: that `register` writes `.runner` on a live instance. That needs a real registration token, which this design cannot mint. ### The convergence guard that does apply `assert_runner_instance`: re-running against the instance this box is already registered to re-uses the binary and skips registration; a **different** instance refuses and names both. Same trust-boundary reasoning as `assert_runner_repo`, asked about the axis Forgejo actually has. ### Three corrections from review !110 The first draft carried three defects that review caught, all of the same family — a stated contract that the code did not actually keep: 1. **`--version` was swallowed on the primary path.** The download block skipped on mere presence, copying `rig runner install`'s shape without its justification: `actions/runner` self-updates, `forgejo-runner` does not. And a ci-box's template *preinstalls* the binary at mint, so the flag documented as the deterministic-pin lever could never fire on a ci-box. The decision is now `runner_download_decision` in the lib — a pure function, so the rule is driven by tests instead of asserted by grep — and the binary is renamed into place rather than written over, since the converge path now runs while the daemon is live (in-place would be `ETXTBSY`). 2. **`.rig-labels` outlived the registration it described.** The write had escaped the registration branch, where `runner-install.sh` correctly keeps its copy. A plain re-run stamped that invocation's labels over a registration made with different ones, and `status` then reported confidently wrong labels while Forgejo held the originals. It is scoped again, and an *explicit* `--labels` on a re-run now warns that Forgejo owns labels from registration time. 3. **The checksum gate failed open.** A missing `.sha256` warned and installed anyway — contradicting both the README and this file's own comment about unverified root downloads. The original reasoning (do not let an upstream layout change break installs) reasons about the wrong failure: a layout change breaks the *binary* URL too, so "binary yes, checksum no" is the shape of an interfered fetch, which is what the checksum is for. Both paths refuse now, with no bypass flag. ### `.runner` holds a credential here GitHub's `.runner` names a repo. Forgejo's holds `address`, `name`, `labels` **and the runner's own long-lived token** — the credential it authenticates with on every poll. So this family does something its GitHub sibling never had to: it installs `.runner` as `0600` owned by the runner user, and **re-asserts that mode on every converge**. A registration secret readable by every account on the box would be a quiet, permanent credential leak, and convergence is the only moment rig can notice a mode that drifted. `status` therefore reads `address`, `name` and `labels` and never prints the token. ### Removal Forgejo's runner has no deregistration handshake — no removal-token endpoint, no `config.sh remove`. `remove` stops and disables the unit and wipes the local registration, then says plainly that the entry must be deleted in Forgejo's admin UI. `rig runner remove`'s `--local` escape hatch is the *only* mode here, so it is not offered as a flag that suggests a server-side alternative exists. ## Guard: `bootstrap --undo` `bootstrap-undo.sh` refuses to leave the tailnet while a GitHub runner is installed, so undo cannot strand a ghost runner in a repository. The same hazard exists for a Forgejo runner on a machine, so the guard learns the `forgejo-runner.service` unit and the `.runner` under the runner user's home. ## Testing `test/cli.sh` is dependency-free, non-root, offline. What it can prove: - Every new command's arg validation, `--help`, and unknown-flag refusals. - `bin/rig` dispatch, including bare `rig forgejo-runner` showing usage. - The forge-aware URL builder as a **pure function**, lifted and driven directly: GitHub host yields the three-candidate list in tag-first order, a Forgejo host yields the single `/archive/.tar.gz`. - `templates_source_desc` names a non-default host. - The staged `ci-box` definition passes `rig template-lint` — the same parser a mint runs, so the definition cannot ship malformed. - Grep-pins that the `.runner` 0600 assert and the `bootstrap --undo` forgejo-runner guard are present, so a deleted guard cannot ship green (the repo's existing precedent for guards that need a real machine). What it cannot prove, and is left to the drill: a real registration against a live Forgejo, and a job actually executing in a container. ## Out of scope `install.sh` hardcodes `github.com` in `resolve_latest_tag` and `ref_candidate_urls` (rig's own source), and `commands/bootstrap.sh` fetches box from `raw.githubusercontent.com`. Hosting rig itself on Forgejo needs those too. They are follow-ups, not this change — `snapshot_templates` is included here only because it fetches *the registry*, and leaving it behind would let the snapshot and the live fetch disagree about where the registry lives.