Using Monorepo for Managing Software Repositories

What is a MonoRepo?

A Monorepo is a type of software repository that contains multiple projects that are related to each other and interact with each other. The concept of the Monorepo is often confused with that of the Monolith repository, which combines multiple sub-projects into a single larger project and platform (UI and application data combined). The Monorepo strategy, on the other hand, can contain multiple projects that are independent of one another but still interact. Monorepo repositories are often used to avoid conflicts between teams and simplify code sharing, versioning, and maintenance. 

When working with projects that contain several projects within one, it can always be considered as a “Code Co-location”, but it will only be regarded as a Monorepo-type repository if there is an established relationship between them. Similarly, when working with a repository of a large application without a correct division of each component, it will then be just a massive Monolith repository.

What is a Polyrepo or Multi-Repo?

A Polyrepo, (or Multi-Repo) on the other hand, is typically connected to micro-services architecture, and code is split into separate repositories as teams develop these micro-services independently. Each repository has its own build and pipeline, with the team having the autonomy to decide which libraries and tools to use. This independence can help small teams to deploy more quickly, if the focus is on high-velocity development, but comes with a laundry list of potential problems when the time comes to integrate these separate applications /services. 

Among the many possible conflicts between repositories, we have: 

• Code sharing – When different teams work on their own parts of a project, they might end up writing similar code separately. To avoid this duplication, they can share their code by creating a common framework and defining a set of tools that everyone can use. This makes it easier to integrate their work, but it can also be challenging to keep everything up-to-date and ensure that everyone is using the latest version.

• Duplicate code – Company teams may develop custom software for the same or similar code for similar functions and components, each with its own implementation. Each time a team ends up doing this it consumes time, increases project maintenance, and can significantly affect safety and quality control.

• Changes between shared repositories – If a bug or critical failure occurs in any project repository, the developer is obliged to correct and define the environment for each of the repositories, a task that becomes costly if the revision histories are disconnected, except, of course, for the subsequent work and coordination required to version the project.

It’s for cases like this that the concept of a Monorepo was developed. With a single repository, all projects feature the following:

• The same CI, without the need to publish versioned packages.
• All developers work on the same commit, avoiding the problems of duplicate code and code sharing between teams described earlier.
• If the repository is unique, then the version is the same for all projects, which prevents conflicts between each other and between external libraries.

Simply creating a single repository will not auto-magically produce these advantages. To have a true Monorepo, and to realize its advantages requires the right tools for the situation. A Monorepo repository is usually composed of a workspace with local and distributed computational caching, consistent development, transparent remote execution, and fluid visibility into the project, among many other requirements.

(image from https://monorepo.tools/)

Monorepo Tools

Monorepo has become an ever more widely adopted strategy, embraced by several companies and teams, which has led to the creation of some exciting tools to help these repositories deliver up to or beyond expectations.

One such tool, for example, is Bazel. Developed internally as Blaze by Google and distributed open-source as Bazel, this tool was released in 2015 and is responsible for ensuring that source code is built following specific rules, a factor that makes it an extremely useful tool when working with a Monorepo.

Another famous tool is Gradle. This will probably be the oldest of the tools on this list, released in mid-2007-2008. Gradle is an open-source build automation system built on Apache Ant and Apache Maven. It manages the software development process for compilation and packaging tasks for testing, deployment, and publishing. It is designed for multi-project builds, making it a great tool for Monorepos. It runs incremental builds by determining the parts of the build tree that are up to date. Those tasks do not need to be re-executed.

Monorepos are also often used for different design libraries, such as Chakra UI or Mantine, where they share packages, code, and components through different sub-projects. They can then export them separately while leveraging the strategy of having all sub-projects in the same place.

For Microsoft-related tools, we have Lage. This tool, built on JavaScript/TypeScript, also seeks to optimize the construction and maintenance of a Monorepo.

These are certainly not the only tools out there to help with the Monorepo strategy. Other examples include Lerna, Nx, Pants, Turborepo, etc.

Challenges of the Monorepo Strategy

No strategy is immune from challenges, and Monorepos is no exception. It is not suitable for every project, as there are several potential situational disadvantages to be aware of, and these need to be considered if there is any chance it might impact your project’s health.

Because it is a single repository containing the entire application, running Continuous Integration (CI) may be more computationally expensive or have a larger build time than in Polyrepo cases. But with the right tools, (Gradle is an example) and some additional configuration, this can be modified so you will only need to build the packages that had modifications.

One of the key potential drawbacks of a single repository is that it may present security problems. Because it is a single repository, and multiple teams (and team members) may have access to all parts of the project, the entire project can be put at risk by a single bad actor. With multiple repositories, access can be granted separately, limited by team or specific team members. Even without malicious intent, this access issue can be a problem. If an error is made, the common code can impact many application components, and source conflicts can be difficult to merge. This issue can be mitigated, however. It is possible to keep separate Monorepos for different teams, with access to only the code that is necessary or that makes sense to be shared. Alternatively, you can protect your Monorepo by limiting who will be able to merge changes to your code and to add an extra security layer, you can use the code owner’s implementation. To learn more about this option, you can review it in this GitHub documentation.

Summary

Monorepositories are a strong solution, striking a balance between the fast and loose implementation of Polyrepos, and the slow and steady but carefully integrated methods required to build monolithic applications. With the right tools and careful application of access policies, a Monorepository might be the right choice for your upcoming project. It allows you to write clean code, and reuse components and code across different projects, while still benefitting from increased productivity.