4.9.1 Repository Rule Fundamentals

Repository rules are Bazel's loading-phase mechanism for making another repository exist. A repo rule takes attributes such as a URL, checksum, local path, or generated BUILD file, then materializes a directory tree that Bazel can address with labels like @repo//pkg:target.¹ Build rules create targets inside an already-loaded package. Repository rules prepare the external repository whose packages Bazel can then load and analyze.²

A Repo Rule Materializes A Directory Tree

An external repository is just a repository-shaped directory tree: source files plus Bazel boundary files and packages. Bazel fetches that directory on demand when a label, dependency, or command needs something from it.³ The rule invocation is the definition of how to create that tree: download and extract an archive, symlink a local directory, clone a Git repository, resolve Maven artifacts, or generate BUILD files around host-specific content.⁴

That makes repository rules feel similar to build rules, but their output is not a target's declared file. Their output is an entire repository namespace. Once materialized, normal labels inside that repository work the same way as labels in the main repository: a package is still a package, a target is still a target, and @repo//tools:compiler means "the target compiler in package tools of the apparent repository repo."⁵

The smallest custom repository rule has the same skeleton as other Starlark extension points: define an implementation function, then assign the result of repository_rule() to a global symbol.⁶

def _hello_repo_impl(ctx):
    ctx.file("hello.txt", ctx.attr.message + "\n")
    ctx.file("BUILD.bazel", 'exports_files(["hello.txt"])')

hello_repo = repository_rule(
    implementation = _hello_repo_impl,
    attrs = {
        "message": attr.string(mandatory = True),
    },
)

In a Bzlmod project, a user can expose that rule in MODULE.bazel with use_repo_rule() and call it to create a repository.⁷

hello_repo = use_repo_rule("//:repo.bzl", "hello_repo")

hello_repo(
    name = "hello",
    message = "Hello, repository rules",
)

This example assumes repo.bzl sits in a Bazel package. An empty root BUILD.bazel file is enough to make the //:repo.bzl label resolvable.⁷

The implementation receives repository_ctx, not the analysis-phase ctx from rule(). That context can write files, create symlinks, expand templates, download files, extract archives, execute host commands, read environment variables, and watch files that should trigger re-fetching.⁸

It Runs When The Repository Is Needed

A repository rule implementation runs during loading, on demand when Bazel needs a target from that repository. Materialization must finish before Bazel can load packages and targets from it.⁹ It does not run in the action sandbox, does not create actions, and cannot depend on files produced by normal build actions.¹⁰ If the repo rule needs a helper tool, it must get that tool in loading-phase terms: download a prebuilt binary, use a host command deliberately, or structure the integration so the generated repository exposes targets for the later build graph.¹¹

That lifecycle difference is the reason repository rules are powerful and easy to misuse. They can reach the network and host filesystem outside the ordinary action model. Bazel therefore cannot automatically notice every possible change that might affect the generated repository. It re-fetches a repository when tracked inputs change: the repo rule attributes, the Starlark implementation, environment variables read through repository_ctx.getenv() (preferred), watched paths, or an explicit forced fetch.¹² The legacy repository_rule(environ = [...]) declaration is deprecated in favor of getenv(), which is covered later in 4.9.6 getenv() vs os.environ Pitfall alongside file watching in 4.9.7 watch() / watch_tree() File Dependencies.

Built-In Rules Are The Default Starting Point

Most projects should start with built-in repository rules instead of custom code. http_archive downloads a compressed archive, verifies it, extracts it, and makes the repository's targets available.¹³ http_file and http_jar handle single-file downloads.¹⁴ local_repository exposes a local directory that already contains Bazel files, while new_local_repository creates Bazel files around a local directory that does not already have them.¹⁵

git_repository and new_git_repository also exist, but http_archive is the recommended default: Git rules depend on system git, support only one remote instead of mirror URLs, and do not work with the repository cache in the same way.¹⁶ 4.9.2 Archive Downloads & Integrity explains the archive and integrity trade-offs in detail. Here, the decision rule is simple: choose the repository rule whose materialization model is already closest to the dependency you need.

Bzlmod Decides. Repo Rules Materialize

Bzlmod and repository rules solve different parts of external dependency handling. Module resolution starts from MODULE.bazel, reads the transitive module graph, selects versions, and determines which repositories should be available.¹⁷ Repository rules are the lower-level materialization mechanism: they say how a particular repo directory is fetched, symlinked, or generated.¹⁸

Module extensions connect the two. An extension reads tags across the module graph and usually creates repositories by calling repo rules.¹⁹ For example, an extension for Maven, Go modules, or Cargo can aggregate the user's dependency declarations, resolve them with ecosystem-specific logic, then call repository rules to expose generated repositories to Bazel.²⁰ 4.10.1 Module Extension Fundamentals develops the extension model. For now, keep the distinction that a repository rule is the unit it calls to make a repo exist.

Design With The Boundary In Mind

Treat a repository rule as a boundary between Bazel's dependency graph and something outside it: a release archive, a local SDK, a language package manager, a system installation, or a generated toolchain repository. The best repo rules make that boundary explicit. They take clear attributes, verify downloaded bytes, generate predictable BUILD files, and record the host inputs that affect their output.²¹

The worst repo rules turn loading into an opaque bootstrap script. If the implementation shells out to tools from ambient PATH, reads untracked environment variables, follows mutable branches, or embeds a full external evaluator, the generated repository can differ across machines without Bazel knowing why.²² Those failure modes create the design pressure behind the rest of this section: integrity checks, custom rule APIs, reproducibility, watched inputs, hermetic host tooling, and non-incremental external evaluation.