Content Library
Scenarios
Migrations
Planning Guides
Checklist for Repository Migrations

Checklist for Repository Migrations

This checklist is intended to facilitate a successful migration to GitHub by providing an overview of the necessary steps involved, with a focus on migrating repositories. This checklist is a guide on what needs to be done for a migration as an approach for planning.

Looking for additional help with your migration project? GitHub has expert resources available to assist and has a large ecosystem of Partner options available.

Migration Tools

For a detailed reference based on source and destination environments, see Migration tools comparison on GitHub Docs.

  • GitHub Enterprise Importer: Recommended for migrations to GitHub.com and GitHub Enterprise Cloud, allows for migrations of source repository content along with associated metadata, such as Pull Requests and Issues.
  • ghe-migrator: Recommended for migrations to GitHub Enterprise Server, allows for migrations of source repository content along with associated metadata.
  • Git-based migration: For source-only repository content migrations without metadata.

Project Planning

Planning is crucial for a successful migration as it provides a structured framework to identify and address potential challenges, ensuring a smooth and efficient transition with minimal disruption to operations.

  • Define the project scope, objectives, and success criteria.
  • Document individuals who need to be involved or informed at different stages.
  • Identify project stakeholders and decision-makers.
  • Establish a project timeline with key milestones.
  • Assess potential risks and develop mitigation strategies.
  • Create a migration plan runbook.
  • Create a comprehensive communication plan.
  • Plan migration pace (e.g., all at once or phased).
  • Document migration schedule for each repository.
  • Identify and document the training needs for both developers and administrators.

Assessment of Current Environment

Understanding the current environment is fundamental for a successful migration. A thorough assessment provides insights into the existing usage, dependencies, and potential challenges, enabling informed decision-making and minimizing disruptions during the transition.

Target Environment Design and Configuration

Making sure that the target GitHub Enterprise Cloud environment is set up for success is critical for a successful migration process. Learn more about GitHub Enterprise Administration and Governance on GitHub Resources and Governance Design Principles.

  • Map source environment repository structures to target organizations/repositories.
  • Plan the structure of the target environment.
  • Plan for handling large files and repositories.
  • Plan for handling release tags and release artifacts.
  • Set up identity access in the target environment. See Identity and access management for more information on Enterprise identity management configuration options.
  • Configure enterprise, organization, and team structure.
  • Configure governance and policy settings.
  • Conduct security assessments on the target environment.

Migration Testing and Preparation

Thorough testing and preparation are essential for successful migrations, as they help identify and mitigate potential issues, ensuring a smooth transition and minimizing disruptions.

  • Define testing criteria and success metrics.
  • Identify migration types for each repository.
  • Choose migration tools.
  • Prepare any dependencies for migration tools, as required, such as infrastructure needs, firewall/network configurations, and authentication methods.
  • Correct any issues on existing repository data or make plans for mitigation (such as large files, commit history, metadata sizing, submodules, and Git LFS usage) based on migration method.
  • Perform dry-run migrations to identify issues.
  • Identify integration and external tools compatibility issues.
  • Configure reverse proxy or app gateway as needed for integration of webhooks and audit log data.
  • Run pilot migrations, document and address issues.
  • Configure integration and external tools with pilot migrations.
  • Communicate with pilot users and gather feedback.
  • Establish a process for handling migration failures.
  • Validate governance and policy settings for any changes needed.
  • Document readiness of the destination environment.
  • Document steps to revert in case of failure.

Repository Migration

Executing the migration is a critical phase that requires coordination and monitoring to ensure a smooth transition. This phase involves executing the migration plan, addressing any issues that arise, and validating the success of the migration.

  • Document issues encountered and resolutions.
  • Freeze changes in the source environment.
  • Create a dedicated migration support channel for issue resolution
  • Execute the migration plan runbook.
  • Track migration status and fix errors.
  • Link identity attribution (when using GitHub Enterprise Importer).

Post-Migration Activities

Post-migration steps are crucial for a successful transition. They involve verifying data integrity, validating functionality, and addressing any issues. Thorough testing minimizes disruptions and ensures the new environment meets requirements. Additionally, it establishes best practices for ongoing maintenance and long-term success.

  • Confirm repository visibility, permissions, and access controls.
  • Validate migrated data.
  • Convert pipelines to GitHub Actions workflows.
  • Ensure CI/CD and other integrations work.
  • Validate governance and policy settings for any changes needed.
  • Validate compliance and auditing requirements.
  • Update configurations for integrations and tools.
  • Gather developer feedback and improvement suggestions.
  • Monitor performance and usage.
  • Conduct a post-mortem for lessons learned.
  • Plan for deprecation of the source environment.
Last updated on