docs(security-config): soften aspirational MUSTs to align with init template#79
Conversation
…emplate PR #77 shipped a branch-protection.json.template that sets `enforce_admins: false` and deliberately omits `required_signatures`, per the user-chosen pragmatic baseline for solo-maintainer Netresearch repos (snipe-it-docker-compose-stack, usercentrics-widgets, ldap-selfservice-password-changer, etc. all benefit from admin-bypass in emergencies; bot PRs from Dependabot/Renovate without per-repo signing setup would otherwise be blocked indefinitely). `references/security-config.md` claimed: - "enforce_admins MUST be true" (line 98) - "required_signatures | true" in the settings table (line 166) Both contradicted the new template. Anyone reading the skill now would see the contradiction as a bug, either "correct" per-repo (admin sperrt sich raus) or assume the template ignores the doc. Reframed: - `enforce_admins`: "SHOULD be true on mature multi-maintainer repos as a hardening target" + explicit "init script ships false as pragmatic baseline" + concrete upgrade command + emergency-bypass rationale. - `required_signatures`: table cell shows both states (target: true / init: unset) + bot-signing precondition + per-repo upgrade trigger. Plus the security-note callout under enforce_admins now points at the unresolved-threads memory rule as the operator-side safety valve when enforce_admins=false is the right per-repo choice. No template change in this PR; this is doc-only alignment with what PR #77 already shipped. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
There was a problem hiding this comment.
Code Review
This pull request updates the security configuration documentation to provide more pragmatic guidance on branch protection settings. It relaxes the enforce_admins requirement for solo-maintainer repositories and adjusts the required_signatures setting to avoid blocking automation bots during initial setup. The reviewer suggested using relative paths for internal documentation links instead of absolute URLs to ensure they remain functional across different branches.
There was a problem hiding this comment.
Pull request overview
This PR updates the security-config.md reference documentation to remove contradictions with the branch-protection init template introduced in PR #77 (notably enforce_admins: false and required_signatures being omitted), by reframing those settings as pragmatic defaults with an explicit hardening path.
Changes:
- Softened
enforce_adminsguidance from “MUST” to “SHOULD (hardening target)” and documented why the init baseline keeps admin-bypass enabled. - Updated the
required_signaturestable entry to distinguish between “target” vs “init” state and added context about bot-signing prerequisites.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…nces Three medium-priority threads on PR #79, all addressed: 1. (gemini) absolute github.com/blob/main URL → relative path `[the bootstrap reference](repo-bootstrap.md)`. Survives forks, offline renders, future branch renames. 2. (copilot) link text described "feedback memory" but linked at the bootstrap reference (which is the right page; the wrong claim was only in the link's display text). Rephrased the text to match what the reader will actually find on the linked page: "the pre-merge GraphQL query operators should run before every `gh pr merge`". 3. (copilot) `gh api PATCH` was ambiguous (no endpoint, no fields). Replaced with the concrete enablement command + verify command: `gh api repos/OWNER/REPO/branches/main/protection/required_signatures -X POST` plus the `.required_signatures.enabled` jq probe. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
Why
PR #77 shipped
assets/branch-protection.json.templatewith two deliberate choices:enforce_admins: false— solo-maintainer Netresearch repos benefit from admin-bypass in emergenciesrequired_signaturesomitted — Dependabot/Renovate bot PRs without per-repo signing setup would otherwise be blockedreferences/security-config.mdwas already in the repo with stricter language:enforce_adminsMUST betruefalseAnyone reading the skill now would see the contradiction as either a documentation bug or as license to "fix" their per-repo config (and admin-bypass themselves out of an emergency-merge path).
What changed
enforce_adminssection: switched from "MUST betrue" to "SHOULD betrueon mature multi-maintainer repos as a hardening target". Added explicit acknowledgement that the init script shipsfalseas the pragmatic baseline, plus the upgrade command + emergency-bypass rationale.required_signaturestable cell: now shows both states (target:true; init: unset) with the bot-signing precondition and per-repo upgrade trigger.enforce_adminssecurity-note callout now points at the unresolved-threads operator-side safety valve for repos where the admin-bypass IS the right choice.What did NOT change
branch-protection.json.templatestays as-is.Test plan
wc -w skills/github-project/SKILL.md= 499 (no change; this PR only touchessecurity-config.md)Pre-merge gate
I'll run the unresolved-threads GraphQL check before merging — the hard rule I just had to bake into memory after burning 3 PRs on the same mistake.