How Chromium's OWNERS System Enforces Expert Code Review

This article explains how the Chromium project uses the OWNERS file system to guarantee that designated domain experts approve code changes within specific directories. By embedding plain-text access control files directly into the source tree and integrating them with automated review tools, Chromium strictly enforces that no code is merged without the sign-off of a developer who intimately understands that part of the codebase.

The Structure of OWNERS Files At the core of the system are plain-text files named OWNERS, which are distributed throughout the Chromium directory tree. Each file contains a list of email addresses corresponding to developers who are recognized as the gatekeepers and domain experts for that specific module or directory.

Hierarchical Inheritance The system operates on a principle of directory inheritance. When a developer modifies a file, the system looks for an OWNERS file in the immediate directory. If none exists, it traverses up the directory tree until it finds one. Consequently, owners listed in higher-level directories hold authority over subdirectories.

However, for highly sensitive areas of the codebase, this inheritance can be broken. By placing the set noparent directive inside an OWNERS file, the system ignores all OWNERS files higher up in the directory tree. This guarantees that only the specific experts listed in that local file can approve changes, preventing even top-level project administrators from bypassing specialized reviews.

Granular File-Level Enforcement Not all files in a directory require the same type of expertise. The OWNERS syntax includes a per-file directive that applies ownership rules to specific files or file patterns. This is heavily utilized for security enforcement. For example, files that define Inter-Process Communication (IPC) interfaces, such as *.mojom files, have immense security implications. A directory's OWNERS file will use the per-file directive combined with set noparent on these specific files, forcing any changes to them to be approved exclusively by members of the Chromium security team, while standard directory owners can still approve changes to normal C++ implementation files in the same folder.

Automated Gatekeeping via Gerrit The rules defined in OWNERS files are not merely guidelines; they are strictly enforced by Gerrit, Chromium’s web-based code review tool, and the Commit Queue (CQ). When a developer uploads a patch (known as a changelist), automated presubmit scripts and Gerrit's built-in plugins parse the list of modified files and map them against the source tree's OWNERS files.

Gerrit dynamically calculates whether the changelist has sufficient approvals. To merge code, every single modified file must receive a "Code-Review +1" vote from at least one valid owner of that file's directory. Until this condition is met, Gerrit visually flags the missing approvals and physically disables the ability to submit the code to the Commit Queue. Once the required domain experts provide their cryptographic sign-off on the review platform, the block is lifted, allowing the automated system to test and merge the change into the Chromium repository.