Include main branch ruleset as part of the template

[d-morrison]

Adapted from d-morrison/rpt#134.

Summary

• Export the live main branch ruleset to .github/rulesets/main.json (server-assigned fields stripped so it round-trips through the create/update endpoints).
• New .github/scripts/apply-rulesets.sh idempotently applies every JSON in .github/rulesets/ to the current repo — PUT to update an existing ruleset by name, POST to create.
• New .github/rulesets/README.md documents what's enforced (required PR, no force-push / no deletion, copilot code review on push, Maintain-role PR-only bypass) and how to re-export after editing in the UI.
• README.Rmd / README.md: add a one-step entry under "Setup steps" pointing to the script.

Test plan

• Create a throwaway repo from the template and run .github/scripts/apply-rulesets.sh against it — verify the ruleset shows up under Settings → Rules → Rulesets.
• Re-run the script — confirm it updates in place rather than creating a duplicate.
• Edit a rule in .github/rulesets/main.json, run the script, confirm the change appears in the GitHub UI.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR packages the template repository’s default-branch protection ruleset into the template itself, along with tooling and documentation to apply and maintain it in newly created repos.

Changes:

• Adds an exported main branch ruleset JSON under .github/rulesets/ plus documentation for what it enforces and how to re-export it.
• Introduces .github/scripts/apply-rulesets.sh to idempotently create/update rulesets in a target repo via the GitHub API.
• Updates README.Rmd / README.md setup steps to instruct users to apply the ruleset.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.Rmd	Adds setup-step documentation for applying rulesets.
README.md	Adds setup-step documentation for applying rulesets.
.github/scripts/apply-rulesets.sh	New script to create/update rulesets from JSON definitions.
.github/rulesets/README.md	Documents ruleset behavior and re-export process.
.github/rulesets/main.json	Exported ruleset definition for the default branch.

[d-morrison]

@claude address review comments

[claude]

Claude finished @d-morrison's task in 2m 4s —— View job

---

Addressed Review Comments

• Read changed files to understand current state
• Fix pagination issue in .github/scripts/apply-rulesets.sh
• Fix step ordering in README.Rmd
• Fix step ordering in README.md
• Commit and push changes

Changes made

.github/scripts/apply-rulesets.sh — pagination fix

Added --paginate and piped through jq -s 'add // []' so all pages of rulesets are fetched before building the name→id map:

# Before
existing=$(gh api "repos/$repo/rulesets" --jq '[.[] | {name, id}]')

# After
existing=$(gh api --paginate "repos/$repo/rulesets" --jq '[.[] | {name, id}]' | jq -s 'add // []')

--paginate fetches every page (each emitting a JSON array); jq -s 'add // []' merges those arrays into one flat array that the downstream jq lookup can work with correctly.

README.Rmd / README.md — step ordering fix

Swapped steps 2 and 3 so users push their initial commit to main before applying the ruleset that blocks direct pushes:

• Step 2 → Push to main branch (initial commit)
• Step 3 → Apply branch rulesets (protects main after the seed content is in place)
  |

[d-morrison]

@claude fix failing workflows then iterate

[claude]

Claude finished @d-morrison's task in 3m 11s —— View job

---

Fixed Failing Workflows

• Gather context (CI status, changed files)
• Identify failing workflows
• Fix Spellcheck — added rulesets to inst/WORDLIST
• Fix Check Links — excluded quarto.org in lychee.toml (trusted docs site unreachable from CI runners due to network restrictions)
• Push changes

Cannot Fix — Workflow Permission Limitation

• Claude Code Review is failing because the workflow was triggered by claude[bot] (a bot), and the review action requires bots to be listed in allowed_bots. Fixing this requires editing a .github/workflows/ file, which GitHub App permissions do not allow me to modify.

  The error was:

  Workflow initiated by non-human actor: claude (type: Bot).
  Add bot to allowed_bots list or use '*' to allow all bots.
  

  To fix manually: edit the Claude Code Review workflow file and add allowed_bots: "claude[bot]" (or "*") to the action inputs. See the FAQ for more details.

---

Committed: fix: resolve spellcheck and link-checker CI failures → pushed to claude/include-branch-ruleset
|

[d-morrison]

@claude review, then revise, iteratively

[claude]

Claude finished @d-morrison's task in 3m 40s —— View job

---

Review & Revise

• Gather context and read changed files
• Review: .github/scripts/apply-rulesets.sh — pagination fix is correct; script logic is sound
• Review: .github/rulesets/main.json — well-formed, server-assigned fields stripped, ~DEFAULT_BRANCH targets correctly
• Review: .github/rulesets/README.md — fixed: added RULESET_ID discovery command
• Review: README.Rmd / README.md — fixed: project structure now includes rulesets/ and apply-rulesets.sh
• Review: inst/WORDLIST / lychee.toml — correct
• Commit and push (96dfd15)

---

Summary of changes

.github/rulesets/README.md — added a discovery command before the re-export snippet so users know how to find the RULESET_ID:

# Find your ruleset ID:
gh api repos/OWNER/REPO/rulesets --jq '[.[] | {name, id}]'

README.Rmd / README.md — updated the project structure tree to include the new files added by this PR:

└── .github/
    ├── rulesets/            # Branch ruleset definitions
    │   ├── main.json        # Default branch ruleset
    │   └── README.md        # Ruleset documentation
    ├── scripts/
    │   ├── apply-rulesets.sh    # Apply branch rulesets to a new repo
    │   └── ...

Notes from the review

• apply-rulesets.sh: The pagination logic (--paginate + jq -s 'add // []') is correct for single-page, multi-page, and zero-page cases.
• main.json: ~DEFAULT_BRANCH is the right target (adapts to any default branch name). bypass_actors role ID 2 is the Maintain role — correctly documented. required_approving_review_count: 0 is a reasonable template default; users can tighten this.
• lychee.toml: Excluding quarto.org means broken quarto.org links won't be detected by CI, but this appears necessary since the CI runners can't reach the site.
  | Branch

[d-morrison]

@claude review

[claude]

Claude finished @d-morrison's task in 1m 26s —— View job

---

Code Review

• Gather context
• Read changed files
• Analyze and provide review feedback

---

Overall this PR is well-implemented. The previous iterations already addressed the Copilot review comments (pagination, step ordering). Here's a full review of the current state:

.github/scripts/apply-rulesets.sh — looks good

The script is solid:

• Executable bit is set (100755) — correct.
• Pagination (--paginate + jq -s 'add // []') correctly handles zero, one, and multi-page results.
• set -euo pipefail — good defensive shell scripting.
• shopt -s nullglob — correctly handles the no-JSON-files case.
• jq -r ... // empty on line 29 correctly produces empty output (not null) when a ruleset isn't found, so the [ -n "$id" ] branch condition is reliable.

One minor nit: the header comment says "Run once after creating a new repo" but the script is idempotent and is designed to be re-run freely. Consider changing "once" to something like "after creating a new repo from this template, or whenever the ruleset definitions change."

Fix this →

.github/rulesets/main.json — one thing worth noting

The ruleset is well-formed. ~DEFAULT_BRANCH is the right target. Server-assigned fields are stripped.

required_approving_review_count: 0 — PRs can be merged with zero approvals. This is a reasonable minimal default for a template (users can tighten it), but it's worth calling out explicitly in the README so template users know to raise this if they want review gates. Currently the README doesn't mention it.

bypass_actors bypass_mode: "pull_request" — The README says "Maintainers can merge via a PR they authored", but bypass_mode: "pull_request" actually means the Maintain role can merge any PR while bypassing the ruleset requirements (e.g., even if required reviews aren't met). It's not limited to PRs they authored. The current description is slightly misleading — consider: "Maintain role can merge pull requests even when PR requirements are not otherwise satisfied." Fix this →

.github/rulesets/README.md — mostly good

The discovery command + re-export snippet is helpful and the jq del(...) fields match what GitHub actually returns. One suggestion: document that required_approving_review_count: 0 is intentional and adjustable, so template users don't assume they have review gates when they don't.

README.Rmd / README.md — correct

Step ordering is now right (push to main first, then apply rulesets), which was the core issue. The project structure tree now includes the new files. The (requires admin access) note on step 3 is a useful heads-up.

inst/WORDLIST / lychee.toml — correct

• rulesets added to spellcheck wordlist — appropriate.
• quarto.org excluded from link checker with an explanatory comment — pragmatic fix. Note that this means broken quarto.org links won't be caught by CI going forward. The comment is honest about the trade-off; acceptable.

---

Summary

The PR is ready to merge with one genuine correctness issue worth fixing before merge:

	Issue	Severity
main.json	required_approving_review_count: 0 is undocumented — template users may not realize PRs need zero reviews	Minor
.github/rulesets/README.md	bypass_mode: "pull_request" description is slightly misleading	Minor
.github/scripts/apply-rulesets.sh	"Run once" comment is misleading for an idempotent script	Nit
Branch

[claude]

Claude finished @d-morrison's task in 3m 6s —— View job

---

Code Review

• Gather context
• Read changed files
• Review .github/scripts/apply-rulesets.sh
• Review .github/rulesets/main.json
• Review .github/rulesets/README.md
• Review README.Rmd / README.md
• Review inst/WORDLIST / lychee.toml
• Post review summary

---

.github/scripts/apply-rulesets.sh — two open issues

Script logic is correct: set -euo pipefail, shopt -s nullglob, the --paginate | jq -s 'add // []' pipeline, and the // empty / [ -n "$id" ] update-vs-create branch are all sound.

Issue 1 (nit, open from previous review) — misleading comment on line 3:

# Run once after creating a new repo from this template. Idempotent: a

"Run once" contradicts "Idempotent." The script is explicitly designed to be re-run after editing ruleset definitions. Fix this →

---

.github/rulesets/main.json — looks good structurally

~DEFAULT_BRANCH targeting is correct. Server-assigned fields are stripped. enforcement: "active" is appropriate.

One design note: required_approving_review_count: 0 means PRs can be merged with zero approvals. The "Required PR before merging" rule only forces the existence of a PR, not any review of it. This is fine as a template default (easy to tighten), but it should be called out in the README so template users don't assume they have review gates. See README issue below.

---

.github/rulesets/README.md — two open issues

Issue 2 (minor, open from previous review) — incorrect bypass description on line 29:

Maintainers can merge via a PR they authored, but cannot push directly.

This is factually wrong. bypass_mode: "pull_request" means the Maintain role can merge any PR while bypassing the ruleset's requirements (e.g., merging without the required Copilot review or without approvals). It is not limited to PRs they authored. Fix this →

Issue 3 (minor, open from previous review) — required_approving_review_count: 0 undocumented:

The "What's enforced" section describes PR-required-before-merging but doesn't mention that zero approvals are needed. Template users may incorrectly assume they have review gates. Suggest adding a bullet like:

No mandatory approval by default — PRs require no approvals to merge (required_approving_review_count: 0); raise this under Settings → Rules → Rulesets if you want review gates.

Fix this →

---

README.Rmd / README.md — looks good

Step ordering is correct (push to main first, then apply rulesets). The (requires admin access) note is useful. Project structure tree correctly reflects the new files. README.md content is consistent with README.Rmd.

---

inst/WORDLIST — correct

Adding rulesets is appropriate.

---

lychee.toml — accepted trade-off, but note the scope

Excluding https://quarto.org/.* is broad: the template already contains ~7 distinct quarto.org links across README.md, index.qmd, chapters/chapter1.qmd, and README.Rmd. All of these are now exempt from link checking. The comment in the file is honest about the reason, and the exclusion appears necessary given CI network restrictions — but be aware that broken quarto.org links (e.g., docs pages that move) will no longer be caught automatically.

---

Summary

Three issues from the previous review are still open. Two are quick text fixes (issues 1 and 2). Issue 3 is a documentation gap worth filling before merge. Otherwise the implementation is solid.

	Issue	Severity
apply-rulesets.sh:3	"Run once" contradicts the script's idempotent design	Nit
rulesets/README.md:29	bypass_mode: "pull_request" description is factually incorrect	Minor
rulesets/README.md	required_approving_review_count: 0 not documented — template users may assume review gates exist	Minor
Branch

[d-morrison]

Claude Code CLI (local session) is working on this — paws off until I'm done.

[d-morrison]

@claude review again — addressed all three open items from the last review (apply-rulesets.sh comment, bypass_mode description, and the required_approving_review_count: 0 documentation gap).

[claude]

Claude finished @d-morrison's task in 57s —— View job

---

Code Review

• Gather context
• Read changed files
• Verify Issue 1: apply-rulesets.sh comment fix
• Verify Issue 2: bypass_mode description fix
• Verify Issue 3: required_approving_review_count: 0 documentation
• Full review pass

---

All three open items are addressed. Here's the verification and a final pass:

Issue 1 — apply-rulesets.sh:3: "Run once" ✅ Fixed

# Run after creating a new repo from this template, or after editing a
# ruleset definition. Idempotent: a ruleset whose `name` already exists …

"Run once" is gone; the comment now accurately reflects that the script should also be re-run after editing ruleset definitions.

Issue 2 — bypass_mode description ✅ Fixed

Maintainers can merge pull requests even when the ruleset's PR requirements
are not otherwise satisfied, but cannot push directly.

The previous "PRs they authored" framing (which was factually wrong) is replaced with the correct description of bypass_mode: "pull_request" semantics.

Issue 3 — required_approving_review_count: 0 ✅ Fixed

- **No mandatory approval by default** — PRs require no approvals to merge
  (`required_approving_review_count: 0`); raise this under Settings → Rules →
  Rulesets if you want a review gate.

Clear, prominent, actionable — exactly what template users need to know.

---

Remaining observations (no blocking issues)

apply-rulesets.sh — the script logic remains sound: set -euo pipefail, shopt -s nullglob, --paginate | jq -s 'add // []', and the // empty / [ -n "$id" ] branch are all correct. No issues.

main.json — well-formed, ~DEFAULT_BRANCH targeting is correct, server-assigned fields stripped. No issues.

README.Rmd / README.md — step ordering is correct (push to main first, then apply rulesets). README.md is consistent with README.Rmd. No issues.

inst/WORDLIST / lychee.toml — appropriate fixes. The broad quarto.org exclusion in lychee.toml is a known trade-off already called out in a previous review; the in-file comment is honest about the reason.

---

Summary

All three items from the previous review are resolved. The PR is ready to merge.
| Branch

[claude]

Claude finished @d-morrison's task in 1m 8s —— View job

---

Code Review

• Gather context
• Read changed files
• Verify fix 1: apply-rulesets.sh "Run once" comment
• Verify fix 2: bypass_mode description in rulesets/README.md
• Verify fix 3: required_approving_review_count: 0 documentation
• Full review pass

---

All three open issues are resolved. Here's the final pass:

apply-rulesets.sh — fix 1 ✅

Lines 3–4 now read:

# Run after creating a new repo from this template, or after editing a
# ruleset definition. Idempotent: a

"Run once" is gone. One cosmetic nit: Idempotent: a sits alone at the end of line 4 before continuing on line 5 (ruleset whose 'name' already exists…). It reads fine as a flowing paragraph-style comment; not worth fixing.

Script logic remains solid: set -euo pipefail, shopt -s nullglob, --paginate | jq -s 'add // []', and the // empty / [ -n "$id" ] update-vs-create branch are all correct.

rulesets/README.md — fixes 2 & 3 ✅

Bypass description (fix 2) — now reads:

Maintainers can merge pull requests even when the ruleset's PR requirements are not otherwise satisfied, but cannot push directly.

That's factually accurate for bypass_mode: "pull_request".

Zero-approval documentation (fix 3) — new bullet added:

No mandatory approval by default — PRs require no approvals to merge (required_approving_review_count: 0); raise this under Settings → Rules → Rulesets if you want a review gate.

Clear and actionable for template users.

main.json — unchanged, still correct

~DEFAULT_BRANCH targeting, enforcement: "active", server-assigned fields stripped. Nothing to flag.

README.Rmd / README.md — correct

Step ordering is right (push to main first at step 2, then apply rulesets at step 3). The (requires admin access) note is useful. README.md is consistent with README.Rmd. No _site/, _freeze/, or .quarto/ artifacts in the diff.

inst/WORDLIST / lychee.toml — correct

rulesets in the wordlist is appropriate. The quarto.org exclusion is broad (covers all quarto.org links already in the repo) but the inline comment is honest about the reason. Accepted trade-off.

---

This PR is ready to merge. No remaining issues.
| Branch

[claude]

Claude finished @d-morrison's task in 1m 6s —— View job

---

Code Review

• Gather context
• Read changed files and diff
• Review .github/scripts/apply-rulesets.sh
• Review .github/rulesets/main.json
• Review .github/rulesets/README.md
• Review README.Rmd / README.md
• Review inst/WORDLIST / lychee.toml
• Post review summary

---

All three items flagged in the previous review are now resolved. Here's the verification:

apply-rulesets.sh — Issue 1 ✅

Header comment now reads:

# Run after creating a new repo from this template, or after editing a
# ruleset definition. Idempotent: a ruleset whose `name` already exists on
# the repo is updated in place rather than duplicated.

"Run once" is gone. The description accurately reflects the script's idempotent design. Script logic (set -euo pipefail, shopt -s nullglob, --paginate | jq -s 'add // []', // empty / [ -n "$id" ]) is all correct.

rulesets/README.md — Issue 2 ✅

Bypass description now reads:

Maintainers can merge pull requests even when the ruleset's PR requirements are not otherwise satisfied, but cannot push directly.

Factually correct for bypass_mode: "pull_request".

rulesets/README.md — Issue 3 ✅

New bullet added to "What's enforced":

No mandatory approval by default — PRs require no approvals to merge (required_approving_review_count: 0); raise this under Settings → Rules → Rulesets if you want a review gate.

Clear and actionable for template users.

---

Remaining observations (no blocking issues)

main.json — well-formed, ~DEFAULT_BRANCH targeting is correct, server-assigned fields stripped, enforcement: "active". No issues.

README.Rmd / README.md — step ordering is correct (push to main at step 2, apply rulesets at step 3). Both files are consistent with each other. No _site/, _freeze/, or .quarto/ artifacts in the diff. No issues.

inst/WORDLIST — rulesets is appropriate. No issues.

lychee.toml — quarto.org exclusion is broad (covers all existing quarto.org links across README.md, index.qmd, etc.) but necessary given CI network restrictions; the inline comment is honest about the reason. Accepted trade-off.

---

This PR is ready to merge. No remaining issues.
| Branch

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-05-25 19:17 PDT