Migrating Git repositories permalink

I recently needed to migrate our company’s git repositories from GitHub to an on-prem BitBucket instance without completely blocking the on-going work of >100 engineers. While Atlassian provides a tool to import, I couldn’t find the tool in our instance of BitBucket and had to resort to the built-in tools in git as described in the GitHub documentation:

  1. Make a bare mirrored clone of the repository

    git clone --mirror https://github.com/exampleuser/repository-to-mirror.git
cd repository-to-mirror.git

  2. Set the push location on the mirror to your new remote

    git remote set-url --push origin https://git.ourserver.com/exampleuser/mirrored.git
git push --mirror

  3. Update from original repository in case changes are made

    git remote update

Once I had the commands down, it was just a matter of coordination and ordering. My approach followed these basic steps:

  1. Create users and groups in BitBucket (This was actually done for my since we had integrated our ActiveDirectory server with BitBucket).
  2. Setup a Jenkins user with public SSH key so that our Jenkins jobs can clone repositories to build
  3. Create a new, empty repo in BitBucket
  4. Run through the steps above, using the new BitBucket repo
  5. Clone Jenkins jobs, disable them (so they don’t accidentally cause race conditions with the existing jobs) and update them to use the new BitBucket repo
  6. Disable the old Jenkins jobs.
  7. Enable the new Jenkins jobs and test them.
  8. Restrict access to the old GitHub repository so that no one can write to it
  9. Update the mirror from the old GitHub repository and push to BitBucket
  10. Notify everyone to update their local repositories using git remote set-url origin https://git.ourserver.com/exampleuser/mirrored.git
  11. Delete old Jenkins jobs
  12. Set a reminder to delete the old repository in 2 sprints.
© 2023