Migrating to Monorepo: A Step-by-Step Guide

Greg Foster
Greg Foster
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


Migrating to a monorepo structure from multiple repositories can streamline your development process, but it requires careful planning and execution. Here is a step-by-step guide to help you through the transition.

Step 1: Preparation

  • Evaluate the benefits: Assess if the monorepo model aligns with your team's workflow and goals.

  • Communication: Discuss the migration plan with your team to ensure everyone understands the benefits and the process.

  • Choose the right tools: Select tools that support monorepo management, such as Lerna, Yarn Workspaces, or Bazel, which can aid in the transition and future management.

Step 2: Planning

  • Structure your monorepo: Decide on the directory structure of the monorepo, considering how to group projects and shared code.

  • Dependency management: Plan how to handle dependencies between projects, possibly using workspace tools or package managers that support monorepos.

Step 3: Combining Repositories

  • Start with a new repository or designate one of the existing repositories as the monorepo.

  • Gradually move other projects into the monorepo, ensuring to maintain their history. Tools like git subtree can be used for this purpose.

  • Resolve any conflicts that arise from combining repositories, such as overlapping files or incompatible git histories.

Step 4: Configuring the Build System

  • Set up build configurations that handle the newly structured projects. Ensure that the build system can handle incremental builds and can scale with the monorepo.

  • Test the build process thoroughly to ensure that all projects build correctly in the new setup.

Step 5: Continuous Integration/Continuous Deployment (CI/CD)

  • Adjust your CI/CD pipelines to work with the monorepo. This might involve setting up path filters to trigger builds only for changed projects.

  • Optimize CI/CD for speed and efficiency, possibly using caching and parallelization techniques.

Step 6: Training and Documentation

  • Update your documentation to reflect the new monorepo structure and workflows.

  • Train your team on the new processes, ensuring everyone is comfortable with the new system.

Step 7: Monitoring and Optimization

  • Monitor the monorepo for any issues that might arise post-migration.

  • Continuously optimize the monorepo setup to handle the evolving needs of your projects.

On this page
Git inspired
Graphite's CLI and VS Code extension make working with Git effortless.
Learn more

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2