Mono-repos: Part 1. Introduction

3 min readJan 22, 2022
monorepo v polyrepos — Created with Blender on Instagram

Code organisation is one of the biggest discussions in Software. And similar to most things, it is subjective and the TDLR with this post is this — “choose what works well for your team, but don’t be afraid to try out different things.”

In this post, I want to discuss the basics of a mono-repo and why you could consider it over poly-repos.

What are mono-repos?

Stated simply, mono-repos are code repositories which house more than one deployable. These deployables could be an npm package, a web app, a docker image, a helm template, a shell script, etc., or a combination of these.

Also, this means everything in your project is placed in one repository — these include the source code, documentation, supporting examples (postman collections, curl scripts), CI/CD, and the rest.

Why mono-repos?

This is where the discussion starts, and I encourage each one of you to share your thoughts about mono-repos in the comments.

I understand that this is very subjective but let’s try and list out reasons why mono-repos might be a good idea.


The main reason why mono-repos make sense, as everything is in one place, the complete code base, and supporting material is open to whoever has access to the repository.

This means that reusable parts are more easily discovered and this, in-turn encourages collaboration and maintenance.


Because all code resides in the same git tree, changes required for a feature, when small, can be created in the same pull request. I still recommend separating pull requests when the changes start spanning various parts of the repo.


As your solution grows, you’ll soon realize many of your repository settings need replicating. This is not an issue with mono-repos as there’s only one repository.

But again, this is a trade-off between number of repositories and the work needed to maintain a single repo, let’s discuss these now.

Things to consider for your repositories

Clearly there’s no one solution for all project types and it’s the same with code repository choices. Mono-repos won’t work in all scenarios, a few of which are:

Granular Access Control

If your codebase is for proprietary solutions and requires granular control for access, mono-repos won’t work for you right out of the bat.

This is because git trees cannot have RBAC, it’s either all-in access to repo, or no access at all.

CICD Requirements

Because all the source code resides in one git tree, smart decisions need to made to understand what code has changed and which outputs to rebuild. Thankfully, there are quite a few tools available for this, which I am going to write about in future posts. A mono-repo wouldn’t make sense if each change recreates every single output. This would not scale at all.

This also requires a mature team who understand the complications this creates and how to solve them.

Code Organization

There are a lot of tools available to help create a meaningful structure for code and documentation in your repository. All of which help create a meaningful structure and encourage reusable code.

These are a few thoughts about mono-repos. In the upcoming blogs, I’ll explore tools to help create mono-repos and maintain them. Again, would love to see your thoughts in the comments.





Personal Opinions • Beyond Full Stack Engineer @ McKinsey & Company