docs: the deployment as it actually is — loopback, midgard, and a label that does not exist #19

Merged

larandar merged 2 commits from tango/deployment-truths into main

2026-08-11 06:38:28 +00:00

agent.odin commented

2026-08-11 06:15:41 +00:00

Owner

Four corrections to what this repository says about its own deployment, all found while writing the deployment design note for lar.ad/flake-ops#75 against the live forge. Documentation and option descriptions only.

In scope

Where this can run. A new README section, and the same fact on services.jostoph.forgejo.url. The estate's Forgejo sets webhook.ALLOWED_HOST_LIST = "loopback" — a line in lar.ad/flake-ops's modules/impls/forge/forgejo.nix written naming this steward before it existed — so the steward runs on the forge's own host or its hook silently never fires. The examples showed https://jostoph.ting.example/webhook/forgejo, which is the one shape that cannot work. They now show http://127.0.0.1:8420/webhook/forgejo, with the two things that look wrong about it explained: no reverse proxy, because /v1/audit and /v1/evaluate ride the same listener and anything fronting the hook fronts them too unless it filters by path; and http, because the X-Forgejo-Signature authenticates the delivery rather than the transport, which never leaves the host.
Forge credentials: none are needed. The section still said the canonical is private "and there is no flake.lock committed yet for that reason". The lock is committed and pins the public midgard mirror — which flake.nix already explains at length on the input itself. This was the one factual error I found in the repository, and it is the sentence that would stop a reader from writing an anonymous input. The netrc recipe stays, scoped to what it is still for: working against the private canonical.
The curated label does not exist. Read on 2026-08-10, the Ting org carries no labels at all — none at org level, none on any repository. So curated_label never matches and the merge rule can only ever take its squash branch, silently and forever, because a label that was never created is indistinguishable from one the author chose to withhold. Recorded as a note beside the rule. lar.ad already carries the equivalent as Reviewed/Curated ("preserve the commit line (rebase/ff); absence means squash. Set by approver."), so if Ting adopts that naming the parameter is wrong as well as unmatched.
nix/module.nix still described the pre-ruling world. forgejo.url told the reader forge-side conformance is the steward's, "reached at birth through just forgejo and reconciled after". The README already records the owner's ruling of 2026-08-05 against that; the module was the last place still saying otherwise, and an option description is what someone reads before going to look for a recipe that is not there.
Two smaller ones: the secret_file comment said "the same file", which is the one thing it cannot be — it is read on the machine that reconciles, and webhookSecretFile on the machine that verifies; and the secret's provenance now records the owner's 2026-08-10 ruling that OpenBao mints it, which makes this hook the estate's first managed secret.

Out of scope

Any change to the rules or their parameters. curated_label is flagged, not renamed — which name Ting adopts is Ting's call, and it travels with whoever creates the label.
Creating the label. It is desired state, so it belongs in pipeline_labels on the forge-conformance trait in lar.ad/flake-ops, not here.
Any option semantics. Nothing but descriptions, comments, and one example changed in nix/module.nix.
The branch-model question. Ting is a one-branch namespace and forge-conformance assumes two; that is flake-ops#75's problem, not this repository's.

Boundary

Two files, README.md and nix/module.nix. No Rust, no policy parameters, no nix/forgejo.nix, no build inputs, no lock. Nothing that can change what the steward decides.

Acceptance

The README no longer claims a credential is required or that no lock is committed, and the deployment example is one that would actually receive a delivery.
nix flake check still passes — see the caveat below.
No diff outside README.md and nix/module.nix.

Caveat, stated plainly

I did not run nix flake check. These commits were made through the forge API from a workspace that has no checkout of this repository, so nothing here was evaluated. The change is confined to description strings, comments, and one example, none of which participate in evaluation beyond being parsed — but that is an argument, not a test, and the check is the thing that settles it.

Authored as agent.odin.

Four corrections to what this repository says about its own deployment, all found while writing the deployment design note for [lar.ad/flake-ops#75](https://jo.et0.pw/lar.ad/flake-ops/issues/75) against the live forge. Documentation and option descriptions only. ## In scope - **Where this can run.** A new README section, and the same fact on `services.jostoph.forgejo.url`. The estate's Forgejo sets `webhook.ALLOWED_HOST_LIST = "loopback"` — a line in `lar.ad/flake-ops`'s `modules/impls/forge/forgejo.nix` written naming this steward before it existed — so the steward runs on the forge's own host or its hook silently never fires. The examples showed `https://jostoph.ting.example/webhook/forgejo`, which is the one shape that cannot work. They now show `http://127.0.0.1:8420/webhook/forgejo`, with the two things that look wrong about it explained: no reverse proxy, because `/v1/audit` and `/v1/evaluate` ride the same listener and anything fronting the hook fronts them too unless it filters by path; and `http`, because the `X-Forgejo-Signature` authenticates the delivery rather than the transport, which never leaves the host. - **Forge credentials: none are needed.** The section still said the canonical is private *"and there is no `flake.lock` committed yet for that reason"*. The lock **is** committed and pins the public `midgard` mirror — which `flake.nix` already explains at length on the input itself. This was the one factual error I found in the repository, and it is the sentence that would stop a reader from writing an anonymous input. The netrc recipe stays, scoped to what it is still for: working against the private canonical. - **The `curated` label does not exist.** Read on 2026-08-10, the `Ting` org carries no labels at all — none at org level, none on any repository. So `curated_label` never matches and the merge rule can only ever take its `squash` branch, silently and forever, because a label that was never created is indistinguishable from one the author chose to withhold. Recorded as a note beside the rule. `lar.ad` already carries the equivalent as `Reviewed/Curated` ("preserve the commit line (rebase/ff); absence means squash. Set by approver."), so if Ting adopts that naming the parameter is wrong as well as unmatched. - **`nix/module.nix` still described the pre-ruling world.** `forgejo.url` told the reader forge-side conformance is the steward's, "reached at birth through `just forgejo` and reconciled after". The README already records the owner's ruling of 2026-08-05 against that; the module was the last place still saying otherwise, and an option description is what someone reads before going to look for a recipe that is not there. - Two smaller ones: the `secret_file` comment said "the same file", which is the one thing it cannot be — it is read on the machine that **reconciles**, and `webhookSecretFile` on the machine that **verifies**; and the secret's provenance now records the owner's 2026-08-10 ruling that OpenBao mints it, which makes this hook the estate's first managed secret. ## Out of scope - **Any change to the rules or their parameters.** `curated_label` is flagged, not renamed — which name Ting adopts is Ting's call, and it travels with whoever creates the label. - **Creating the label.** It is desired state, so it belongs in `pipeline_labels` on the `forge-conformance` trait in `lar.ad/flake-ops`, not here. - **Any option semantics.** Nothing but descriptions, comments, and one `example` changed in `nix/module.nix`. - **The branch-model question.** `Ting` is a one-branch namespace and `forge-conformance` assumes two; that is flake-ops#75's problem, not this repository's. ## Boundary Two files, `README.md` and `nix/module.nix`. No Rust, no policy parameters, no `nix/forgejo.nix`, no build inputs, no lock. Nothing that can change what the steward decides. ## Acceptance - The README no longer claims a credential is required or that no lock is committed, and the deployment example is one that would actually receive a delivery. - `nix flake check` still passes — see the caveat below. - No diff outside `README.md` and `nix/module.nix`. ## Caveat, stated plainly **I did not run `nix flake check`.** These commits were made through the forge API from a workspace that has no checkout of this repository, so nothing here was evaluated. The change is confined to description strings, comments, and one `example`, none of which participate in evaluation beyond being parsed — but that is an argument, not a test, and the check is the thing that settles it. Authored as `agent.odin`.

agent.odin added 2 commits

2026-08-11 06:15:41 +00:00

docs: the deployment as it actually is — loopback, midgard, and a label that does not exist b0043722db

Four corrections, all found while writing the deployment note for
lar.ad/flake-ops#75 against the live forge.

Where this can run: on the forge's own host and nowhere else. The estate's
Forgejo sets webhook.ALLOWED_HOST_LIST = "loopback" — a line written naming
this steward before it existed — so the URL is http://127.0.0.1:8420, not the
public vhost the examples showed. The two things that look wrong about that
are deliberate and now say so: no reverse proxy, because /v1/audit and
/v1/evaluate ride the same listener and anything fronting the hook fronts them
too; and http, because the signature authenticates the delivery, not the
transport, which never leaves the host.

Forge credentials: none are needed. The section still said the canonical is
private "and there is no flake.lock committed for that reason" — but the lock
is committed and pins the public midgard mirror, which flake.nix already
explains at length. The netrc recipe stays, scoped to what it is still for:
working against the private canonical.

The curated label does not exist. Read on 2026-08-10, Ting carries no labels
at all, so curated_label never matches and the merge rule can only ever take
its squash branch — silently, because a label never created is
indistinguishable from one the author withheld. lar.ad already carries the
equivalent as Reviewed/Curated, so the parameter may be wrong as well as
unmatched. Flagged, not changed: which name Ting adopts is Ting's call.

And the secret_file comment said "the same file", which is the one thing it
cannot be: it is read on the machine that reconciles and the other on the
machine that verifies. Same value, two deliveries — which is why the owner
ruled on 2026-08-10 that OpenBao mints it.

Refs: lar.ad/flake-ops#75

module: the option docs say what the owner ruled, not what law 12 said 468e82eec5

forgejo.url still told the reader that forge-side conformance is the
steward's, "reached at birth through `just forgejo` and reconciled after".
The README already records that the owner ruled on 2026-08-05 against that:
it is the nixops4 provider's, declared and reconciled like any other
resource. The module was the last place still saying otherwise, and an
option description is what someone reads before they go looking for a
recipe that is not there.

Its example is now the URL a real deployment can use. Forgejo refuses
loopback and private delivery targets unless the instance opts in, and the
estate's instance opts in to loopback only — so a public vhost as the
worked example points at the one shape whose hook silently never fires.

webhookSecretFile gains the fact that makes its handling non-obvious: the
same value is read again, on a different machine with a different
lifecycle, as the hook's secret_file.

Comments and examples only — no option semantics change, and nothing here
was evaluated by me. Refs: lar.ad/flake-ops#75