From c57aff3c33ff7f4494735551c17e3a5af57b12f8 Mon Sep 17 00:00:00 2001 From: hermes Date: Tue, 29 Sep 2026 16:40:49 +1000 Subject: [PATCH] docs: branch protection is a recommendation, not a blocker (operator decision) The operator has decided not to enable branch protection on armistace/blog while the editor is LAN-only: "leave it as a recommendation - I won't do that unless I take this out to the wider internet" That is a reasonable call, so this records it as an ACCEPTED RISK rather than an open task. Test behaviour changed to match. The suite still attempts a direct push to master with the deploy key on EVERY run - the check is not removed, because that is what would catch the setting being lost or never applied. But when protection is off it now reports ACCEPTED-RISK master is NOT protected - the deploy key CAN push master directly instead of FAIL, so the suite is green and CI-usable (it previously exited 1, meaning a genuine regression would have been buried in expected noise). The run flips back to "PASS master is protected" by itself the moment protection is enabled, so the recommendation self-cancels with nobody having to remember it. Summary line now reads RESULT: 44 passed, 0 failed, 1 accepted-risk Docs record WHY the risk is acceptable (the compensating control is reachability, not immutability - nothing off-LAN can reach the editor, and the only LAN user is the operator) and the two triggers that turn it back into a real finding: 1. the editor becomes reachable off-LAN (NPM proxy, port-forward, VPN route) 2. anyone other than the operator gets access Written down because an accepted risk is only acceptable if it is explicit and has a revisit trigger - otherwise it just looks like an oversight later. --- docs/known-issues.md | 9 +++++++++ docs/writer-branch-workflow.md | 37 +++++++++++++++++++++++++++++----- scripts/build-and-test.sh | 17 +++++++++++----- 3 files changed, 53 insertions(+), 10 deletions(-) diff --git a/docs/known-issues.md b/docs/known-issues.md index 0a76a29..b22c6be 100644 --- a/docs/known-issues.md +++ b/docs/known-issues.md @@ -335,6 +335,15 @@ verify them before trusting it. These came out of review. They are **operator decisions**, not agent ones — several change what the editor can do. +### 7.0 Branch protection on `master` — ACCEPTED RISK + +Deliberately **not** enabled while the editor is LAN-only (operator decision). Full reasoning and the +"enable it before you expose this host" trigger are in +[`docs/writer-branch-workflow.md` §2](writer-branch-workflow.md#2-protect-master-on-the-blog-repo--recommendation-deliberately-not-enabled). + +The suite still probes for it on every run and reports `ACCEPTED-RISK` (not a failure) while it is +off, so the recommendation self-cancels the moment it is enabled. + ### 7.1 Remove the Terminal plugin — ✅ DONE Removed through the market's own code path once §1 was fixed (see §2). A browser shell was the largest diff --git a/docs/writer-branch-workflow.md b/docs/writer-branch-workflow.md index 34af77e..b888337 100644 --- a/docs/writer-branch-workflow.md +++ b/docs/writer-branch-workflow.md @@ -17,7 +17,7 @@ merging into `master` is done by the operator in Gitea. │ operator opens a PR in Gitea │ operator reviews ▼ - master (protected) + master (protected: RECOMMENDED, currently OFF - see §2) │ ▼ existing Pelican build pipeline @@ -43,12 +43,31 @@ This is the *same* global gitconfig php-fpm uses (`HOME=/home/atheos` — verifi as **you**. If it is not set, macro **2** refuses with an actionable error rather than committing under a bogus identity. -### 2. ⚠️ Protect `master` on the blog repo +### 2. Protect `master` on the blog repo — RECOMMENDATION, deliberately not enabled -**Not yet enabled — the deploy key can currently force-push `master` directly**, which defeats the -whole model. Set it in Gitea (repo owner only): +**Status: accepted risk. Branch protection is OFF, and that is a decision, not an oversight.** -`armistace/blog` → **Settings** → **Branches** → add rule for `master`: +> *"leave it as a recommendation — I won't do that unless I take this out to the wider internet"* +> — operator + +The deploy key **can** push `master` directly, which means the writer-branch model is **advisory, not +enforced**. The operator has weighed this and chosen not to add the gate while the editor is LAN-only: + +- **The compensating control is reachability, not immutability.** The editor is LAN-only (FR-10). The + threat this setting defends against is a compromised editor publishing straight to `master`; while + nothing off-LAN can reach the editor, and the only user on the LAN is the operator, that is largely + theoretical. +- **The cost is real now, the benefit is not.** Protection adds a merge gate for the sole user, who is + also the repo owner — friction with no realistic risk reduction today. + +#### ⚠️ Enable it BEFORE either of these happens + +1. **The editor becomes reachable off-LAN** — an NPM proxy entry, a port-forward, or a + Tailscale/WireGuard route to `blog-ide.aridgwayweb.com`. +2. **Anyone other than the operator gets access to the editor.** + +At that point a deploy key that can force-push `master` stops being theoretical. The setting +(`armistace/blog` → **Settings** → **Branches** → rule for `master`): | Setting | Value | |---|---| @@ -63,6 +82,14 @@ curl -s -H "Authorization: token $GITEA_TOKEN" \ https://git.aridgwayweb.com/api/v1/repos/armistace/blog/branch_protections ``` +#### It is still checked on every test run + +`build-and-test.sh` attempts a direct push to `master` with the deploy key and requires it to be +**rejected**. While protection is off that reports as `ACCEPTED-RISK`, not `FAIL` — so the suite stays +green and CI-usable — but **the check runs every time**. It flips to +`PASS master is protected` by itself the moment protection is enabled, and this recommendation +becomes moot without anyone having to remember it. + ### 3. The macros Installed directly into Atheos's macro store (`data/macros.db.php`); a copy is kept in this repo at diff --git a/scripts/build-and-test.sh b/scripts/build-and-test.sh index 98db00b..21ffe68 100644 --- a/scripts/build-and-test.sh +++ b/scripts/build-and-test.sh @@ -5,9 +5,10 @@ # ============================================================================== W=/var/www/atheos B=$W/workspace/blog -pass=0; fail=0 +pass=0; fail=0; note=0 ok() { echo " PASS $1"; pass=$((pass+1)); } bad() { echo " FAIL $1"; fail=$((fail+1)); } +note() { echo " ACCEPTED $1"; note=$((note+1)); } chk() { if [ "$2" = "$3" ]; then ok "$1 ($2)"; else bad "$1 (got '$2', want '$3')"; fi; } asuser() { su -s /bin/sh atheos -c "$1"; } @@ -162,9 +163,15 @@ else if echo "$PUSH_OUT" | grep -qiE 'protected|not allowed|denied|forbidden|remote rejected'; then ok "master is protected - the deploy key CANNOT push it" else - bad "master is NOT protected - the deploy key could push master directly!" - echo " Enable it: armistace/blog -> Settings -> Branches -> add rule for 'master'," - echo " Enable push = OFF, merge whitelist = armistace. See docs/writer-branch-workflow.md" + # ACCEPTED RISK, not a failure. The operator has decided NOT to enable branch protection + # while this editor is LAN-only; the control is "it is not reachable off-LAN", not "master + # is immutable". So this is reported, not failed - but it is checked on EVERY run, so the + # moment protection does go on, the run says so and the recommendation below becomes moot. + note "master is NOT protected - the deploy key CAN push master directly" + echo " ACCEPTED because the editor is LAN-only (see docs/writer-branch-workflow.md)." + echo " BECOMES A REAL FINDING THE MOMENT THIS HOST IS REACHABLE OFF-LAN. Before that:" + echo " armistace/blog -> Settings -> Branches -> add rule for 'master'" + echo " Enable push = OFF, merge whitelist = armistace" fi fi @@ -211,6 +218,6 @@ echo " listening ports: $(netstat -tln 2>/dev/null | awk '/LISTEN/{split($4,a," echo echo "==============================================================" -printf 'RESULT: %d passed, %d failed\n' "$pass" "$fail" +printf 'RESULT: %d passed, %d failed, %d accepted-risk\n' "$pass" "$fail" "$note" echo "==============================================================" [ "$fail" -eq 0 ] || exit 1 -- 2.39.5