How GitHub Is Transforming Its Monolith into Scalable Microservices

1. Journey Begins

GitHub was founded in 2008 to make code hosting and sharing easy for developers. Its creators were influential Ruby open‑source contributors, so the platform’s architecture is deeply rooted in Ruby on Rails. Over the years GitHub hired top Ruby engineers, expanding and optimizing the codebase. Today the platform serves over 50 million developers, processes more than 80 million pull‑request merges annually, and hosts over 100 million repositories worldwide. The monolithic codebase, evolved for 12 years, now coordinates multiple daily deployments, handles a billion API calls per day, and powers a high‑performance UI.

2. Rapid Internal Growth

In the past 18 months GitHub’s staff grew to over 2 000, and the number of engineers contributing to the codebase more than doubled. Growth came from organic expansion and acquisitions such as Semmle, npm, Dependabot, and Pull Panda. Even before the pandemic, over 70 % of employees worked remotely across six continents. With a thousand internal developers possessing diverse skill sets, the organization needed to rethink its software development approach. Relying on a single Ruby monolith for all teams became inefficient; Conway’s Law predicts that a monolithic system mirrors the organization’s communication structure, leading to larger meetings and complex decision‑making.

3. Monolith vs. Microservices

The team questioned whether to migrate away from the Ruby on Rails monolith toward microservices and how to do it. Monoliths are simple to configure and run, requiring fewer dependencies, and allow rapid local setup. They keep code concise, avoid timeout handling, and benefit from a shared technology stack. However, as GitHub grew, microservices offered advantages: feature‑team ownership via clear API contracts, smaller codebases that are easier to read, faster startup, simpler debugging, and independent scaling of services based on demand.

4. Pragmatic Approach – Empowerment First

Before migration, GitHub examined why and what problems the change should solve. The shift is a cultural transformation requiring extensive effort. The goal is to empower developers rather than replace existing workflows. GitHub will adopt a hybrid environment where new features run as microservices while the monolith remains important. An example is the recent upgrade to Ruby 2.7, documented on the official GitHub blog.

5. Good Architecture Starts with Modularity

Modularization is the first step in breaking the monolith. Teams should split code and data by feature boundaries within the monolith before extracting services. Each service must own its data and expose it only through well‑defined API contracts. Avoid “distributed monoliths” where logic is extracted but a shared database remains, as this adds complexity without the benefits of independent deployment.

6. Data Partitioning

Correct data splitting underpins the monolith‑to‑microservice transition. GitHub identifies feature boundaries in the existing schema, groups related tables (e.g., repositories, users, projects) into “schema domains,” and records them in a YAML definition file that serves as the source of truth. Each domain gets a partition key—repository ID for the repository domain, for instance—to co‑locate related data. This enables sharding data across different servers and clusters. GitHub also implements a query monitor to detect cross‑domain queries and rewrites them into separate calls. For large domains, tenant‑based partitioning limits failure impact to a subset of users.

7. Start with Core Services and Shared Resources

When extracting services, dependencies must flow outward from the monolith, never inward, to avoid a distributed monolith. Begin with core services, then move to feature‑level services. Identify internal tooling that aids development, such as feature flags, and move them outside the monolith so they can be used by extracted services. After a new service is live, remove old code paths, using tools like GitHub’s “Scientist” to run and compare old and new implementations side‑by‑side.

8. Extracting AuthN/AuthZ

Authentication and authorization were the first core services extracted because the entire platform depends on them. A failure in github.com would block Git operations, so isolating these functions was critical. GitHub rewrote authentication as an external mirror service and now communicates with the Rails monolith via Twirp, a gRPC‑style RPC framework, with a dependency direction from the monolith outward.

9. Operational Changes

Monitoring, CI/CD, and containerization are not new, but supporting a monolith‑to‑microservice migration requires operational adjustments. Supporting many small, independent services differs from a single, highly customized pipeline. Monitoring shifts from function‑level metrics to network and contract metrics. CI/CD pipelines become more automated and shareable across services. Containerization enables diverse tech stacks, and a self‑service runtime platform provides Kubernetes templates, Ingress load‑balancers, Splunk log forwarding, and integrated deployment workflows to reduce the operational burden for new microservices.

10. Start Small, Align with Product/Business Value

After establishing structural foundations, new features should be built as microservices outside the monolith. Begin with simple, low‑dependency features—GitHub started with webhook delivery and syntax highlighting. Prioritize based on product and business value, grouping code and data that change together frequently. Avoid over‑fragmentation, which can increase complexity, deployment keys, and operational overhead.

11. Implement Asynchronous and Resilient Code

Transitioning to microservices changes communication patterns. Synchronous calls block the client; asynchronous messaging decouples producers and consumers. GitHub uses Twirp for synchronous calls but plans to adopt an event pipeline for better scalability. Implement retry mechanisms with exponential backoff, circuit breakers, and timeouts to handle network latency and failures. Graceful degradation and user‑friendly fallback messages improve resilience.

12. Summary

The first four sections covered the fundamentals to consider before starting a monolith‑to‑microservice journey: migration motivations, modularity, data partitioning, core service extraction, and necessary operational adjustments. Subsequent sections discussed where to start, aligning microservices with product value, and key concepts of service communication and building resilient systems.