docs: add branch-protection runbook from src/zsh-eza audit findings by ss-o · Pull Request #477 · z-shell/.github

ss-o · 2026-07-24T08:40:04Z

Closes #476. Impact review (per runbooks/instruction-update.md) is in that issue.

Summary

Adds runbooks/branch-protection.md: the checklist for provisioning and auditing repository settings/rulesets on next -> main repos, written from an audit of z-shell/src and z-shell/zsh-eza that found the same three gaps in both independently (missing renovate.json baseBranches, no guard against direct-to-main PRs, delete_branch_on_merge deleting the next branch itself after a promotion merge).
Cross-links from runbooks/dependency-management.md, runbooks/new-repository.md, and ADR-0008's Consequences/References.
Registers runbook-branch-protection in .github/instruction-surfaces.json.

Opened as a draft: this documents a real incident and its fix, but the runbook content and the manifest route are a maintainer call, not something I should land unilaterally.

Test plan

python3 scripts/validate-agent-policy.py -- passes
python3 -m unittest scripts/test_validate_agent_policy.py -v -- 68 tests pass
trunk check on all changed files -- no issues

Adds runbooks/branch-protection.md, the checklist for provisioning and auditing repository settings and rulesets on next -> main repositories (decisions/0008-branching-model.md). Written from an audit of z-shell/src and z-shell/zsh-eza that found the same three gaps in both, independently: renovate.json missing baseBranches (Renovate bypassing next), no required check blocking direct-to-main PRs, and delete_branch_on_merge deleting the next branch itself after a promotion merge -- the ruleset deletion rule did not stop it under an admin bypass. Cross-links from dependency-management.md, new-repository.md, and ADR-0008's Consequences/References. Registers runbook-branch-protection in .github/instruction-surfaces.json. Closes #476

Copilot

Pull request overview

Adds a new operational runbook to standardize how next → main repositories are provisioned and audited (rulesets + repo settings + automation defaults), based on real audit findings, and wires it into the routed instruction surfaces so it’s consistently applied during bootstrap and branch-protection tasks.

Changes:

Add runbooks/branch-protection.md checklist covering rulesets, repo settings (delete_branch_on_merge), and automation configuration (Renovate baseBranches, main-branch guard check).
Cross-link the new runbook from runbooks/new-repository.md, runbooks/dependency-management.md, and ADR-0008 (decisions/0008-branching-model.md).
Register the runbook as a required routed surface via .github/instruction-surfaces.json (runbook-branch-protection).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
runbooks/new-repository.md	Adds explicit guidance to apply the branch-protection runbook for `next` → `main` repos during bootstrap.
runbooks/dependency-management.md	Clarifies Renovate `baseBranches` is mandatory for `next` → `main` repos and links to the runbook.
runbooks/branch-protection.md	New runbook documenting the audit/provisioning checklist and incident learnings.
decisions/0008-branching-model.md	Adds references tying the ADR policy to the enforcement/provisioning runbook.
.github/instruction-surfaces.json	Routes the new runbook as required for relevant tasks/consumers.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Sal <59910950+ss-o@users.noreply.github.com>

Copilot

Pull request overview

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

Comments suppressed due to low confidence (4)

runbooks/new-repository.md:129

Same terminology consistency issue here: this section uses next -> main, while ADR-0008 and other guidance typically use next → main. Aligning to → makes this easier to grep and reduces ambiguity.

If this repository uses the `next` -> `main` model
(`decisions/0008-branching-model.md`), follow `runbooks/branch-protection.md`
in full before opening the bootstrap pull request. Trunk-on-`main`
repositories still need a `main` ruleset, but can skip the `next`-specific
items (the guard workflow, `renovate.json` override).

runbooks/branch-protection.md:38

For consistency with ADR-0008 and other docs in this repo, use next → main (Unicode arrow) rather than next -> main here. This keeps terminology consistent and improves searchability.

Run every item below for a repository whose `decisions/0008-branching-model.md`
row is `next` -> `main`. Skip repositories that are trunk-on-`main`.

runbooks/branch-protection.md:43

Same terminology consistency issue: next -> main is inconsistent with ADR-0008’s next → main wording. Using the same arrow symbol here makes searches and cross-references more reliable.

      `gh api repos/<org>/<repo> --jq .delete_branch_on_merge`. If `true`,
      any PR that uses `next` as its head branch (i.e. every `next` -> `main`
      promotion) risks GitHub deleting `next` right after merge, regardless of

runbooks/branch-protection.md:76

This line uses next -> main, but ADR-0008 and related docs use next → main. Aligning on → keeps terminology consistent across the documentation set.

When squash-merging a `next` -> `main` promotion PR without an explicit

Copilot flagged 8 spots using ASCII -> instead of the Unicode -> already used by ADR-0008 and the rest of the runbook set.

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Copilot review: AGENTS.md only disallows Co-authored-by; there is no blanket no-trailer policy and Signed-off-by is not itself prohibited.

Copilot

Pull request overview

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

…tion-runbook # Conflicts: # decisions/0008-branching-model.md

Copilot

Pull request overview

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

Copilot AI review requested due to automatic review settings July 24, 2026 08:40

Copilot started reviewing on behalf of ss-o July 24, 2026 08:40 View session

Copilot AI reviewed Jul 24, 2026

View reviewed changes

Comment thread runbooks/branch-protection.md Outdated

ss-o marked this pull request as ready for review July 24, 2026 22:02

ss-o requested a review from a team as a code owner July 24, 2026 22:02

Apply suggestions from code review

a0e7dbf

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Sal <59910950+ss-o@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 24, 2026 22:04

Copilot started reviewing on behalf of ss-o July 24, 2026 22:05 View session

Copilot AI reviewed Jul 24, 2026

View reviewed changes

Comment thread runbooks/new-repository.md

Comment thread runbooks/dependency-management.md Outdated

Comment thread runbooks/branch-protection.md Outdated

docs(runbooks): use consistent next -> main arrow glyph

8d31295

Copilot flagged 8 spots using ASCII -> instead of the Unicode -> already used by ADR-0008 and the rest of the runbook set.

Copilot AI review requested due to automatic review settings July 24, 2026 22:48

Copilot started reviewing on behalf of ss-o July 24, 2026 22:48 View session

Copilot AI reviewed Jul 24, 2026

View reviewed changes

Comment thread runbooks/branch-protection.md

docs(runbooks): scope the trailer warning to the actual policy

74715cd

Copilot review: AGENTS.md only disallows Co-authored-by; there is no blanket no-trailer policy and Signed-off-by is not itself prohibited.

Copilot AI review requested due to automatic review settings July 24, 2026 23:13

Copilot started reviewing on behalf of ss-o July 24, 2026 23:13 View session

Copilot AI reviewed Jul 24, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into feature-branch-protec…

c08cdb9

…tion-runbook # Conflicts: # decisions/0008-branching-model.md

Copilot AI review requested due to automatic review settings July 25, 2026 01:55

Copilot started reviewing on behalf of ss-o July 25, 2026 01:55 View session

Copilot AI reviewed Jul 25, 2026

View reviewed changes

ss-o merged commit da0b007 into main Jul 25, 2026
7 checks passed

ss-o deleted the feature-branch-protection-runbook branch July 25, 2026 02:02

Navigation Menu

Uh oh!

docs: add branch-protection runbook from src/zsh-eza audit findings - #477

docs: add branch-protection runbook from src/zsh-eza audit findings#477
ss-o merged 5 commits into
mainfrom
feature-branch-protection-runbook

ss-o commented Jul 24, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ss-o commented Jul 24, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants