0.1.2 Repository Root

With Bazelisk and .bazelversion handling the build tool itself (0.1.1 Bazelisk & .bazelversion), the next file to look for is the one that marks where the project begins. Every Bazel project needs a root, the single directory that anchors the entire build. Bazel finds this root by looking for a boundary marker file¹. Without one, Bazel doesn't know where your project begins, and no command will work.

The Boundary Marker Files

Three file types can serve as a repository boundary marker²:

Multiple marker files can coexist in the same directory². In practice, a modern project usually has a MODULE.bazel at the root and may also have a REPO.bazel beside it.

A typical project root looks like this:

my-project/
├── .bazelversion
├── .git/
├── MODULE.bazel
├── REPO.bazel          (optional)
├── BUILD.bazel
├── app/
│   ├── BUILD.bazel
│   └── main.cc
└── lib/
    ├── BUILD.bazel
    └── utils.cc

The .bazelversion file from the previous article pins the Bazel release, a boundary marker such as MODULE.bazel establishes the repository root, and BUILD.bazel files create the packages covered next in 0.1.3 Package.

MODULE.bazel

This file serves two purposes⁴:

1. Root marker — tells Bazel where the repository begins.
2. Dependency declaration — lists external modules the project depends on.

A minimal MODULE.bazel can be empty. Its presence is enough to mark the root. A typical one looks like this:

module(name = "my-project", version = "1.0")

bazel_dep(name = "rules_cc", version = "0.2.17")
bazel_dep(name = "platforms", version = "1.0.0")

How bazel_dep() works, version resolution, and the Bazel Central Registry are covered in 3.1 Dependency Management. At this stage, MODULE.bazel sits at the root and anchors everything else.

REPO.bazel

REPO.bazel is also a repository boundary file². Like MODULE.bazel, it can be empty and still mark the root. Its extra job is to set repo-wide defaults for all build targets. For example, applying a common license to all targets:

repo(
    default_package_metadata = ["//:my_license"],
)

It also provides ignore_directories() to exclude directories from Bazel's view (e.g., node_modules)⁵. This is the modern replacement for .bazelignore, covered in 3.2.2 .bazelignore.

In modern Bzlmod-based projects, REPO.bazel usually complements MODULE.bazel rather than replacing it. MODULE.bazel carries module and dependency declarations. REPO.bazel carries repo-wide defaults. Either file counts as a boundary marker.

WORKSPACE (Removed)

Before Bzlmod, the WORKSPACE file was Bazel's only root marker and dependency management mechanism. It required all transitive dependencies to be declared manually, leading to fragile and verbose configurations². It was replaced by MODULE.bazel, disabled by default in Bazel 8, and fully removed in Bazel 9³. A variant named WORKSPACE.bazel also existed, for the same case-sensitivity reasons that BUILD.bazel is preferred over BUILD (covered in 0.1.3 Package).

If you encounter a WORKSPACE file in an existing project, it may not have migrated to Bzlmod yet. See M1 WORKSPACE → Bzlmod.

One Bazel Repo ≈ One Git Repo

A Bazel repository and a Git repository are typically one-to-one, with MODULE.bazel at the same level as .git/⁵. Nesting multiple Bazel repositories inside one Git repository, or placing a Bazel repository in a subdirectory, is possible but unusual and generally discouraged⁴. Bazel calls this directory tree a repository. A workspace is the logical build environment formed by the main repository and the external repositories available to the build. It is neither a directory that contains those repositories nor the legacy WORKSPACE file. Bazel resolves module dependencies and makes their repositories available. Module extensions can create more repositories. You explicitly import selected ones with use_repo(). The apparent name used to address an external repository can depend on the repository mapping of the repository containing the label. This distinction becomes relevant when working with external dependencies and labels (0.2.1 Label Anatomy).