Skip to content

Write down how a public repository is set up, ruleset first - #2

Merged
ftymoshchuk merged 1 commit into
mainfrom
claude/new-repository-docs
Sep 26, 2026
Merged

ftymoshchuk merged 1 commit into
mainfrom
claude/new-repository-docs

Conversation

@ftymoshchuk

Copy link
Copy Markdown
Member

What this changes

Aligning sigrix-mcp, mullion and postern took a set of gh commands that were worth keeping: they applied, changed and verified the branch ruleset across four repositories. They only existed in a conversation. This writes them down, so the next public repository starts from them rather than from memory.

  • docs/new-repository.md: the guide.
  • docs/default-branch.ruleset.json: the canonical ruleset, identical to what sigrix-mcp runs now.
  • README: a section pointing at both.

Why the ruleset gets most of the space

It's the one part of a repository's setup that no pull request reviews. Everything else is files, which go through PRs and get checked by CI. The ruleset lives in settings, and nothing notices when it drifts.

The guide says why each rule is set as it is. The approvals are the part that isn't obvious. A sole maintainer can't satisfy code-owner review, the unattributed-changes approval, or last-push approval. And every PR an agent opens is opened under that maintainer's account, so every one of them would be blocked. The guide also says to turn the first two back on once there's a second maintainer, since that's when they become the right rules.

What it covers

Section Contents
The branch ruleset Every rule, its setting, and why
Apply it to a new repository From a clone, or copied from a repo that already has it
Change an existing ruleset Look first, then fetch → change → preview → write back, with three example filters
Verify The four-repository check, with what healthy output looks like
When something is off Each symptom mapped to its cause
The rest of a new repository The files to copy, and from where

The "When something is off" table is the part most likely to save time. Every row is a symptom that actually came up: the classic-protection endpoint returning 404 for a repo protected by a ruleset, blocked with every check green, a POST stacking a second ruleset next to the first, a PUT silently dropping a rule, a heredoc mangled on paste.

Accuracy

  • The main commands (apply, look, change in place, verify, delete) are the ones used to align the four repositories.
  • The example filters were run over a copy of what the API returns. The check-swap filter's output is identical to postern's live ruleset.
  • I also removed a no-clone variant that had never actually been run, rather than document it.
  • The warning not to POST over an existing ruleset now comes before the POST commands. That ordering mistake is how mullion ended up with two rulesets.
  • Every relative link resolves, and the ruleset file is valid JSON.

Consumers

Documentation only. Neither action changes, so nothing pinned to v1.0.0 needs to move.


This is also the first ordinary PR through actions' corrected ruleset since the approval settings were fixed. Its commits are authored by an agent and it's opened under a maintainer's account, which is exactly the case that used to be blocked. It should reach clean once ci-passed is green.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WF6LAfT5nwL4wP9U9VmmAS


Generated by Claude Code

Aligning sigrix-mcp, mullion and postern took a set of `gh` commands
that were worth keeping: they applied, changed and verified the branch
ruleset on four repositories. They lived only in a conversation. The
next public repository should start from them rather than from memory.

The ruleset gets most of the space because it is the one part of a
repository's setup that no pull request reviews. It lives in settings;
nothing notices when it drifts. docs/default-branch.ruleset.json is the
canonical copy, identical to what sigrix-mcp runs, and
docs/new-repository.md says why each rule is set the way it is. The
non-obvious ones are the approvals: a sole maintainer can't satisfy
code-owner review, the unattributed-changes approval or last-push
approval, and every PR an agent opens is opened under that maintainer's
account.

The failure table is the part most likely to save time. Every row is a
symptom that was actually hit: the classic-protection endpoint answering
404 for a repository protected by a ruleset, `blocked` with every check
green, a POST stacking a second ruleset beside the first, a PUT quietly
dropping a rule, a heredoc mangled on paste.

The guide separates the commands that were run for real from the
example filters, which were only checked against a copy of what the API
returns. A no-clone variant that was never run was removed instead of
being documented. The warning not to POST over an existing ruleset now
comes before the POST commands. That ordering mistake is how mullion
ended up with two rulesets.

Documentation only: neither action changes, and consumers have nothing
to bump.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WF6LAfT5nwL4wP9U9VmmAS
@ftymoshchuk
ftymoshchuk merged commit c46a19a into main Sep 26, 2026
7 checks passed
@ftymoshchuk
ftymoshchuk deleted the claude/new-repository-docs branch September 26, 2026 16: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