Ownership, but for code, not people

GitHub’s main application is a Ruby on Rails monolith with over 4.2 million lines of code across roughly 30,000 files. Historically, the company has organized that codebase—and the engineers working on it—through CODEOWNERS in combination with GitHub teams, organizations, issues, and repositories. But as GitHub’s user base and engineering organization have grown, that model has become insufficient. The company found it was missing a layer between how it groups humans and how it groups work to be done. Enter SERVICEOWNERS: an abstraction that injects a “service” layer between groups of functionality and the people maintaining them.

Notably, GitHub has deliberately moved away from the semantics of “ownership” in this context. In the company’s open source ecosystem, the maintainer model more accurately describes the relationship between a team and a service. Where CODEOWNERS is about who is responsible for a set of paths, SERVICEOWNERS is about the services themselves—who maintains them, how they perform, and what they depend on.

One file to define them all

The SERVICEOWNERS file lives in the monolith next to CODEOWNERS. It uses the same syntax: glob patterns (e.g., app/api/integration*), directories (e.g., config/access_control/), and filenames (e.g., app/api/grants.rb) are each mapped to a service name like :apps, which corresponds to the github/apps team.

The file is CI-enforced. The validation rules are:

  • No duplicate patterns, directories, or files are permitted.
  • Every new file added to the github/github repository must have a service owner.
  • Every declared pattern, directory, or file must match at least one existing file.
  • If multiple glob patterns can match the same file, it must be disambiguated with a file or directory entry.

The service-mappings.yaml file defines how the services named in SERVICEOWNERS map to the service catalog and to GitHub teams. It can declare a service’s product manager, engineering manager, repository, and chat information. It can also assign classifications such as a “tier” rating, from zero for critical platform infrastructure to three for experimental or non-critical work.

SERVICEOOWNERS definitions are not limited to the monolith, either. Any repository in the GitHub org can contain an ownership.yaml file, offering version-controlled service metadata from outside the main codebase. This allows the same logical service to have boundaries that span repositories—e.g., GitHub Desktop can be a component of the monolith and also exist as a standalone artifact from a separate repo. An additional benefit: changes to the monolith’s codebase can be grouped around features rather than maintainership.

From file to catalog

The service catalog is the practical result of all this metadata. It centralizes every service definition in one place, including SLO performance, scorecards from GitHub’s fundamentals program, dependencies, and how information flows through the platform. The dependency map is useful for onboarding new engineers, because the service relationships effectively describe the architecture of the platform—no stale documentation required.

For incidents, the catalog also provides direct channels of communication. That has had concrete impact on incident remediation time—incident commanders can look up who maintains a service and how to reach the on-call engineer.

Under the hood, the tooling is a Ruby gem called serviceowners that combines the data from SERVICEOWNERS and service-mappings. It generates the CODEOWNERS file automatically. That means updating who maintains a service is a one-line YAML change, not a manual edit of ownership rules. The gem also comes with a command-line executable that can answer questions like “what is the service this file belongs to?” or “which files belong to this service?”.

And, because this is GitHub, there is a chat-op as well:

me: hubot serviceowners for test/jobs/do_the_thing_with_the_stuff_test.rb

hubot: The file test/jobs/do_the_thing_with_the_stuff_test.rb is part of the github/some_service service and is maintained by the cool-fun-team team who can be reached in #hijinx.

The combination of CODEOWNERS and SERVICEOWNERS gives GitHub a durable mapping between code and people that survives team reorganizations. When priorities shift or teams change, metadata definitions in YAML only need minimal updates. The system aligns well with GitHub’s open source identity and access management project, entitlements, and the company says the model is applicable across organizations, open source or corporate.