repository.md

Repository rules

Repository rules are Bazel rules that can be used in WORKSPACE files to import projects in external repositories. Repository rules may download projects and transform them by applying patches or generating build files.

The Gazelle repository provides three rules:

• go_repository downloads a Go project using either go mod download, a version control tool like git, or a direct HTTP download. It understands Go import path redirection. If build files are not already present, it can generate them with Gazelle.
• git_repository downloads a project with git. Unlike the native git_repository, this rule allows you to specify an "overlay": a set of files to be copied into the downloaded project. This may be used to add pre-generated build files to a project that doesn't have them.
• http_archive downloads a project via HTTP. It also lets you specify overlay files.

NOTE: git_repository and http_archive are deprecated in favor of the rules of the same name in @bazel_tools//tools/build_defs/repo:git.bzl and @bazel_tools//tools/build_defs/repo:http.bzl.

Repository rules can be loaded and used in WORKSPACE like this:

load("@bazel_gazelle//:deps.bzl", "go_repository")

go_repository(
    name = "com_github_pkg_errors",
    commit = "816c9085562cd7ee03e7f8188a1cfd942858cded",
    importpath = "github.com/pkg/errors",
)

Gazelle can add and update some of these rules automatically using the update-repos command. For example, the rule above can be added with:

$ gazelle update-repos github.com/pkg/errors

git_repository

git_repository(name, commit, overlay, remote, repo_mapping, tag)

NOTE: git_repository is deprecated in favor of the rule of the same name in @bazel_tools//tools/build_defs/repo:git.bzl.

git_repository downloads a project with git. It has the same features as the native git_repository rule, but it also allows you to copy a set of files into the repository after download. This is particularly useful for placing pre-generated build files.

Example

load("@bazel_gazelle//:deps.bzl", "git_repository")

git_repository(
    name = "com_github_pkg_errors",
    remote = "https://github.com/pkg/errors",
    commit = "816c9085562cd7ee03e7f8188a1cfd942858cded",
    overlay = {
        "@my_repo//third_party:com_github_pkg_errors/BUILD.bazel.in" : "BUILD.bazel",
    },
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
commit	The git commit to check out. Either commit or tag may be specified.	String	optional	""
overlay	A set of files to copy into the downloaded repository. The keys in this dictionary are Bazel labels that point to the files to copy. These must be fully qualified labels (i.e., @repo//pkg:name) because relative labels are interpreted in the checked out repository, not the repository containing the WORKSPACE file. The values in this dictionary are root-relative paths where the overlay files should be written. It's convenient to store the overlay dictionaries for all repositories in a separate .bzl file. See Gazelle's manifest.bzl_ for an example.	Dictionary: Label -> String	optional	{}
remote	The remote repository to download.	String	required
repo_mapping	In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension's implementation function).	Dictionary: String -> String	optional
tag	The git tag to check out. Either commit or tag may be specified.	String	optional	""

go_repository

go_repository(name, auth_patterns, build_config, build_directives, build_external, build_extra_args,
              build_file_generation, build_file_name, build_file_proto_mode, build_naming_convention,
              build_tags, canonical_id, commit, debug_mode, importpath,
              internal_only_do_not_use_apparent_name, local_path, patch_args, patch_cmds, patch_tool,
              patches, remote, replace, repo_mapping, sha256, strip_prefix, sum, tag, type, urls, vcs,
              version)

go_repository downloads a Go project and generates build files with Gazelle if they are not already present. This is the simplest way to depend on external Go projects.

When go_repository is in module mode, it saves downloaded modules in a shared, internal cache within Bazel's cache. It may be cleared with bazel clean --expunge. By setting the environment variable GO_REPOSITORY_USE_HOST_CACHE=1, you can force go_repository to use the module cache on the host system in the location returned by go env GOPATH. Alternatively, by setting the environment variable GO_REPOSITORY_USE_HOST_MODCACHE=1, you can force go_repository to use only the module cache on the host system in the location returned by go env GOMODCACHE.

Example

load("@bazel_gazelle//:deps.bzl", "go_repository")

# Download using "go mod download"
go_repository(
    name = "com_github_pkg_errors",
    importpath = "github.com/pkg/errors",
    sum = "h1:iURUrRGxPUNPdy5/HRSm+Yj6okJ6UtLINN0Q9M4+h3I=",
    version = "v0.8.1",
)

# Download automatically via git
go_repository(
    name = "com_github_pkg_errors",
    commit = "816c9085562cd7ee03e7f8188a1cfd942858cded",
    importpath = "github.com/pkg/errors",
)

# Download from git fork
go_repository(
    name = "com_github_pkg_errors",
    commit = "816c9085562cd7ee03e7f8188a1cfd942858cded",
    importpath = "github.com/pkg/errors",
    remote = "https://example.com/fork/github.com/pkg/errors",
    vcs = "git",
)

# Download via HTTP
go_repository(
    name = "com_github_pkg_errors",
    importpath = "github.com/pkg/errors",
    urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"],
    strip_prefix = "errors-816c9085562cd7ee03e7f8188a1cfd942858cded",
    type = "zip",
)

# Download major version suffixed via git
go_repository(
    name = "com_github_thediveo_enumflag_v2",
    commit = "0217df583bf3d37b92798602e5061b36556bcd38",
    importpath = "github.com/thediveo/enumflag/v2",
    remote = "https://github.com/thediveo/enumflag",
    vcs = "git",
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
auth_patterns	An optional dict mapping host names to custom authorization patterns. If a URL's host name is present in this dict the value will be used as a pattern when generating the authorization header for the http request. This enables the use of custom authorization schemes used in a lot of common cloud storage providers. The pattern currently supports 2 tokens: <login> and <password>, which are replaced with their equivalent value in the netrc file for the same host name. After formatting, the result is set as the value for the Authorization field of the HTTP request. Example attribute and netrc for a http download to an oauth2 enabled API using a bearer token: auth_patterns = { "storage.cloudprovider.com": "Bearer <password>" } netrc: machine storage.cloudprovider.com password RANDOM-TOKEN The final HTTP request would have the following header: Authorization: Bearer RANDOM-TOKEN	Dictionary: String -> String	optional	{}
build_config	A file that Gazelle should read to learn about external repositories before generating build files. This is useful for dependency resolution. For example, a go_repository rule in this file establishes a mapping between a repository name like golang.org/x/tools and a workspace name like org_golang_x_tools. Workspace directives like # gazelle:repository_macro are recognized. go_repository rules will be re-evaluated when parts of WORKSPACE related to Gazelle's configuration are changed, including Gazelle directives and go_repository name and importpath attributes. Their content should still be fetched from a local cache, but build files will be regenerated. If this is not desirable, build_config may be set to a less frequently updated file or None to disable this functionality.	Label	optional	"@bazel_gazelle_go_repository_config//:WORKSPACE"
build_directives	A list of directives to be written to the root level build file before Calling Gazelle to generate build files. Each string in the list will be prefixed with # automatically. A common use case is to pass a list of Gazelle directives.	List of strings	optional	[]
build_external	One of "external", "static" or "vendored". This sets Gazelle's -external command line flag. In "static" mode, Gazelle will not call out to the network to resolve imports. NOTE: This cannot be used to ignore the vendor directory in a repository. The -external flag only controls how Gazelle resolves imports which are not present in the repository. Use build_extra_args = ["-exclude=vendor"] instead.	String	optional	"static"
build_extra_args	A list of additional command line arguments to pass to Gazelle when generating build files.	List of strings	optional	[]
build_file_generation	One of "auto", "on", "off", "clean". Whether Gazelle should generate build files in the repository. In "auto" mode, Gazelle will run if there is no build file in the repository root directory. In "clean" mode, Gazelle will first remove any existing build files.	String	optional	"auto"
build_file_name	Comma-separated list of names Gazelle will consider to be build files. If a repository contains files named build that aren't related to Bazel, it may help to set this to "BUILD.bazel", especially on case-insensitive file systems.	String	optional	"BUILD.bazel,BUILD"
build_file_proto_mode	One of "default", "legacy", "disable", "disable_global" or "package". This sets Gazelle's -proto command line flag. See Directives for more information on each mode.	String	optional	""
build_naming_convention	Sets the library naming convention to use when resolving dependencies against this external repository. If unset, the convention from the external workspace is used. Legal values are go_default_library, import, and import_alias. See the gazelle:go_naming_convention directive in Directives for more information.	String	optional	"import_alias"
build_tags	This sets Gazelle's -build_tags command line flag.	List of strings	optional	[]
canonical_id	If the repository is downloaded via HTTP (urls is set) and this is set, restrict cache hits to those cases where the repository was added to the cache with the same canonical id.	String	optional	""
commit	If the repository is downloaded using a version control tool, this is the commit or revision to check out. With git, this would be a sha1 commit id. commit and tag may not both be set.	String	optional	""
debug_mode	Enables logging of fetch_repo and Gazelle output during succcesful runs. Gazelle can be noisy so this defaults to False. However, setting to True can be useful for debugging build failures and unexpected behavior for the given rule.	Boolean	optional	False
importpath	The Go import path that matches the root directory of this repository. In module mode (when version is set), this must be the module path. If neither urls nor remote is specified, go_repository will automatically find the true path of the module, applying import path redirection. If build files are generated for this repository, libraries will have their importpath attributes prefixed with this importpath string.	String	required
internal_only_do_not_use_apparent_name	Internal usage only	String	optional	""
local_path	If specified, go_repository will load the module from this local directory	String	optional	""
patch_args	Arguments passed to the patch tool when applying patches.	List of strings	optional	["-p0"]
patch_cmds	Commands to run in the repository after patches are applied.	List of strings	optional	[]
patch_tool	The patch tool used to apply patches. If this is specified, Bazel will use the specifed patch tool instead of the Bazel-native patch implementation.	String	optional	""
patches	A list of patches to apply to the repository after gazelle runs.	List of labels	optional	[]
remote	The VCS location where the repository should be downloaded from. This is usually inferred from importpath, but you can set remote to download from a private repository or a fork.	String	optional	""
replace	A replacement for the module named by importpath. The module named by replace will be downloaded at version and verified with sum. NOTE: There is no go_repository equivalent to file path replace directives. Use local_repository instead.	String	optional	""
repo_mapping	In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension's implementation function).	Dictionary: String -> String	optional
sha256	If the repository is downloaded via HTTP (urls is set), this is the SHA-256 sum of the downloaded archive. When set, Bazel will verify the archive against this sum before extracting it. CAUTION: Do not use this with services that prepare source archives on demand, such as codeload.github.com. Any minor change in the server software can cause differences in file order, alignment, and compression that break SHA-256 sums.	String	optional	""
strip_prefix	If the repository is downloaded via HTTP (urls is set), this is a directory prefix to strip. See [http_archive.strip_prefix].	String	optional	""
sum	A hash of the module contents. In module mode, go_repository will verify the downloaded module matches this sum. May only be set when version is also set. A value for sum may be found in the go.sum file or by running go mod download -json <module>@<version>.	String	optional	""
tag	If the repository is downloaded using a version control tool, this is the named revision to check out. commit and tag may not both be set.	String	optional	""
type	One of "zip", "tar.gz", "tgz", "tar.bz2", "tar.xz". If the repository is downloaded via HTTP (urls is set), this is the file format of the repository archive. This is normally inferred from the downloaded file name.	String	optional	""
urls	A list of HTTP(S) URLs where an archive containing the project can be downloaded. Bazel will attempt to download from the first URL; the others are mirrors.	List of strings	optional	[]
vcs	One of "git", "hg", "svn", "bzr". The version control system to use. This is usually determined automatically, but it may be necessary to set this when remote is set and the VCS cannot be inferred. You must have the corresponding tool installed on your host.	String	optional	""
version	If specified, go_repository will download the module at this version using go mod download. sum must also be set. commit, tag, and urls may not be set.	String	optional	""

http_archive

http_archive(name, overlay, repo_mapping, sha256, strip_prefix, type, urls)

NOTE: http_archive is deprecated in favor of the rule of the same name in @bazel_tools//tools/build_defs/repo:http.bzl.

http_archive downloads a project over HTTP(S). It has the same features as the native http_archive rule, but it also allows you to copy a set of files into the repository after download. This is particularly useful for placing pre-generated build files.

Example

load("@bazel_gazelle//:deps.bzl", "http_archive")

http_archive(
    name = "com_github_pkg_errors",
    urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"],
    strip_prefix = "errors-816c9085562cd7ee03e7f8188a1cfd942858cded",
    type = "zip",
    overlay = {
        "@my_repo//third_party:com_github_pkg_errors/BUILD.bazel.in" : "BUILD.bazel",
    },
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
overlay	A set of files to copy into the downloaded repository. The keys in this dictionary are Bazel labels that point to the files to copy. These must be fully qualified labels (i.e., @repo//pkg:name) because relative labels are interpreted in the checked out repository, not the repository containing the WORKSPACE file. The values in this dictionary are root-relative paths where the overlay files should be written. It's convenient to store the overlay dictionaries for all repositories in a separate .bzl file. See Gazelle's manifest.bzl_ for an example.	Dictionary: Label -> String	optional	{}
repo_mapping	In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension's implementation function).	Dictionary: String -> String	optional
sha256	The SHA-256 sum of the downloaded archive. When set, Bazel will verify the archive against this sum before extracting it. CAUTION: Do not use this with services that prepare source archives on demand, such as codeload.github.com. Any minor change in the server software can cause differences in file order, alignment, and compression that break SHA-256 sums.	String	optional	""
strip_prefix	A directory prefix to strip. See http_archive.strip_prefix.	String	optional	""
type	One of "zip", "tar.gz", "tgz", "tar.bz2", "tar.xz". The file format of the repository archive. This is normally inferred from the downloaded file name.	String	optional	""
urls	A list of HTTP(S) URLs where the project can be downloaded. Bazel will attempt to download the first URL; the others are mirrors.	List of strings	optional	[]