The monolith that could not be split: ten years of GitLab architecture, 2016-2026

A decade of one company's architecture, reconstructed entirely from primary artefacts: design documents with status fields, twenty-eight numbered decision records, a rejected/ directory, closed merge requests and seven incident reviews with impact numbers. It shows which scaling moves bought years and which removed load permanently, what decomposition costs after the migration is done, and why the deployment model decided more forks than traffic did. A reader can take the decision tree, the failure classes and the API recipes and run the same excavation on their own systems.

What you get out of it

• Every split that left the ownership boundary alone bought one to three years and left a new consistency obligation behind; only changes of ownership removed load permanently.
• Decomposing the database converted two foreign keys into mirrored tables, a reconciliation worker, an alert and a runbook, shipped to every customer including single-database installs.
• Praefect, the Git clustering layer, is described by its own team as 'treated as a failed design'; the 2026 answer returns to network-attached storage with consistency moved into the application.
• A load-shedding mechanism amplified the incident it was meant to mitigate, because deferral re-enqueued jobs onto the saturated shard.
• The deciding input on routing, change data capture and analytics was the deployment matrix, not the technology: anything a self-managed customer cannot operate is either rejected or forks the product.

Scope

Why this, now. GitLab put all three iterations of its cellular architecture on hold in 2026 and replaced them with a narrower programme, and the Gitaly team declared its own clustering layer a failed design in the same window, so the decade can now be read with both of its endings visible.

What it does not cover. No comparison with peer companies, no cost figures and no independent measurement: the session's network policy reached only gitlab.com and github.com, so there are no talks, papers or third-party accounts here.