Repository Structure and Contribution Workflow for brave-core: A Complete Guide

The brave-core repository functions as a git sub-module within brave-browser at src/brave, requiring contributors to use npm run sync to maintain Chromium alignment and follow a dual-repository workflow for pull requests.

The brave-core repository contains the core browser implementation, patches to Chromium, and the Rust ad-block engine for the Brave browser. Understanding the repository structure and contribution workflow for brave-core is essential because it operates as an independent sub-module inside the main brave-browser monorepo, creating a unique development environment that requires specific synchronization steps.

Understanding the brave-core Repository Structure

The Sub-Module Architecture

The brave-core source lives as a sub-module repository inside brave-browser, checked out at src/brave. This directory is not a static copy; it is a git sub-module that points to the independent brave-core repository at https://github.com/brave/brave-core.

When you clone brave-browser, the sub-module placeholder exists at src/.gitkeep, but the actual brave-core code is populated by running the provided NPM scripts. The surrounding brave-browser repo provides the build tooling, Chromium sync, and scripts that keep brave-core in sync with the Chromium source tree.

Key Directories and Files

Inside the brave-browser root, you will find:

• README.md – General project overview, build instructions, and high-level sync workflow.
• CONTRIBUTING.md – Detailed contribution guidelines, including how to work with brave-core.
• package.json / package-lock.json – NPM scripts that drive init, sync, build, and test operations.
• .github/ – CI workflows, issue templates, and CODEOWNERS.
• docs/ – Sphinx documentation source for the browser project.

When the sub-module is populated at src/brave, the brave-core directory contains:

• DEPS – Chromium dependency file used by gclient to fetch Chromium.
• patches/ – Platform-specific patches applied to Chromium.
• components/ – C++ and Rust components (e.g., adblock_rust_ffi).
• ios/ and android/ – Platform-specific build targets.
• docs/ – brave-core-specific documentation (e.g., Rust usage).

Setting Up Your Development Environment

Cloning and Initializing the Repository

To begin contributing, you must clone the main repository and initialize the sub-module:

# Clone the main repo (includes the sub-module placeholder)

git clone git@github.com:brave/brave-browser.git brave-browser
cd brave-browser

# Install tooling and populate the brave-core sub-module

npm install
npm run init

The npm run init command fetches Chromium and checks out brave-core into src/brave. Details are in the Clone and initialize the repo section of the README.md.

Configuring Remote Forks

Because brave-core is a sub-module, you must configure remotes for both repositories:

# Add a fork for the browser repo (optional if only editing brave-core)

git remote add myfork git@github.com:<your-user>/brave-browser.git

# Add a fork for the brave-core sub-module

cd src/brave
git remote add myfork git@github.com:<your-user>/brave-core.git

The CONTRIBUTING.md file explains this remote-adding process (lines 60-75).

The brave-core Contribution Workflow

Creating Feature Branches

Always create feature branches within the src/brave directory for your changes:

cd src/brave
git checkout -b my-feature-branch

Branch naming guidelines are mentioned in the CONTRIBUTING guide. Keep branch names descriptive and prefixed with the issue number when applicable.

Making Changes and Syncing

When modifying brave-core, you may need to edit C++, Rust, or JavaScript files, or modify Chromium patches under src/brave/patches/. Before committing, ensure the repository stays in sync:

# From the repo root

npm run sync

# For a forced re-sync

npm run sync -- --force

The npm run sync script updates sub-projects, reapplies patches, and runs hooks. This is the central tool for keeping Chromium, brave-core, and patches in lockstep.

Testing Your Changes

Run the appropriate test suites before submitting:

# Unit tests for core C++/Rust code

npm run test brave_unit_tests

# Browser-level integration tests

npm run test brave_browser_tests

# JavaScript unit tests (run inside src/brave)

cd src/brave
npm run test-unit

Testing requirements are summarized in the Making changes section of CONTRIBUTING (lines 81-94).

Submitting Pull Requests

When ready to submit:

1. Commit your changes with clear messages:

   git add .
   git commit -m "Brief title – fix X / implement Y"
   git push myfork my-feature-branch

2. Open the PR from src/brave (your brave-core fork) to the upstream brave-core:master.

3. Select appropriate reviewers using .github/CODEOWNERS.

4. Ensure your PR includes:

   • A clear title and description
   • A reference to the issue it fixes (use GitHub auto-closing keywords like Fixes #1234)
   • Steps to test the change (mandatory per CONTRIBUTING)
   • Screenshots if UI changes are involved

The Pull requests section of CONTRIBUTING (lines 111-136) outlines this checklist.

CI Validation and Merge

GitHub Actions run CI workflows defined in .github/workflows/ (e.g., pull_request.yml). Reviewers verify test coverage, linting, and that patches apply cleanly. Address comments by pushing additional commits to the same branch.

Once approved, the PR merges into brave-core. Update the brave-browser repo:

git pull                # Bring in the new sub-module commit

npm run sync            # Re-apply patches and update Chromium if needed

For back-porting to other release channels, follow the "Uplifting a pull request" guide referenced in CONTRIBUTING (line 39).

Summary

• brave-core functions as a git sub-module within brave-browser, located at src/brave, containing the core browser implementation and Chromium patches.
• Initialization requires running npm run init after cloning to populate the sub-module and fetch Chromium dependencies.
• Synchronization is managed through npm run sync, which keeps Chromium, brave-core, and patches aligned.
• Contribution workflow involves creating branches within src/brave, pushing to your brave-core fork, and opening PRs against the upstream brave-core:master repository.
• Testing mandates running brave_unit_tests and brave_browser_tests before submission, with CI validation through GitHub Actions.

Frequently Asked Questions

What is the relationship between brave-browser and brave-core?

The brave-browser repository is a monorepo that contains build tooling, CI configuration, and scripts to synchronize with Chromium. The brave-core repository is an independent git sub-module checked out at src/brave that contains the actual browser implementation, Rust components, and Chromium patches. You clone brave-browser first, then use npm run init to populate the brave-core sub-module.

How do I update Chromium when contributing to brave-core?

Run npm run sync from the root of the brave-browser directory. This script updates the Chromium source tree, synchronizes the brave-core sub-module to the correct revision, reapplies patches from src/brave/patches/, and runs necessary hooks. Use npm run sync -- --force for a complete re-synchronization if you encounter patch application errors.

Where should I open my pull request for brave-core changes?

Open your pull request against the brave/brave-core repository (upstream master branch), not the brave-browser repository. Even though you work inside src/brave locally, you must push your branch to your personal brave-core fork on GitHub and create the PR from there. Select reviewers based on the .github/CODEOWNERS file in the brave-core repository.

What testing is required before submitting a brave-core PR?

You must run both unit tests and browser tests before submitting. Execute npm run test brave_unit_tests for C++ and Rust component testing, and npm run test brave_browser_tests for integration testing. For JavaScript changes within brave-core, run npm run test-unit from the src/brave directory. All tests must pass locally before pushing, as GitHub Actions will re-run the full CI suite defined in .github/workflows/ upon submission.

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