Rename default branch from master to main #938

Completed the native default-branch rename from master to protected main and verified the cutover. Source preparation and community PR #1680 are merged. This issue is closed as completed.

Verified results:

• The renamed tip was 9496b27465c07828cfd68b48425a51288f63c42d; the native operation preserved it, and the old master ref is absent.
• All 0 existing tags and every unrelated branch retained their original object SHAs during cutover. Protections/rulesets, GitHub-visible hook configurations and workflow state are preserved.
• Fresh clones select main, with origin/HEAD pointing at origin/main. Existing PRs retargeted to main with unchanged heads.
• Actual deployed Git resource checks passed. Isolated public-source check/get build 398015664 succeeded at the renamed tips; that source-only probe skipped LFS/submodules, with production fetch settings preserved. Path-filtered deployed versions were verified to be the main tip or a valid ancestor.
• Repository/counter/publication writers were coordinated, with no active writer builds during renaming. Counter state stayed unchanged throughout paused verification. Every original job and pipeline pause state was restored, including originally paused jobs.

The deployed docs Git source follows the renamed default branch. The published init-azure, init-vsphere, jobs and update-disk pages show the expected main links; their documentation edit URLs use main. The published BPM configuration page maps its edit link to bpm-release/edit/main/docs/config.md. Publication was already successful; no publication was triggered solely for validation.

Only the required deployed Git branch selectors were updated; other live job/configuration fields were preserved. The merged community configuration specifies default_branch: main.

Documentation/comment-only follow-ups may merge independently and do not gate this completed repository/pipeline migration.

Peribolos synchronization remains asynchronous. No individual run is a checklist gate; an eventual successful synchronization containing the merged community configuration is still needed before org configuration is fully applied.

The original migration plan and review links below are retained for reference.

Related PRs:

• Source preparation: Prepare docs-bosh for the main default branch #937
• Shared community configuration: Set eight BOSH subgroup default branches to main community#1680 (draft until all eight cutovers are verified)

Documentation/comment follow-ups:

• Update source comments for the main branch rename bosh-gdc-cpi-release#18

Scope:

Update publication guidance, MkDocs edit links and both sides of the BPM edit-link mapping. Update maintained links for the accompanying Azure CPI, Google CPI, vSphere CPI and BPM migrations. The deployed documentation Git source already follows the default branch.

Merge/promotion order:

The deployed Git source follows the default branch. This preparation PR can remain open through native rename and auto-retarget to main. Merge after Azure CPI, Google CPI, vSphere CPI and BPM have main; verify the resulting publication and edit URLs. This avoids publishing new links before their targets exist.

Repository/counter writers identified in the checked-in pipeline:

• No source-repository/counter writer was found in this repository; coordinate and drain any in-progress publication.

Re-audit the live job graph before cutover; a job named test-unit can still write refs or advance counters. Preserve any existing version/counter state, release tags, artifact/image identities, unrelated branch refs and all existing counter state. The org-wide source audit found only documentation/comment follow-ups in other repositories for this migration; refresh active consumers and maintained branches during cutover preflight. Do not create migration PRs against feature/PR branches or modify their heads.

Cutover steps:

1. Follow the merge/promotion order above. Refresh the source/consumer audit. Capture current default tip, every branch and tag object SHA (including annotated tag objects), protections/rulesets, all open PR bases/heads, workflows/integrations, version/counter state, and deployed pipeline configuration and exact job/pipeline pause settings.
2. Coordinate all active consumers. Pause the affected pipeline and repository/counter/publisher writers, and drain already-started writer builds. Pausing alone does not stop running builds. For documentation publication, coordinate the current publication job and let any in-progress publication finish. Preserve the original pause states for restoration.
3. Run gh api --hostname github.com --method POST repos/cloudfoundry/docs-bosh/branches/master/rename -f new_name=main. Poll until GitHub reports protected default main and no master ref; the native operation can settle asynchronously. Confirm the renamed tip and every unrelated ref/tag object match the snapshot.
4. No Git branch selector edit is required in the publication pipeline. Recheck/fetch the existing default-following docs source after rename. After merging the retargeted documentation PR, verify it fetches that commit and the published page/edit links use main, including the BPM mapping.
5. Read back actual deployed configuration and run read-only checks/fetches of every affected Git source. Verify fetched versions belong to main; path-filtered resources may correctly select an older ancestor when the preparation changes only CI files. Preserve production LFS behavior; source-only clone/probe checks may skip LFS downloads. Do not create a release, tag, image publication or version bump merely to validate the rename.
6. Verify a fresh clone selects main with origin/HEAD at origin/main; use GIT_LFS_SKIP_SMUDGE=1 for source-only checks where needed. Compare every other branch/tag object, protections/rulesets, existing PR bases and unchanged heads, workflow/integration settings and counter state. Update branch selectors for any active external publisher/integration that actually has one. Verify relevant documentation/edit links after their target branches exist.
7. Restore each job and pipeline to its captured pause state, leaving originally paused jobs paused. Record evidence here. Merged source preparation alone is insufficient to close this issue. After all eight selected migrations are verified, mark the shared community PR ready for review and merge.

Documentation/comment-only follow-ups do not block native renaming. Merge them with or after their corresponding target renames. The docs-bosh edit-link/publication ordering above is part of final website verification.

Completed preparation validation: parsed MkDocs edit URI and BPM mapping checks pass; git diff --check passes. No website publication is triggered for validation.

Peribolos synchronization is asynchronous and individual runs can be canceled by later merges. Do not wait for a particular run as a checklist gate. An eventual successful synchronization containing the merged community configuration is still required before org configuration is fully applied.

Rollback: pause/drain writers, natively rename main back to master, restore the captured pipeline branch settings, verify sources and original version state, then restore original pause settings. Coordinate reverting the community default if merged. Keep tags, counters, unrelated branches and artifacts intact; do not create a divergent compatibility branch. For utilities, retain develop and its tested preparation history while restoring only the promoted branch setting. For documentation, coordinate the edit-URI/mapping reversal with publication.