System Design: GitHub (200M Repos, Git Object Storage, Sparse Trigram Code Search, Per-Job VM CI)
Modeled, not leaked. This post models a GitHub-scale platform; it is not a leak of GitHub internals. Scale numbers are engineering estimates.
Internal components (Spokes, Blackbird, Hydro, GLB, Azure runners) are paired with buildable OSS or managed-cloud substitutes.
GitHub's publicly known architecture has historically centered on Rails; this post picks Go to model the shape.
Who this is for
- Interview candidates designing a Git platform
- Architects evaluating Gitaly + Praefect vs managed products
- Startup founders building a code-hosting product
- Infrastructure engineers benchmarking against GitHub-scale
5-minute summary
🔒 Premium section
1. Why this is hard
GitHub looks simple on the surface: host repositories, show pull requests, run CI, search code. In reality each feature maps to a different systems problem with its own storage model, consistency rules, latency targets, and scaling bottlenecks.
Six hard problems shape the design.
1. Git object storage at internet scale. Hundreds of millions of repositories generate trillions of immutable Git objects.
Efficient packing, replication, hot-repo balancing, and garbage collection are required.
2. Fork networks and shared storage. Many repositories are forks with minimal divergence.
Full copies would waste massive storage. Forks need shared object pools while preserving permissions and deletion safety.
3. Pull request diff computation. A PR is based on merge-base comparison, not branch tips.
Graph walks, tree diffs, rename detection, and patch generation must be fast.
4. Code review comment anchoring. Comments attached to specific lines must survive rebases, force-pushes, file renames, and deleted lines.
5. Search across global code volume. Near-instant substring, regex, and symbol search across hundreds of terabytes of source.
6. CI/CD execution of untrusted code. Bursty workloads, strong isolation, secret protection, compute cost control.
Operational constraints make it harder. Pushes cannot be lost. Permissions must always hold. Clone, PR, search, and CI startup must feel fast. Node or regional failures should not cause a major outage. Shared infrastructure must handle abuse and noisy neighbors.
Where systems usually break first
- CI burst queues. Dependabot waves, release cutovers, Monday-morning push storms drain the warm pool faster than it refills.
- Hot repos during release days. One repo absorbing hundreds of pushes/hour saturates a single Git replica set.
- Permission cache misses. A team-membership flip invalidates wide fan-outs; the thundering herd hits MySQL.
- Search indexing lag after mass pushes. A CI robot mass-rewriting files spikes the indexer for minutes.
- Webhook retry storms. A popular repo with thousands of hooks going to a single flaky target.
Each maps to a section below; the rest of the post is about keeping these five from turning into an incident.
2. Functional Requirements
| ID | Requirement | Priority |
|---|---|---|
| FR-01 | Clone, push, fetch Git repos over HTTPS and SSH | P0 |
| FR-02 | Fork with object sharing via alternates | P0 |
| FR-03 | Create and merge PRs with merge-base diffs | P0 |
| FR-04 | Inline review comments with auto-repositioning | P0 |
| FR-05 | Branch protection enforced at receive-pack | P0 |
| FR-06 | CODEOWNERS-based review assignment | P1 |
| FR-07 | Code search across public and authorized private repos | P0 |
| FR-08 | Actions CI/CD with workflow YAML in the repo | P0 |
| FR-09 | Webhook delivery with HMAC-signed payloads | P0 |
| FR-10 | Org management with teams, roles, permissions | P0 |
| FR-11 | Repo file browser with syntax highlighting | P0 |
| FR-12 | Issue + PR search (non-code) | P1 |
| FR-13 | Commit history and blame | P1 |
| FR-14 | Releases with binary artifacts | P1 |
| FR-15 | Markdown rendering cached in Redis | P1 |
| FR-16 | Notifications (email, push, in-app) | P1 |
| FR-17 | Dependabot-style dependency update PRs | P2 |
| FR-18 | Packages (container, npm, Maven) | P2 |
3. Non-Functional Requirements
| ID | Requirement | Target (modeled) |
|---|---|---|
| NFR-01 | Clone p50 / p99 on a typical 50MB-pack repo | <3s / <8s |
| NFR-02 | Push ACK after majority commit | <2s typical |
| NFR-03 | Repo page load | <500ms |
| NFR-04 | PR diff render (≤50 files) | <1s |
| NFR-05 | Code search p50 / p99 | <200ms / <1s |
| NFR-06 | Actions job dispatch-to-running | <30s |
| NFR-07 | Webhook delivery p50 / p99 | <5s / <30s |
| NFR-08 | Availability | 99.95% |
| NFR-09 | Git object durability | 3x replica + object-store backup |
| NFR-10 | Horizontal scalability | Linear for transport, search, CI |
| NFR-11 | Consistency | Strong for refs; eventual for search and CI status |
| NFR-12 | Actions concurrency peak | ~500K jobs |
| NFR-13 | RTO for stateless services | <5 min |
| NFR-14 | Fork storage cost | <1% of upstream |
| NFR-15 | Search index freshness | <2 min typical |
These are design budgets used to size capacity and set alert thresholds, not measured production p99s (p99 is the slowest 1 percent of requests).
Later sections that discuss actual query behavior (e.g. §9.3) use ranges rather than point targets. Latency targets are for a typical repo; large monorepos are a separate tail.
[3.1] Workload assumptions
- Median pack ~5MB. Long tail of monorepos >1GB.
- ~15 commits/repo/day median; hot monorepos see hundreds of pushes/hour.
- ~60M forks in ~1M networks, average size ~50, long tail into tens of thousands.
- Peak/average ~3x on Git ops, driven by working-hours overlap across US timezones.
- Webhook-delivery-to-push ratio ~5:1.
4. Technology Choices and What to Build When
🔒 Premium section
5. End-to-End Architecture
🔒 Premium section
6. Git Object Storage
🔒 Premium section
7. Pull Requests and Diffs
🔒 Premium section
8. Code Review: Comment Anchoring
🔒 Premium section
9. Code Search
🔒 Premium section
10. CI/CD
🔒 Premium section
11. Data Model
🔒 Premium section
12. Back-of-the-Envelope
🔒 Premium section
13. Access Control
🔒 Premium section
14. Fork Model
🔒 Premium section
15. Bottlenecks and Backpressure
🔒 Premium section
16. Multi-Region and Lifecycle
🔒 Premium section
17. Failure Scenarios
🔒 Premium section
18. Operational Playbook
🔒 Premium section
19. SLOs
🔒 Premium section
20. Security, Abuse, and Trust
🔒 Premium section
21. What to build at 10, 50, or 200 engineers
🔒 Premium section
22. Key Takeaways
🔒 Premium section
23. API Design (appendix)
🔒 Premium section
24. Appendix
🔒 Premium section
25. References
🔒 Premium section
