Skip to content

fix(github): align the repo baseline ruleset with steward-default-branch - #1045

Merged
DevSecNinja merged 2 commits into
mainfrom
devsecninja-fix-steward-default-branch
Nov 14, 2026
Merged

DevSecNinja merged 2 commits into
mainfrom
devsecninja-fix-steward-default-branch

Conversation

@DevSecNinja

@DevSecNinja DevSecNinja commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Summary

The DotfilesHelpers baseline managed a default-branch ruleset named Default, but every repo now uses repo-steward's steward-default-branch. Running Set-GitHubRepoConfig -Category Ruleset would have created a second, competing ruleset with different rules. This aligns the baseline with repo-steward's policy/baseline.toml [protection]:

  • Name: Default → steward-default-branch, so the existing ruleset is updated in place.
  • Rules: deletion, non_fast_forward, required_linear_history, required_signatures. These are modelled as Rules and ForkRules lists that mirror required_rules and fork_rules in the TOML. Unsupported types are rejected.
  • Forks: keep only deletion and non_fast_forward, because GitHub's "Sync fork" pushes upstream commits that are neither signed nor linear. On a fork, linear history and signatures are reported as drift and removed when remediating.
  • Owner bypass: unchanged (RepositoryRole 5, always).
  • Add-only kept: only those four parameterless rules are managed. Status checks, Copilot review, code scanning and any other rule are carried over verbatim.

Behaviour change: pull_request is no longer managed here

repo-steward keeps PR-only in a separate steward-pull-request ruleset, so a repo can be exempted from that rule alone. The live steward-default-branch rulesets have no pull_request rule. Managing one here would make the two tools fight, so the baseline drops RequirePullRequest, RequiredApprovingReviews and AllowedMergeMethods. A pull_request rule found on the ruleset is now preserved like any other unmanaged rule, and is neither judged nor rewritten. Release-tag protection (steward-release-tags) is likewise documented as repo-steward's, rather than recognised here.

Breaking for -Baseline overrides: Ruleset keys RequirePullRequest, RequiredApprovingReviews, BlockDeletion, BlockForcePush and AllowedMergeMethods are gone; use Rules / ForkRules instead. The docs and examples are updated.

Docs

docs/github-repo-config.md now states that repo-steward is the reference and the two must stay in sync, explains the fork subset, and says PR-only and tag protection belong to repo-steward.

Relationship to #1043

This branches from main and is independent of #1043; the two touch different parts of the same files. A trial merge of both branches is conflict-free, and the full Pester suite passes on the merged result (994 passed).

Validation (local, on the owner's Windows machine)

  • Full Pester suite on this branch: 934 passed, 0 failed. New and updated tests cover the four rules, the fork subset (payload, audit drift and a Set POST), preserving pull_request verbatim, rejecting unsupported rule types, sending canonical lower-case rule types, and the rename.
  • PSScriptAnalyzer on the changed files: no findings.

Read-only audit: Get-GitHubRepoConfig -All -Check Ruleset

compliant: 15        (existing steward-default-branch rulesets match the aligned baseline exactly)
drift: 27            (all: ruleset_present False -> True; no steward-default-branch yet)
not evaluated: 21    (private repos; rulesets need GitHub Pro, skipped with a warning)

None of the 27 has a competing branch ruleset; ai-toolkit and note-iq have only steward-release-tags (tag), and entra-docs-pr has only push-protection (push). No Default ruleset remains on any repo. 10 of the 27 are forks, so they would get the fork rule set.

Dry run: ... | Set-GitHubRepoConfig -Category Ruleset -WhatIf

Nothing was written. Excerpt (27 lines, one per repo):

What if: Performing the operation "Create ruleset 'steward-default-branch' (ruleset_present: False -> True)" on target "DevSecNinja/note-iq".
What if: Performing the operation "Create ruleset 'steward-default-branch' (ruleset_present: False -> True)" on target "DevSecNinja/devsecninja-com".
What if: Performing the operation "Create ruleset 'steward-default-branch' (ruleset_present: False -> True)" on target "DevSecNinja/AgenticOdyssey".
...

Whether to create those 27 rulesets from here or let repo-steward do it is the owner's call; this PR only stops the two tools from diverging.

Closes #1044

Summary by CodeRabbit

  • New Features
    • The default branch ruleset now applies deletion protection, non-fast-forward prevention, linear history, and signed-commit requirements. Forks receive a reduced set of these rules.
    • Existing rules managed elsewhere are preserved, while rules outside the supported set are not applied by this configuration.
    • Ruleset checks no longer assess required approval counts or allowed merge methods.
  • Documentation
    • Updated guidance explains ruleset ownership, fork-specific behavior, enforcement, and administrator bypasses.

Rename the baseline default-branch ruleset from Default to
steward-default-branch, the one repo-steward manages, so remediation
updates it in place instead of creating a competing ruleset.

Mirror repo-steward's policy/baseline.toml [protection]: deletion,
non_fast_forward, required_linear_history and required_signatures, with
forks keeping only deletion and non_fast_forward, and the owner bypass
(RepositoryRole 5, always). PR-only (steward-pull-request) and release-tag
protection (steward-release-tags) stay with repo-steward, so pull_request
is no longer managed here; like status checks and Copilot review, it is
carried over untouched.

Closes #1044

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@coderabbitai

coderabbitai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The default-branch ruleset is now named steward-default-branch. Managed rules vary by fork status, and repository configuration auditing and remediation use the desired rules for that status. The documentation and tests reflect the updated ruleset and its preservation of unmanaged rules.

Changes: Steward ruleset alignment

Layer / File(s) Summary
Managed rule selection and payload generation
home/dot_config/powershell/modules/DotfilesHelpers/Public/GitHubRuleset.ps1, tests/powershell/GitHubRuleset.Tests.ps1, tests/powershell/Profile.Tests.ps1
Get-GitHubRulesetDesiredRule selects supported managed rules from Rules or ForkRules and returns canonical rule types. New-GitHubRulesetPayload replaces managed rules with parameterless desired rules, preserves other rules, and accepts fork status. Tests cover the payload rules, preserved rules, and helper visibility.
Repository configuration, auditing, and remediation
home/dot_config/powershell/modules/DotfilesHelpers/Public/GitHubRepoConfig.ps1, docs/github-repo-config.md, tests/powershell/GitHubRepoConfig.Tests.ps1, tests/powershell/GitHubApi.Tests.ps1, tests/powershell/GitHubCredentialPlacement.Tests.ps1, tests/powershell/OnePasswordCredential.Tests.ps1
The baseline uses steward-default-branch, with deletion, non_fast_forward, required_linear_history, and required_signatures for non-forks. Forks use only deletion and non_fast_forward. Auditing checks managed-rule presence against the desired set, and remediation passes fork status into payload generation. Documentation and tests cover the baseline, fork behavior, and preservation of unmanaged rules.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant Config as GitHubRepoConfig
  participant Desired as Get-GitHubRulesetDesiredRule
  participant Payload as New-GitHubRulesetPayload
  Config->>Desired: Resolve desired rules using fork status
  Desired-->>Config: Return canonical managed rule types
  Config->>Payload: Pass baseline, existing ruleset, and fork status
  Payload->>Desired: Resolve desired rules using fork status
  Desired-->>Payload: Return desired managed rule types
  Payload-->>Config: Return payload with desired managed rules and preserved other rules
Loading
Merge Risk: Minimal · up to 2c8a0

This change renames the baseline default-branch ruleset to steward-default-branch and aligns its managed rules with repo-steward. Forks manage only deletion and non-fast-forward. Existing pull-request and other unmanaged rules are left untouched. No concrete merge-blocking risk was found in the supplied changes.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: the repo baseline ruleset is aligned with the steward-default-branch name and rules. The summary covers the rename, the rule alignment, and the fork subset, so the tit…
Linked Issues check Passed Directly linked issue #1044 has these coding requirements. (1) Rename to steward-default-branch: GitHubRepoConfig.ps1 sets Ruleset.Name = 'steward-default-branch'. (2) Align rules with repo-steward [p…
Out of Scope Changes check Passed The changed areas map to #1044. The baseline (GitHubRepoConfig.ps1) and payload builder (GitHubRuleset.ps1) hold the rename, rule and fork changes. The new Get-GitHubRulesetDesiredRule helper rejects …
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Full details: Title check

Explanation

The title names the main change: the repo baseline ruleset is aligned with the steward-default-branch name and rules. The summary covers the rename, the rule alignment, and the fork subset, so the title matches the changeset. It uses the conventional fix(github) prefix and is 72 characters, within a typical single-line limit.

Full details: Linked Issues check

Explanation

Directly linked issue #1044 has these coding requirements. (1) Rename to steward-default-branch: GitHubRepoConfig.ps1 sets Ruleset.Name = 'steward-default-branch'. (2) Align rules with repo-steward [protection]: Rules = deletion, non_fast_forward, required_linear_history, required_signatures; ForkRules = deletion, non_fast_forward. Both are read in GitHubRuleset.ps1 through Get-GitHubRulesetDesiredRule. (3) Owner bypass RepositoryRole 5 with bypass_mode 'always': implemented in New-GitHubRulesetPayload using $script:GitHubRepositoryRoleAdmin = 5. (4) Add-only handling: New-GitHubRulesetPayload keeps every existing rule whose type is not in the managed set, so status checks, Copilot review and code scanning are carried over. (5) Docs and tests: the PR summary and the raw change summary report updates to docs/github-repo-config.md and to the Pester tests for the rename, rules, fork subset and preservation. I did not run the test suite. The tests are supported only by the PR summary and the change summary. (6) repo-steward as reference and sync note: stated in the Get-GitHubRepoBaseline comments and in the docs. Tag protection (#1044 optional item) is handled by documenting that repo-steward owns steward-release-tags, which the issue permits. The removal of pull_request management is not in the #1044 list. It follows from the issue's stated alignment with the TOML [protection] rule set. No unmet coding requirement is found.

Full details: Out of Scope Changes check

Explanation

The changed areas map to #1044. The baseline (GitHubRepoConfig.ps1) and payload builder (GitHubRuleset.ps1) hold the rename, rule and fork changes. The new Get-GitHubRulesetDesiredRule helper rejects unsupported rule types and returns canonical lower-case names, which supports the rule alignment. Get-GitHubRepoConfig ruleset audit now uses the same desired-rule calculation, so audit and remediation agree. Test fixture renames and the Profile.Tests.ps1 private-helper list entry are needed for the renamed ruleset and the new helper. The docs changes are the #1044 documentation item. The Ruleset override key changes (Rules/ForkRules replace RequirePullRequest, RequiredApprovingReviews, BlockDeletion, BlockForcePush and AllowedMergeMethods) follow from the rule alignment. The change summary lists no changes to Settings, Actions or AppCredential behavior. I found no change unrelated to the issue.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 01d996e4-e994-4df5-ac13-b019999adbca
Commits

Reviewing files that changed from the base of the PR and between a753075 and 2c8a04f.

Files selected for processing: 9

  • docs/github-repo-config.md
  • home/dot_config/powershell/modules/DotfilesHelpers/Public/GitHubRepoConfig.ps1
  • home/dot_config/powershell/modules/DotfilesHelpers/Public/GitHubRuleset.ps1
  • tests/powershell/GitHubApi.Tests.ps1
  • tests/powershell/GitHubCredentialPlacement.Tests.ps1
  • tests/powershell/GitHubRepoConfig.Tests.ps1
  • tests/powershell/GitHubRuleset.Tests.ps1
  • tests/powershell/OnePasswordCredential.Tests.ps1
  • tests/powershell/Profile.Tests.ps1

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Case-insensitive rule validation accepts uppercase values that are sent unchanged to GitHub, whose case-sensitive rule-type enum rejects them and causes creation or remediation to fail.

1 open issue
What changed in this PR

Aligns DotfilesHelpers’ default-branch protection with repo-steward, addressing #1044 by updating steward-default-branch rather than creating a competing ruleset.

Changes:

  • Replaces legacy ruleset options with Rules and ForkRules, applying reduced protection to forks.
  • Preserves unmanaged rules, including pull_request, while leaving PR-only and tag protection to repo-steward.
  • Updates documentation and tests for ruleset identity, drift detection, payloads, and fork remediation.
File Description
tests/​powershell/​Profile.Tests.ps1 Adds the desired-rule helper to module checks.
tests/​powershell/​OnePasswordCredential.Tests.ps1 Aligns ruleset fixtures with the new baseline.
tests/​powershell/​GitHubRuleset.Tests.ps1 Tests managed rules, fork payloads, validation, and preservation.
tests/​powershell/​GitHubRepoConfig.Tests.ps1 Updates baseline, drift, identity, and fork-remediation tests.
tests/​powershell/​GitHubCredentialPlacement.Tests.ps1 Aligns credential-placement fixtures with the baseline.
tests/​powershell/​GitHubApi.Tests.ps1 Updates API fixtures to use steward rules.
home/​dot_config/​powershell/​modules/​DotfilesHelpers/​Public/​GitHubRuleset.ps1 Selects and validates desired rules while preserving unmanaged rules.
home/​dot_config/​powershell/​modules/​DotfilesHelpers/​Public/​GitHubRepoConfig.ps1 Aligns baseline settings, drift detection, and fork-aware remediation.
docs/​github-repo-config.md Documents steward ownership, fork behavior, and replacement overrides.

Review effort: Balanced

Rule-type validation is case-insensitive, but GitHub's rule-type enum is not.
Return the canonical lower-case names so an override such as
'DELETION' no longer reaches the API as-is.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@DevSecNinja
DevSecNinja merged commit 16f747d into main Nov 14, 2026
20 checks passed
@DevSecNinja
DevSecNinja deleted the devsecninja-fix-steward-default-branch branch November 14, 2026 11:54
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.

fix(github): align the repo baseline ruleset with steward-default-branch

2 participants