The Chromium Commit Queue and Mandatory Trybots Explained

This article provides a comprehensive overview of the Chromium Commit Queue (CQ) and the automated testing infrastructure that guards the Chromium codebase. It explains how the CQ automates the process of verifying and merging code changes, and details the specific mandatory trybots—across Linux, Windows, macOS, Android, iOS, and ChromeOS—that must successfully build and pass tests before any patch is allowed to land in the main repository.

What is the Chromium Commit Queue?

The Commit Queue (CQ) is an automated system within the Chromium project's Layered Universal Continuous Integration (LUCI) infrastructure. Its primary purpose is to protect the stability of the main Chromium source tree by ensuring that incoming code changes—known as Changelists (CLs)—compile correctly and pass a rigorous suite of automated tests before they are merged.

Developers interact with the CQ through Gerrit, Chromium’s code review tool. The workflow operates in two main modes:

  • CQ Dry Run (Commit-Queue +1): Triggers the automated tests on a CL without merging the code. Developers use this to verify their changes before or during a code review.
  • Submit to CQ (Commit-Queue +2): Used after a CL has received approval (Code-Review +1) from the necessary code owners. The CQ runs all required tests, and if every test passes, it automatically rebases the patch and merges it into the main Git branch. If any test fails, the CQ rejects the patch and notifies the developer.

Which Trybots Must Pass Before Code Lands?

Trybots are the individual automated builders and test runners orchestrated by the CQ. When a developer submits a CL to the Commit Queue, it dispatches the code to a specific set of trybots in parallel.

For a typical C++ or core code change in Chromium, the following core trybots are mandatory and must pass completely:

1. Presubmit and Static Analysis

  • chromium_presubmit: This is the fastest and most fundamental bot. It does not compile the browser; instead, it runs scripts to check code formatting, verify license headers, enforce banned C++ functions, and ensure that the developer has approval from the correct directory OWNERS.
  • tricium-metrics-analysis / Clang Tidy: Analyzes the code for common programming errors, style violations, and metric configuration issues.

2. Desktop Platforms

  • linux-rel: Compiles a release build (with assertions enabled) for Linux and runs unit tests, browser tests, and web platform tests.
  • win-rel: Compiles a 64-bit release build for Windows and executes the standard Windows test suites.
  • mac-rel: Compiles a release build for macOS and runs tests across both Intel and Apple Silicon architectures.
  • linux-chromeos-rel: Compiles the ChromeOS version of the browser running on a Linux environment and executes ChromeOS-specific test suites.

3. Mobile Platforms

  • android-arm64-rel: Compiles the Android browser for 64-bit ARM architecture and runs tests on physical Nexus/Pixel devices or emulators hosted in the swarming infrastructure.
  • android-binary-size: A specialized bot that ensures the CL does not inadvertently bloat the final download size of the Chrome APK on Android beyond a strict threshold.
  • ios-simulator: Compiles Chromium for iOS and runs unit and integration tests inside the Xcode iOS Simulator.

4. Emerging Platforms

  • fuchsia-x64-cast-receiver-rel (and related Fuchsia bots): Compiles and tests Chromium components designed to run on the Fuchsia operating system.

Conditional and Path-Specific Trybots

The Chromium repository is massive, so running every test in existence for every CL is computationally impossible. To optimize resources, the CQ uses a dynamic configuration file (commit-queue.cfg) to determine which trybots are necessary based on the specific files modified in the CL:

  • Documentation Changes: If a CL only modifies Markdown (.md) files, the CQ will bypass all compilation trybots and only run chromium_presubmit.
  • Platform-Specific Code: If a CL only modifies files strictly isolated to macOS (such as .mm Objective-C++ files in a Mac-only directory), the CQ may skip the Windows and Android trybots.
  • Specialized Subsystems: Modifying specific directories triggers additional mandatory trybots. For example, changing code in the //gpu directory will automatically add hardware-accelerated GPU trybots (like linux-swangle-try-x64 or specific Mac/Windows GPU bots) to the required queue. Similarly, modifying WebXR or V8 JavaScript engine interfaces will pull in dedicated bots for those subsystems.

Handling Flaky Tests

Because the CQ runs thousands of tests across multiple operating systems, network or timing issues can occasionally cause a test to fail even if the developer's code is fine (known as a "flaky" test).

Before rejecting a CL, a trybot will automatically retry failed tests inside the same build. If the test passes on the retry, the trybot marks the build as successful (often noted as "passed with flakes"), allowing the code to land without forcing the developer to restart the entire Commit Queue process.