docs: correct new-repo section (bootstrapping is not automatic) - #4
Merged
Conversation
The "Adding a new repo" section claimed new repos are "protected as soon as they're created." That is false and actively dangerous: a brand-new empty repo's first commit cannot go through a PR (no base branch exists), and pushing code then renaming/repointing a side branch onto the default lands unscanned code on a protected branch while the ruleset still reports all rules active. Replace it with explicit guidance: create repos with --add-readme so the default branch exists and is protected from commit zero, do real work via PRs, and treat a GH013 rejection as stop-and-report rather than something to route around — for humans and AI coding agents alike. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Reviewer point: "a rejected push is never an obstacle to engineer around" was too blunt — it could read as discouraging the legitimate recovery (move changes to a branch, push, open a PR), which is the intended workflow, not a workaround. Split the guidance in two: (1) a rejected push to an existing default branch just means "open a PR instead" — that works and is sanctioned; the bypass is specifically landing code on the default WITHOUT a scanned PR (rename onto default, repoint default, admin bypass). (2) commit zero in a brand-new empty repo is the one case branch-and-PR cannot cover (no base branch to target), which is why repos must be created with --add-readme. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Clarify the importance of using a scanned PR to avoid bypassing security checks on the default branch.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
docs/security-review-setup.mdtold readers, under Adding a new repo, that new repos are "protected as soon as they're created." That is false, and it is the exact false belief that lets unscanned code reach a protected default branch.A brand-new empty repo has no default branch yet, so its first commit cannot go through a PR (a PR needs an existing base). Pushing code to an empty repo and then renaming a side branch onto the default — or repointing the default branch, or an admin bypass — lands unscanned code on a protected branch while the ruleset still reports all rules active. The repo looks governed; its initial code never was.
What changes
Docs only. Replaces the "Adding a new repo: Nothing" section with a "Creating a new repo" section that:
gh repo create --add-readme(or the UI "Add a README") so the default branch exists and is protected from commit zeroGH013 ... Required workflow ... is not satisfiedrejection is the gate working as intended — stop and report, don't route around — for humans and AI coding agents (Claude Code, Codex, Gemini, …) alikeNote
This PR is itself a live test of the gate on a docs-only change: it should scan clean and be mergeable once
Claude Security Review (required)passes.🤖 Generated with Claude Code