Skip to content

docs: template-based repo creation + Troubleshooting section - #6

Merged
Neil-Smithline merged 1 commit into
mainfrom
docs/repo-creation-and-troubleshooting
Sep 1, 2026
Merged

docs: template-based repo creation + Troubleshooting section#6
Neil-Smithline merged 1 commit into
mainfrom
docs/repo-creation-and-troubleshooting

Conversation

@Neil-Smithline

Copy link
Copy Markdown
Contributor

What

Updates docs/security-review-setup.md:

  1. Creating a new repo now recommends creating from the org template:

    gh repo create radius-workshop/<name> --template radius-workshop/repo-template --clone --private
    

    This seeds commit zero with README.md, CLAUDE.md, AGENTS.md, and
    GEMINI.md, so whichever agent a developer uses (Claude Code, Codex, Gemini)
    reads the same security-gate rules from the first commit. Those files are a
    reviewed baseline — they entered repo-template through a scanned PR. The
    bare --add-readme path is dropped and the commit-zero rationale updated to
    match.

  2. New Troubleshooting section documenting the failure modes we've hit:

    • org-wide scan outage → check the ruleset rules array (and history) first
    • a single PR unscanned/stale → re-trigger it
    • a check that shows but doesn't block → confirm the workflows rule
    • a new repo left empty after --template create → the require-workflows
      rule's do_not_enforce_on_create must be true
    • .github's own PRs are exempt from the scan (source-repo exemption)
    • all scan-behavior changes belong in this repo, never per-repo

Note

radius-workshop/.github PRs are exempt from the security scan (documented in
the new section), so this PR merges via the admin bypass rather than a green
Claude check.

Creating a new repo now leads with `gh repo create --template
radius-workshop/repo-template --clone`, which seeds commit zero with the
per-agent guidance files (README/CLAUDE/AGENTS/GEMINI) as a reviewed baseline;
the bare `--add-readme` path is dropped and the commit-zero explanation updated
to match.

Adds a Troubleshooting section covering the failure modes we've actually hit:
- org-wide scan outage -> check the ruleset `rules` array first, plus history
- one PR unscanned/stale -> re-trigger (push, reopen, @dependabot recreate)
- check present but merge not blocked -> confirm the `workflows` rule
- new repo empty after --template create -> do_not_enforce_on_create must be true
- .github's own PRs are exempt from the scan (source-repo exemption)
- all scan behavior changes belong in this repo, never per-repo

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@Neil-Smithline
Neil-Smithline merged commit 995250c into main Sep 1, 2026
3 checks passed
@Neil-Smithline
Neil-Smithline deleted the docs/repo-creation-and-troubleshooting branch September 1, 2026 16:18
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.

1 participant