From 5814f177c89ff69f5232dbd4eb69d980b2dd7151 Mon Sep 17 00:00:00 2001 From: damocles Date: Sat, 21 Nov 2026 13:28:25 +0100 Subject: [PATCH] docs: the swarm-builder status gates the merge now, and no promise about rebasing a PR branch --- docs/2-handbook/swarm/services.md | 3 ++- docs/4-implementation/swarm/builder.md | 7 ++++--- docs/4-implementation/swarm/controller.md | 6 +++--- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/2-handbook/swarm/services.md b/docs/2-handbook/swarm/services.md index 455fa736e..8f27fa612 100644 --- a/docs/2-handbook/swarm/services.md +++ b/docs/2-handbook/swarm/services.md @@ -191,7 +191,8 @@ metrics it exports and the threat model: The swarm builder, in a `swarm-builder` container on the host that sets `deploy.builder.enable`; set it to `false` to opt out. It evaluates and builds unreviewed agent config PRs, and the result shows as a `swarm-builder` commit -status on the PR. A red status blocks nothing: the merge still deploys. It also +status on the PR. The status is required: a red or missing one blocks the +merge. It also builds each agent before the swarm sends its deploy, and a failed build holds that deploy back. The jobs show on the swarm UI's Jobs page. It builds through its host's nix daemon, so it costs real CPU and disk. diff --git a/docs/4-implementation/swarm/builder.md b/docs/4-implementation/swarm/builder.md index ff8e41827..325387ca6 100644 --- a/docs/4-implementation/swarm/builder.md +++ b/docs/4-implementation/swarm/builder.md @@ -122,7 +122,8 @@ status has no link. host's store until it's collected, so on a host that also runs the hive, the hive's own build can reuse whatever matches. A [meta build](#deploy-gate) can push to [a binary cache](#binary-cache). -- The PR check gates nothing. A merge deploys whatever the status says. The +- The PR check gates the merge: `swarm-builder` is a required status on every + config repo's `main`, so a red or missing status blocks it. The [deploy gate](#deploy-gate) is a separate build, from `internal/meta`. - A lost webhook delivery of a PR push isn't retried: the head isn't built until the next push. The jobs graph is in memory, so a controller restart drops a build in @@ -712,8 +713,8 @@ swarm-controller queues a `build_agent` job. Jobs run one at a time, and a newer push replaces its PR's job while that job is still waiting. The builder builds that config at the PR's head on the agent base its own host runs, through the host's nix daemon, and swarm-controller writes the result as a `swarm-builder` -commit status on the head. The job shows on the swarm UI's Jobs page. A red -status blocks nothing: the merge still deploys. +commit status on the head. The job shows on the swarm UI's Jobs page. The +status is required on `main`: a red or missing one blocks the merge. Separately, the builder builds each agent from `internal/meta` before the swarm sends its deploy, and a failed or unpushed build holds that deploy back (`build_meta` job; diff --git a/docs/4-implementation/swarm/controller.md b/docs/4-implementation/swarm/controller.md index 38f71336a..3428644a4 100644 --- a/docs/4-implementation/swarm/controller.md +++ b/docs/4-implementation/swarm/controller.md @@ -397,9 +397,9 @@ one per hive. It ensures them at start and every five minutes after commit status has to pass before a merge, and no other status is required. The controller leaves a repo with no `main` rule alone; - the merge settings of every `agent-configs` repo: fast-forward-only is - the default merge style, and rebase stays on, so an operator can rebase - an out-of-date PR branch onto `main`. The other merge styles stay as the - repo has them; + the default merge style, and the rebase merge style stays allowed. The + other merge styles stay as the repo has them, and the rule's blocking of + out-of-date branches stays as it was; - the pull-mirrors from `deploy.forgejo.mirrors` on the controller's host (with the `actions/checkout` and `actions/upload-artifact` ones `deploy.forgejo.actionsFromSelf` adds, and `hyperhive/hyperhive` from