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

> Understand the brave-core repository structure and contribution workflow for brave-browser. Learn the dual-repository process and sync command for collaborators.

- Repository: [Brave Software/brave-browser](https://github.com/brave/brave-browser)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/brave/brave-browser/blob/main/README.md) – General project overview, build instructions, and high-level sync workflow.
- [`CONTRIBUTING.md`](https://github.com/brave/brave-browser/blob/main/CONTRIBUTING.md) – Detailed contribution guidelines, including how to work with `brave-core`.
- [`package.json`](https://github.com/brave/brave-browser/blob/main/package.json) / [`package-lock.json`](https://github.com/brave/brave-browser/blob/main/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:

```bash

# 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](https://github.com/brave/brave-browser/blob/master/README.md).

### Configuring Remote Forks

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

```bash

# 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:

```bash
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:

```bash

# 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:

```bash

# 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:
   ```bash
   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`](https://github.com/brave/brave-browser/blob/main/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:

```bash
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.