Skip to content

Instantly share code, notes, and snippets.

@robandpdx

robandpdx/migration-guide-gerrit-github.md

Last active February 23, 2023 18:07
Show Gist options
  • Save robandpdx/da63457d0cccfdca1866d579ba087dee to your computer and use it in GitHub Desktop.
Save robandpdx/da63457d0cccfdca1866d579ba087dee to your computer and use it in GitHub Desktop.
Download ZIP
Raw
migration-guide-gerrit-github.md

Migration Guide from Gerrit to GitHub

Scope of the document

This document provides the steps involved in migrating source code from Gerrit to GitHub. The CI/CD setup part is currently out of scope of this document.

Introduction

Below is a guided procedure to ensure a migration from Gerrit to GitHub.

Migration steps

The following steps act as high-level phases when implementing a migration project: image

  1. Step 1 - Pre-migration Prepare the source and the target for the migration, decide on the scope, consolidate the sources and ensure the repositories are prepared for migration.

  2. Step 2 - Exporting migration data Generate an archive with all the information to export it to GitHub.

  3. Step 3 - Importing migration data Use the API’s provided to import all the repositories and meta-data to Gerrit.

  4. Step 4 - Post-migration Ensure the migrated resources are correctly set up.

Steps for migration

Step 1: Pre-migration checklist

  • Make a list of all repositories that need to be migrated and categorize them as needed
  • Determine the potential Organization that will be created in GitHub.
  • Use this time of migration to only export the things that matter and do a repository cleanup.
  • Plan some time to execute a dry run of the migration (if possible, on a sandbox environment).
  • Create backups if necessary.
  • Please ensure that SSH configuration for Gerrit and GitHub repositories have been set up. [to be reviewed]
  • If SSH has not been set up, generate an SSH key in your local device and add it to User Profile -> Settings -> SSH Keys -> Add SSH Key.
  • Provide Read, Owner and Create Reference access in Gerrit for the user who is performing the migration to GitHub.
  • If the program asks to enter a username and password, please enter your ID Number as username and your personal access token as the password. (script)
  • If you do not have a Personal Access Token (PAT), go to GitHub Settings -> Developer Settings -> Personal Access Tokens. Check all boxes to configure the permissions needed.

Step 2: Exporting data steps

  • Clone repository from Gerrit When cloning the repository use the --bare option as we don’t need to check out the working tree and branches are copied “as is” to the local repository, without mapping them to refs/remotes/*. git clone --bare <gerrit_repo_url>

  • Analyze repository Use git show-ref to review all branches (refs/heads/) and all tags (refs/tags/) that have been cloned and that will be pushed to GitHub. git show-ref Additionally, you can count the number of branches and tags: git show-ref | grep refs/heads | wc –l git show-ref | grep refs/tags | wc –l

  • Review committers In order to have all commits associated with the correct user on GitHub, ensure that all users with the email addresses used in the Git repository have been created on GitHub. To view all email addresses of all committers of the Git repository, run the following command: git shortlog --summary --numbered --email –all

Step 3: Importing data into GitHub

  • Create an empty repository on GitHub It is preferred that you create the empty repository in GitHub instance.

  • Push repository to GitHub Push the repository using the --mirror option to push all branches and tags. git push --mirror https://<github_repo>.git

  • Verify repository on GitHub Review if all expected files are visible on GitHub. Compare the number of branches and tags with the number that you retrieved in the Analyze repository step. Note: Also, please note that the Max File Size allowed on Gerrit repositories is 314MB. For LFS based migrations, please refer to Large File Storage (LFS) migration (github.com).

Step 4: Post-migration checklist

  • Check GitHub access and permissions

    • Create all the organizations for each of the logical structures in the company
    • Move the repositories to the new organization in GitHub.
    • Check the team structure and permissions
    • Check the users in each team
    • Check the repository access for the teams
    • Check external collaborators
    • See authentication settings for 2FA and SAML (if needed)

  • Old repositories

    • Archive and allow only read access
    • Remove unnecessary access to users

  • New repositories

    • Ensure no content has been lost in the imported repositories
    • Check branches and permissions in place
    • Research the type of GitHub integration you required (OAuth app, GitHub app, webhook, GitHub Actions)
    • Plan each of the integrations and make a guide on how to set it up in the repository
    • Add the integrations to the repositories/organizations that require it

  • Communicate changes

    • Create a shared plan with the team affected by the migration and automation enablement
    • Communicate when the migration is fully completed

References

References and Links

  1. How to move a git repository with history | Atlassian Git Tutorial
  2. git - Migrating commit history from Gerrit to GitHub - Stack Overflow
  3. Introduction (github.com)
  4. From Gerrit to Github. Transitioning the code review tool of a… | by Nathaniel Morihara | Compass True North | Medium
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment