Skip to content

docs(security-config): soften aspirational MUSTs to align with init template#79

Merged
CybotTM merged 2 commits into
mainfrom
docs/soften-security-config-aspirational
May 23, 2026
Merged

docs(security-config): soften aspirational MUSTs to align with init template#79
CybotTM merged 2 commits into
mainfrom
docs/soften-security-config-aspirational

Conversation

@CybotTM
Copy link
Copy Markdown
Member

@CybotTM CybotTM commented May 23, 2026

Why

PR #77 shipped assets/branch-protection.json.template with two deliberate choices:

  • enforce_admins: false — solo-maintainer Netresearch repos benefit from admin-bypass in emergencies
  • required_signatures omitted — Dependabot/Renovate bot PRs without per-repo signing setup would otherwise be blocked

references/security-config.md was already in the repo with stricter language:

Line Old Conflict
~98 enforce_admins MUST be true Template ships false
~166 (table) `required_signatures true

Anyone 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_admins section: switched from "MUST be true" to "SHOULD be true on mature multi-maintainer repos as a hardening target". Added explicit acknowledgement that the init script ships false as the pragmatic baseline, plus the upgrade command + emergency-bypass rationale.
  • required_signatures table cell: now shows both states (target: true; init: unset) with the bot-signing precondition and per-repo upgrade trigger.
  • The under-enforce_admins security-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

Test plan

  • Markdown lint will run via CI on push
  • Word count check: wc -w skills/github-project/SKILL.md = 499 (no change; this PR only touches security-config.md)
  • CI green

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.

…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>
Copilot AI review requested due to automatic review settings May 23, 2026 07:17
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 23, 2026

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread skills/github-project/references/security-config.md Outdated
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_admins guidance from “MUST” to “SHOULD (hardening target)” and documented why the init baseline keeps admin-bypass enabled.
  • Updated the required_signatures table 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.

Comment thread skills/github-project/references/security-config.md Outdated
Comment thread skills/github-project/references/security-config.md Outdated
…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>
@CybotTM CybotTM merged commit 76a53cd into main May 23, 2026
20 of 21 checks passed
@CybotTM CybotTM deleted the docs/soften-security-config-aspirational branch May 23, 2026 08:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants