Your singletons choose where you fail: ten years of GitLab's architecture

A decade of one company's platform evolution, reconstructed entirely from primary artefacts it publishes in Git repositories: 207 design documents, two rejected routing proposals, a closed merge request that deletes a consensus layer, and five public incident reviews. After reading it you can order your own decomposition work by divisibility rather than size, and name the shared resources that will decide where your platform actually fails.

What you get out of it

• Every incident in the public corpus lands on something shared rather than something large: Redis for Sidekiq, one Gitaly storage node, Consul under Patroni, and an edge provider.
• Code decomposition and runtime decomposition solve different problems; GitLab's runtime split advanced through four designs while the Rails decomposition document sat at status 'proposed' for three years.
• The database work moved because it had a number: physical tables under 100 GB, act at 10 GB, against a 2.5 TB table growing 300 GB a month.
• An ADR accepted deeper Cloudflare dependency in writing; 22 months later a Cloudflare outage removed GitLab.com and the responders' own runbooks for 25 minutes.
• A cellular architecture buys isolation by creating a new global singleton, the routing control plane, which GitLab put on managed Spanner in a different cloud from the cells themselves.

Scope

Why this, now. GitLab's Cells programme reached its fourth design in 2026 and its first cells now run in a second cloud, so the decade's decisions are visible end to end while the outcome is still open.

What it does not cover. GitLab's self-managed and Dedicated products except where they constrain the SaaS design, its AI features and commercial history, any comparison with how other companies solved the same problem, and GitLab's own blog posts, which this session's network policy made unreachable.