docs(gitea-runner): state that a runs-on label list is AND, not fallback

I wrote "one-line fallback to pfi-fleet costs you nothing" to a peer,
meaning a manual edit; it was read as scheduler behaviour, and
`runs-on: [vastblue, pfi-fleet]` would have shipped into a contract. A
label list requires ALL the labels, so that form matches no runner and
queues forever instead of failing — the worst outcome of the three,
because a queued job looks busy rather than broken.

Standard Actions semantics rather than a gitea quirk; the ambiguity was
in my prose. Documented where the label guidance already lives so the
next reader does not have to have been in the conversation.
This commit is contained in:
2026-09-02 09:26:19 -07:00
parent e5cbb5485b
commit 2575242e87
+12
View File
@@ -129,6 +129,18 @@ A workflow that runs on the central runner needs three things:
1. **`runs-on:`** matching a runner label — `pfi-fleet` (cross-fleet)
or `ana-docker` (pin to that host).
**A label LIST is AND, not fallback.** `runs-on: [vastblue, pfi-fleet]`
requires a runner carrying *both* labels — it does not try the first and
fall back to the second. A list naming a label no runner has matches
nothing and the job queues forever rather than failing, which is the worst
of the three outcomes because the board looks busy rather than broken.
Use **one** label, and when a workflow should move to a new runner, edit
the label deliberately at that moment. (Caught by eitri-smithy-dev on
2026-09-02 against vastblue's U1 contract, after infra-ops wrote "one-line
fallback to `pfi-fleet`" meaning a manual edit and was read as scheduler
behaviour. Standard Actions semantics, not a gitea quirk — the ambiguity
was in the prose, not the product.)
2. **An SSH key** to reach the deploy target. Stored as a repo or
org-level Actions secret named e.g. `DEPLOY_SSH_KEY`. The
corresponding public key must be in `~lkraven/.ssh/authorized_keys`