Repositories
An app's code, its deployment configuration and the configuration of the cloud it runs on all live in git. How you split them over repositories determines who can change what, which pipelines run for a commit, and how many merge requests one change takes. Five layouts are common, each with upsides and downsides, and none fits every team. Start from cloud and projects: one repository for the cloud, and one repository per project that holds the app's code and its deployment configuration. When you adopt GitOps, move the deployment configuration into one configuration repository, as in projects and configuration. Change the layout when the signals under Choosing keep showing up.
The deployment configuration is what a deployment reads, such as Kubernetes manifests or Helm values per environment. A pipeline applies it, or a GitOps controller watches it. The cloud is what the apps run on: infrastructure as code and cluster configuration. Projects covers the layout inside one repository.
One monorepo
One repository holds the cloud, the deployment configuration of every app and the code of every app:
monorepo/
├── cloud/ infrastructure as code, cluster configuration
├── config/ deployment configuration of every app
└── apps/ code of every appUpsides
- One merge request can change an app, its deployment configuration and the cloud, and the reviewer sees all three.
- Shared libraries and every app that uses them change in the same commit, without publishing a package version.
- Pipelines, linters and conventions are defined once, and everyone searches one tree.
- New developers clone one repository.
Downsides
- Git hosts grant access per repository, so everyone who can push app code can also push changes to the cloud and to production configuration.
- Code owner rules only add required approvals per path, and everyone with access still reads every file.
- Every commit starts the pipeline of the whole repository, so each job needs path rules, such as
rules:changesin GitLab CI. - Large repositories need a build tool that builds and tests only what a commit affects.
- Two apps changed in one commit still deploy one after the other, so each has to work with the old version of the other.
- Argo CD regenerates every app's manifests after any commit to the repository, unless the
argocd.argoproj.io/manifest-generate-pathsannotation limits it. - New image tags that the pipeline commits start the pipeline again, unless the commit carries
[skip ci]or is pushed with--push-option=ci.skip. - Production changes sit between code commits in the history, so finding when a setting changed takes
git log -- config/. - Tags are per repository, so apps with their own release cycle need prefixed tags such as
shop-1.4.0.
Polyrepo
Every app, every app's deployment configuration and every part of the cloud gets a repository of its own:
shop/ code of the shop app
shop-config/ deployment configuration of the shop app
billing/ code of the billing app
billing-config/ deployment configuration of the billing app
cluster/ cluster configuration
network/ infrastructure as code for the networkUpsides
- Access per repository matches who may change what: a developer can push to
shopwithout push access toshop-configorcluster. - Each repository has its own pipeline, tags and release cycle, and its pipeline builds only what's in it.
- Changing the replicas or an environment variable deploys without building the app again.
- The history of a configuration repository lists every change to what runs, and CI can commit image tags to it without starting a build.
- Small repositories are quick to clone, and easy to open source or hand over to another team.
Downsides
- Changes that span repositories take one merge request per repository, merged in the right order, and no pipeline tests them together before they merge.
- Shared code needs a package with its own versions and releases, and every repository that uses it upgrades on its own schedule.
- Pipelines, linters and conventions drift apart unless every repository includes the same CI templates and gets dependency updates from a bot such as Renovate.
- Developers have to find, clone and get access to more repositories.
- No single tree shows what runs in an environment, since each app's configuration is in its own repository.
Cloud and projects
The cloud gets one repository, and every project gets a repository that holds the app's code and its deployment configuration together:
cloud/ infrastructure as code, cluster configuration
shop/
├── src/ code
└── deploy/ deployment configuration per environment
billing/
├── src/
└── deploy/The project's pipeline deploys from deploy/, or a GitOps controller, set up in the cloud repository, watches each project's deploy/ directory. The Cloud Handbook covers what goes in the cloud repository and how to set up the cloud platform.
Upsides
- A feature and the configuration it needs, such as a new environment variable, land in one merge request, and the reviewer sees both.
- The code and the configuration it expects are in the same commit, so a deployment can't pair an image with settings meant for another version.
- The team that writes the app also owns its deployment, with its own members, tags and pipeline per project.
- App developers don't need push access to the cloud repository, so a project's merge request can't change the cluster or the network.
- Adding a project means one new repository, and removing a project removes one.
Downsides
- Configuration-only changes, such as more replicas, run the project's pipeline and build the app again unless the build jobs have path rules.
- New image tags that the pipeline commits start the pipeline again, so skip CI for that commit, or deploy the tag without committing it.
- Everyone who can merge app code can also change its production configuration, since both are in one repository.
- An app built from several repositories but deployed as one unit has no obvious home for its deployment configuration.
- What runs in an environment is spread over the project repositories, and only the cluster or the GitOps controller shows all of it.
- Changes across projects, such as an API change between two apps, still take one merge request per project.
Projects and configuration
The cloud gets one repository, every project gets a repository for the app's code, and one configuration repository holds the deployment configuration of every app. The GitOps controller watches the configuration repository:
cloud/ infrastructure as code, cluster configuration
config/
├── shop/ deployment configuration of the shop app per environment
└── billing/
shop/ code of the shop app
billing/ code of the billing appA team on cloud and projects moves to this layout when it adopts GitOps and keeps each app's code in its own repository: the deploy/ directories move into the configuration repository.
Upsides
- Configuration changes such as more replicas deploy without a build.
- The history of the configuration repository lists every change to what runs, without code commits in between.
- CI commits new image tags to the configuration repository, so a tag commit never starts the build that made the image.
- Access splits by role: developers push to their project, and a smaller group merges production configuration.
- One tree shows what runs in every environment, and promoting a version from staging to production is one merge request.
- Each project keeps its own members, tags, pipeline and release cycle.
- An app built from several repositories but deployed as one unit has one place for its deployment configuration.
Downsides
- A feature that needs new configuration takes two merge requests, and the configuration has to land before or with the new image.
- Developers work in their project's repository and in the configuration repository, and have to know which setting lives where.
- Every release needs a commit to the configuration repository, from the project's pipeline or from a bot such as Renovate or Argo CD Image Updater.
- A project pipeline that can push image tags to the configuration repository can change every app's configuration there.
- Everyone with push access to the configuration repository can change every app's configuration, and code owner rules only add required approvals per path.
- Changes across projects, such as an API change between two apps, still take one merge request per project.
Three monorepos
One repository holds the cloud, one holds the deployment configuration of every app, and one holds the code of every app. The GitOps controller watches the configuration repository:
cloud/ infrastructure as code, cluster configuration
config/
├── shop/ deployment configuration of the shop app per environment
└── billing/
code/
├── shop/
└── billing/Upsides
- Configuration changes such as more replicas deploy without a build.
- The history of the configuration repository lists every change to what runs, without code commits in between.
- Access splits by role: developers push code, and a smaller group merges production configuration.
- CI commits new image tags to the configuration repository, so a tag commit never starts the build that made the image.
- One tree shows what runs in every environment, and promoting a version from staging to production is one merge request.
- Shared libraries and the apps that use them change in one commit, as in one monorepo.
Downsides
- A feature that needs new configuration takes two merge requests, and the configuration has to land before or with the new image.
- Developers work in two repositories and have to know which setting lives where.
- Every release needs a commit to the configuration repository, from the pipeline or from a bot such as Renovate or Argo CD Image Updater.
- Everyone with push access to the configuration repository can change every app's configuration, and code owner rules only add required approvals per path.
- The code repository needs path rules in CI and, as it grows, a build tool that builds only what a commit affects.
- No pipeline tests a code change against the configuration it will run with before both are merged.
Choosing
Start from cloud and projects, and change the layout when one of these signals keeps showing up.
Access
When the people who write the code aren't the people who may change production configuration or the cloud, put those parts in separate repositories. Git hosts enforce read and push access per repository only. Code owner rules add required approvals per path, but anyone with access still reads every file. On GitLab, code owner approval needs a paid tier.
Releases
Parts with their own release cycle and version numbers fit separate repositories, because tags, release notes and release pipelines work per repository. Parts that always release together, such as a frontend and the API built for it, fit one repository.
Teams
For one team, few repositories means one place to look, fewer pipelines to maintain and one access list. Several teams get their own access, pipelines and review rules from a repository per team or project, so they don't wait on each other's reviews. A monorepo shared by many teams needs code owner rules and a build tool that builds only what changed.
Coupling
When most merge requests in one repository need a matching merge request in another, the two repositories change together. Merge them, or move the part they share into one of them. The reverse holds too: a directory that never changes with the rest of its repository can move out.
Pipelines
When pipelines spend most of their time on parts a commit didn't touch, add path rules to the jobs, or split those parts off. When a configuration change waits for a full build, add path rules that skip the build, or move the configuration to its own repository.
GitOps
When you adopt a GitOps controller, move the deploy/ directory of each project into one configuration repository, as in projects and configuration. The controller then watches one repository, and CI commits image tags there without starting a build.
Changing
A layout change moves more than files: each part's pipelines, access rules and GitOps controller sources move with it, and every developer clones again. Merge or close the open merge requests of a part before you move it, because they stay behind in the old repository.
Keep the history when you move a part, with the git filter-repo tool in a fresh clone. To split a directory into its own repository, run git filter-repo --subdirectory-filter <directory>. To combine two repositories, move the files of one into a subdirectory with git filter-repo --to-subdirectory-filter <directory>. Then merge that repository into the other with git merge --allow-unrelated-histories.