feat: add parameters for branch protection rule customization

[olzemal]

What

related to https://github.com/opendefensecloud/odd-internal/issues/44

• common.mk - the static REPO_RULESET json is replaced with a ruleset built at runtime via jq, driven by new make variables
• make repo-settings now prints the effective ruleset settings on each run.
• README.md / docs/NEW_REPO.md - documented the new variables.
• Default behavior is identical to before. All features are opt-in.

Checklist

• Tests added/updated
• No breaking changes (or upgrade path documented above)
• Readable commit history (squashed and cleaned up as desired)
• AI code review considered and comments resolved
• To actually improve the OpenSSF Score each project needs to:
  • Update dev-kit to a release of this feature
  • Add the new variables with values to the Makefile
  • Run make repo-settings again (requires Admin permissions).

Summary by CodeRabbit

• New Features

  • Added configurable merge strategies, including merge commits, squash merges, and rebase merges.
  • Expanded branch protection settings for approvals, code-owner reviews, branch freshness, status checks, administrator bypass, and target branch patterns.
  • Repository settings now synchronize labels, enable security scanning, and maintain workflow updates automatically.
  • Added validation for status-check configuration to help prevent invalid repository settings.

• Documentation

  • Updated setup documentation with available configuration options and examples for customizing repository settings.

[coderabbitai]

📝 Walkthrough

Walkthrough

Repository settings now use configurable Make variables and a downloaded repo-settings.sh script. The script validates configuration, reconciles GitHub settings and branch rulesets, and installs the versioned update-action-pins workflow. Documentation describes the available variables.

Changes

Branch protection configuration

Layer / File(s)	Summary
Configurable settings entrypoint common.mk, scripts/repo-settings.sh	common.mk defines merge and protection variables and passes them to the strict Bash settings script. The script authenticates with GitHub and validates status-check configuration.
Repository settings reconciliation scripts/repo-settings.sh	The script synchronizes labels, merge settings, branch deletion, secret scanning, the protect-main ruleset, and the versioned update-action-pins workflow.
Configuration documentation README.md, docs/NEW_REPO.md	Documentation describes merge options, protection variables, status checks, branch freshness, administrator bypass, and protected branch patterns.

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

Sequence Diagram(s)

sequenceDiagram
  participant MakeRepoSettings
  participant RepoSettingsScript
  participant GitHub
  participant WorkflowRepository
  MakeRepoSettings->>RepoSettingsScript: Pass REPO_* variables and tool settings
  RepoSettingsScript->>GitHub: Authenticate and reconcile repository settings
  RepoSettingsScript->>GitHub: Update or create protect-main ruleset
  RepoSettingsScript->>WorkflowRepository: Download update-action-pins workflow

Loading

Possibly related PRs

• opendefensecloud/dev-kit#22: Earlier changes to repo-settings merge-strategy configuration are extended by this pull request.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the changes and checklist, but it omits the required Why, Testing, and Notes for reviewers sections.	Add Why, Testing, and Notes for reviewers sections, and describe the tests performed.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the main change: adding configurable branch protection parameters.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/644-advanced-branch-protection-rules

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@common.mk`:
- Line 117: Update the generated ruleset summary echo in the relevant make
target to print the generated branch targets from RULESET_JSON’s
conditions.ref_name.include field instead of relying only on
REPO_RULESET_BRANCHES, so the default ~DEFAULT_BRANCH is shown even when the
variable is empty.
- Around line 121-127: The required status-check input handling in common.mk
must preserve spaces within individual context names instead of splitting
REPO_STATUS_CHECKS on whitespace; switch to an array-valued input or equivalent
lossless encoding and update the corresponding README.md description to document
the new format.
- Around line 144-148: Update common.mk around the ruleset generation to reject
REPO_REQUIRE_BRANCH_UP_TO_DATE=true when REPO_STATUS_CHECKS is empty, failing
before generating a ruleset without required_status_checks; alternatively,
update README.md line 114 to explicitly state that branch freshness requires at
least one REPO_STATUS_CHECKS value. Apply the chosen behavior consistently at
common.mk lines 144-148 and README.md line 114.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 88ad4943-7d3a-46d8-8247-028b9be2b4f4

📥 Commits

Reviewing files that changed from the base of the PR and between d7e7744 and 424af78.

📒 Files selected for processing (3)

• README.md
• common.mk
• docs/NEW_REPO.md

[olzemal]

@coderabbitai review

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cbrgm]

Two things before merge:

1. $(RULESET_JSON) vs $$RULESET_JSON slip in the two gh api calls (inline below). It ships an empty body to the API, so the target doesn't actually create or update the ruleset
2. The recipe is now ~40 lines of shell + jq inlined in the Makefile, every line escaped with \ and $$. The shellcheck target only lints git ls-files '*.sh', so none of this shell is covered. Wdyt about moving the body into hack/repo-settings.sh and passing the REPO_* values as env? shellcheck picks it up for free, the jq program can live in a jq -f file without the escaping.. Doesn't need to be this PR, i can sketch it if useful.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/repo-settings.sh`:
- Around line 34-35: Normalize REPO_STATUS_CHECKS once to a list containing only
non-empty string contexts, then use that normalized value for validation,
required-status-check ruleset creation, and reporting. In the
REPO_REQUIRE_BRANCH_UP_TO_DATE guard, reject an empty normalized list, and
update the logic around the required-status-checks installation and output to
reuse the same effective list so logs cannot describe unapplied checks.
- Around line 29-32: Update the repository selection logic in
scripts/repo-settings.sh to preserve and use an explicitly configured REPO
value, only resolving the current GitHub repository when REPO is unset. Also
update common.mk to forward REPO when invoking this script, ensuring
REPO=owner/name targets the requested repository.
- Around line 139-141: Update the workflow download in scripts/repo-settings.sh
to first write to a temporary file within .github/workflows, then atomically
move that file to .github/workflows/update-action-pins.yml only after curl
succeeds. Ensure failed or interrupted downloads do not replace or truncate the
existing workflow.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a9670ec6-588b-4539-919e-ef017e49883f

📥 Commits

Reviewing files that changed from the base of the PR and between d7e7744 and d6fe687.

📒 Files selected for processing (4)

• README.md
• common.mk
• docs/NEW_REPO.md
• scripts/repo-settings.sh

🚧 Files skipped from review as they are similar to previous changes (3)

• README.md
• common.mk
• docs/NEW_REPO.md

[olzemal]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.