How Brave Manages the DEPS File for Chromium Dependency Synchronization

Brave uses a partial DEPS file located at src/brave/DEPS that extends and overrides upstream Chromium dependencies, synchronized via gclient sync and gated by CI validation.

The brave/brave-browser repository maintains a complex dependency relationship with upstream Chromium, requiring precise version control to ensure stability and security. The DEPS file serves as the single source of truth for Chromium revisions, allowing Brave to pin specific versions while applying proprietary patches and extensions.

Understanding the DEPS File Architecture

Brave's dependency management relies on a two-layer system that combines upstream Chromium configurations with Brave-specific overrides.

The Base Chromium DEPS

The upstream Chromium source contains a root DEPS file that enumerates all Chromium-owned dependencies, including third-party libraries, testing tools, and build dependencies. This file lives in the Chromium repository and defines the baseline versions that Brave extends.

Brave's Partial DEPS Override

Brave adds its own src/brave/DEPS file that extends and overrides entries in the Chromium DEPS. This partial DEPS file pins Brave-specific components including:

• The exact Chromium version via the chromium_version variable
• Brave-specific patches located in the patches/ directory
• Ad-blocking libraries and privacy components not present in Chromium

The Synchronization Workflow

Synchronizing dependencies requires coordinating gclient configuration with Brave's build scripts.

gclient Configuration

The src/.gclient file defines the "solution" that tells gclient sync where to fetch Chromium and how to apply the Brave overlay. This configuration ensures that Chromium is fetched into src/chrome before Brave's modifications are applied.

Running the Sync Command

Developers trigger synchronization using the npm shortcut defined in package.json:

# Sync the entire source tree (Chromium + Brave patches)

npm run sync

This command executes gclient sync, which reads the merged DEPS configuration, pulls the exact Chromium revision specified in src/brave/DEPS, and applies Brave's patches from the patches/ directory.

To verify the specific Chromium revision that was fetched:

git -C src/chrome rev-parse HEAD

The output should match the revision hash defined in src/brave/DEPS.

Chromium Version Bumping Process

When a new Chromium version is released, Brave maintainers follow a disciplined bump process using the .github/ISSUE_TEMPLATE/06_chromium_bump.yml template. The process involves:

1. Updating the chromium_version variable in src/brave/DEPS
2. Running npm run sync to verify the checkout and apply patches
3. Updating related build scripts such as src/tools/update_brave_version.py
4. Submitting the change for CI validation

Example update to src/brave/DEPS:

# Update the Chromium revision in src/brave/DEPS

sed -i.bak 's/"chromium_version": ".*"/"chromium_version": "124.0.6367.91"/' src/brave/DEPS

# Re-run the sync to pull the new revision and apply Brave patches

npm run sync

# Commit the validated change

git add src/brave/DEPS
git commit -m "Bump Chromium to 124.0.6367.91"

Continuous Integration and Validation

Brave's CI system enforces DEPS consistency on every pull request. The .github/workflows/pull_request.yml workflow runs gclient sync before each build, guaranteeing that the exact revisions recorded in src/brave/DEPS are used. Any mismatch between the DEPS specification and the actual checked-out code causes the CI to fail, preventing accidental dependency drift.

Key Files in the DEPS System

File	Role
src/brave/DEPS	Brave-specific dependency overrides that pin the Chromium version and define Brave-specific components
src/.gclient	gclient configuration specifying how to fetch Chromium and apply the Brave overlay
package.json	Contains the npm run sync script shortcut for developers
.github/ISSUE_TEMPLATE/06_chromium_bump.yml	Issue template for coordinated Chromium version bumps
.github/workflows/pull_request.yml	CI workflow that validates DEPS synchronization on every PR

Summary

• Brave uses a partial DEPS file at src/brave/DEPS to extend upstream Chromium dependencies without modifying the root Chromium repository.
• The chromium_version variable in src/brave/DEPS serves as the single source of truth for which Chromium revision Brave builds against.
• gclient sync (via npm run sync) merges the Chromium and Brave DEPS configurations, fetches the exact revisions, and applies Brave-specific patches.
• A structured bump process using GitHub issue templates ensures coordinated updates to Chromium versions with full CI validation.
• Continuous integration enforces DEPS consistency by running gclient sync on every pull request, preventing dependency drift.

Frequently Asked Questions

How does Brave pin a specific Chromium version without forking the entire Chromium repository?

Brave stores a chromium_version variable in src/brave/DEPS that specifies the exact revision hash or tag to fetch. When gclient sync runs, it reads this variable and checks out the specified Chromium revision into src/chrome, allowing Brave to build against a specific upstream version while keeping its own modifications separate in src/brave.

What happens if the DEPS file specifies a Chromium revision that is incompatible with Brave's patches?

The CI system will fail during the gclient sync or patch application phase. Brave maintains a patches/ directory containing modifications to Chromium source files. If a Chromium bump changes the underlying code that a patch targets, the patch will fail to apply cleanly, causing the build to break. This signals maintainers to update the affected patches before the new Chromium version can be adopted.

Can developers manually override the Chromium version for local testing?

Yes, developers can manually edit src/brave/DEPS to change the chromium_version value to a different revision hash or tag. After modifying the file, running npm run sync (which invokes gclient sync) will fetch the new Chromium version and attempt to apply Brave's patches. However, this is not recommended for production builds as it bypasses the validated bump process and may introduce instability or security vulnerabilities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}