feat(repository): add CREATE_DEFAULT_BRANCH flag to create default branch instead of renaming

[decyjphr]

Why

Today, when repository.default_branch is configured and differs from the repo's current default branch, safe-settings renames the current default branch to the configured name. Renaming is disruptive for teams that want their default branch pointer to move to a brand new branch while keeping the original branch intact (for history, open PRs, tooling, or automation that still references it).

This adds an opt-in variation so operators can migrate a repo's default branch by creating the new branch rather than renaming the existing one.

What

Introduces a new environment feature flag CREATE_DEFAULT_BRANCH (default false). It only affects the path where the configured default_branch differs from the current one:

• Flag OFF (default): unchanged behavior. If the configured branch is missing, the current default branch is renamed.
• Flag ON + configured branch missing: creates a new branch off the current default branch's HEAD SHA (git.createRef) and promotes it to the default (repos.update). The existing default branch is left untouched (no rename).
• Flag ON + configured branch already exists: simply sets it as the default (no create, no rename).

How it fits together

The two missing-branch code paths in updateDefaultBranch now route through a small createOrRenameBranch() gate that dispatches on the flag. The new createDefaultBranch() method resolves the current default branch SHA, creates refs/heads/<newname>, then updates the repo's default branch, with full nop (dry-run) support that emits NopCommands for both the ref creation and the default-branch update.

Notes for reviewers

• Only the "configured branch does not exist" path changes. The "branch already exists" and flag-OFF paths preserve existing behavior.
• While adding tests I removed a stray it.only in test/unit/lib/plugins/repository.test.js that was silently suppressing the other tests in that file; those two tests now run again alongside the new suite.
• Documented in README.md (env var section) and docs/github-settings/1. repository-settings.md.

Testing

• Repository unit tests: 6/6 pass (covering flag OFF -> rename, flag ON + missing -> create + promote without rename, flag ON + exists -> set default only).
• Full unit suite: 316 passed, 12 skipped, 0 failures.
• standard lint clean on all changed files.

[Copilot]

Pull request overview

Adds an opt-in feature flag to change how repository.default_branch reconciliation works when the configured branch does not exist, allowing safe-settings to create the configured default branch (instead of renaming the current default branch) and then promote it to default.

Changes:

• Introduces CREATE_DEFAULT_BRANCH env flag and routes missing-branch reconciliation through a create-vs-rename gate.
• Implements createDefaultBranch() to create refs/heads/<new> from the current default branch HEAD SHA and update the repo default branch.
• Adds unit tests for the new branching behavior and documents the new env var in user docs.

Show a summary per file

File	Description
test/unit/lib/plugins/repository.test.js	Adds unit coverage for default-branch reconciliation under the new flag; removes stray it.only.
README.md	Documents the new CREATE_DEFAULT_BRANCH environment variable behavior and example usage.
lib/plugins/repository.js	Adds create-vs-rename dispatch and new createDefaultBranch() implementation.
lib/env.js	Exposes CREATE_DEFAULT_BRANCH env flag as a boolean.
docs/github-settings/1. repository-settings.md	Updates default_branch docs to describe the new flag behavior.

Review details

Tip

Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 5/5 changed files
• Comments generated: 2
• Review effort level: Lite

[decyjphr]

Good catch. Fixed in 59b9ad9: createDefaultBranch() now re-throws after logging, so a failed branch creation or default-branch update stops the sync flow (it no longer continues to updaterepo or reports success) and the failure is recorded via errorStash. Added a regression test asserting the method rejects and repos.update is not called on failure.

[decyjphr]

Fixed in 8f75cab: corrected the default_branch type label from boolean to string since it takes a branch name.

[Copilot]

Review details

Suppressed comments (1)

lib/plugins/repository.js:184

• CREATE_DEFAULT_BRANCH is intended (per PR description) to only change the behavior when the configured branch is missing (404). This hunk also routes the res.data.name !== newname case through createOrRenameBranch(). That case is explicitly documented as the "GitHub rename redirect" scenario where the ref doesn’t exist and the code needs to rename the branch back; attempting createDefaultBranch() here (when the flag is on) will likely fail with 422 Reference already exists and won’t restore the branch name as intended. Keep this path using renameBranch() regardless of the flag, and only gate the 404/missing-branch path.

      // If the old branch was renamed github will find the branch with the oldname the branch but the ref doesn't exist
      // So we'd have to rename it back to the oldname
      if (res.data.name !== newname) {
        return this.createOrRenameBranch(oldname, newname, resArray)
      } else {

• Files reviewed: 5/5 changed files
• Comments generated: 0 new
• Review effort level: Lite