BitBucket_to_Github_migration.pdf

Transcript

1. Bitbucket to GitHub Migration Dos, Don’ts, Rulesets, and Survival Tips Yunus Kaya | 2026
2. Agenda 1 Why migration is more than moving code 2 Repository cleanup and branch review 3 Security checks before migration 4 GitHub target settings and validation tools 5 Branch naming and commit policies 6 Pull request governance and exceptions 7 Post-migration pitfalls and next steps
3. Introduction Migration Is a Quality Gate • Migration is not just moving code from A to B • It is a chance to: • clean repositories • remove technical junk • validate naming and mapping • apply GitHub policies • improve security controls • standardize workflows Raiffeisen Software | Migration from Bitbucket to GitHub
4. Preparation Pre-Migration Cleanup • Check repositories for unnecessary or problematic files • files larger than 100 MB • build artifacts • generated files • obsolete content • missing .gitignore entries • Use Git LFS for valid large binaries or remove them • Use BFG Repo Cleaner if large files exist in Git history Raiffeisen Software | Migration from Bitbucket to GitHub
5. Preparation Pre-Migration Cleanup Step 1 — Mirror clone Create a fresh bare mirror of the repository Make a backup before rewriting history Step 2 — Run BFG Strip blobs larger than 100 MB BFG rewrites commits, branches, and tags Step 3 — Clean Git data Expire reflog Run garbage collection Step 4 — Push cleaned history Push the updated mirror back to the remote Step 5 — Re-clone Delete old local clones Create fresh clones for all users Raiffeisen Software | Migration from Bitbucket to GitHub
6. Preparation Branch Cleanup Before Migration • Delete branches that are no longer needed • Avoid carrying branch clutter into GitHub • Migrate only the current default branch and active branches Raiffeisen Software | Migration from Bitbucket to GitHub
7. Governance Branch Naming Policy • Allowed names: main, develop, development, feature/*, release/*, hotfix/*, bugfix/*, support/* • Jira issue key required for most non-base branches • Everything lowercase except the Jira issue key • No special characters • Examples: feature/PTMFTECH-123, hotfix/PTWPTECH-9999-urgent-crash-fix, release/1.2.3 Raiffeisen Software | Migration from Bitbucket to GitHub
8. Preparation Repository Mapping and Naming • Validate repository name mapping carefully • Repositories not to be migrated must be removed from the mapping file Raiffeisen Software | Migration from Bitbucket to GitHub
9. SecurityGI Security Check Before Migration • Every repository must be checked for vulnerabilities before migration • Run the DCRYPD GitHub Action • Security check for existing credentials • If cleanup is not possible, align with Security • The process creates an HTML report and a Jira ticket • The Jira ticket must be closed before migration Raiffeisen Software | Migration from Bitbucket to GitHub
10. Git To Rebase or not to Rebase? No More Train Stations • We prefer rebase to avoid noisy merge histories • Merge commits often create a Git graph that looks like a train station • This makes history harder to read, review, and debug • Rebase helps keep the history: • cleaner • more linear • easier to understand • easier to audit • makes harder to reuse branches Raiffeisen Software | Migration from Bitbucket to GitHub
11. Governance Commit Message Policy • Commit messages must include a Jira issue key • Format: ABC-123: commit message • Conventional commit example: feat(api): ABC123: add new endpoint • Malformed, lowercase, or missing Jira keys are not allowed Raiffeisen Software | Migration from Bitbucket to GitHub
12. Governance Teams and Access Governance • Direct access only through teams • Read role: teamname-read • Write role: teamname-write • Admin role: teamname-admin • This improves audits, consistency, onboarding, and offboarding Raiffeisen Software | Migration from Bitbucket to GitHub
13. Governance Pull Request Governance and Exceptions • PRs merged into main require the four-eyes principle • Exceptions must be managed centrally by Security, not by repository admins. • Exception flow: ticket → Security review → GitHub admin change → documented reason Raiffeisen Software | Migration from Bitbucket to GitHub
14. After Migration Feature Branch Trap After Migration • Only main and release branches are actively updated • Feature branches are not automatically synchronized • Old feature branches may contain outdated build folders and Jenkinsfiles • Correct fix: copy the build folder from main and replace it in the feature branch • Do not merge main into the old feature branch Raiffeisen Software | Migration from Bitbucket to GitHub
15. Summary Final Dos and Don’ts DO DON’T • Do: clean repositories, remove dead branches, validate mapping, run security scans • Do: apply rulesets, use team-based access, follow naming and commit policies • Do: Enforce the rulesets as far as possible • Don’t: underestimate the need for project coordination alongside technical work • Don’t: treat migration as a purely technical task — coordination, tracking, and ownership are essential (someone still must keep the chaos on a leash) • Don’t: allow exceptions unless absolutely necessary • Don’t: migrate junk, large files, stale branches, or undocumented exceptions Raiffeisen Software | Migration from Bitbucket to GitHub
16. Thank you for your attention Questions? Happy to discuss migration pitfalls, rulesets, and GitHub governance. Contact Yunus Kaya mailto: yunus.kaya@outlook.at