4.9.2 Archive Downloads & Integrity

Bazel's safest external-dependency path is a small contract: download this exact archive, verify these exact bytes, extract them into an external repository, and expose them through generated or overlaid BUILD files. That contract is what lets repository rules participate in reproducible builds even though they run during loading and can reach the network outside ordinary action sandboxing.¹

The Archive Contract

For custom repository rules, the core API is repository_ctx.download() for a file and repository_ctx.download_and_extract() for an archive. Both accept one URL or a list of mirror URLs, can verify either sha256 or Subresource Integrity integrity, and return the computed hashes after a successful download.² The built-in http_archive, http_file, and http_jar rules are the higher-level versions most users see first: http_archive downloads a compressed archive, decompresses it, and makes its targets available as a repository.³

A minimal custom rule often looks like this shape:

def _sdk_repo_impl(rctx):
    rctx.download_and_extract(
        url = rctx.attr.urls,
        sha256 = rctx.attr.sha256,
        strip_prefix = rctx.attr.strip_prefix,
    )
    rctx.file("BUILD.bazel", rctx.attr.build_file_content)

The SDK name is incidental. The pattern is to expose urls, sha256, and layout decisions such as strip_prefix as attributes of the repository rule rather than hide them in shell script state. A Go toolchain archive is the canonical example: urls for mirrors, sha256 for the expected checksum, download_and_extract() to unpack, and a template-generated BUILD file to make the extracted tree usable by Bazel.⁴

strip_prefix is not the only extraction control. repository_ctx.download_and_extract() and repository_ctx.extract() also accept strip_components, which removes a fixed number of leading path components and is mutually exclusive with strip_prefix.² For custom repository rules, rename_files can rename archive entries before prefix stripping, which is useful for problematic filenames or case-insensitive filesystem collisions.²

The Hash Is Both Security And Cache Key

sha256 and integrity are not decorative. The official API docs call it a security risk to omit the checksum because remote files can change. At best, omitting it makes the build non-hermetic.² The same checksum is also what lets Bazel avoid network access: when a hash is supplied, Bazel first checks the repository cache for that file, downloads only if it is missing, and adds a successful download back to the cache.²

That means a good archive dependency gets two properties at once. It rejects unexpected bytes, and it can be reused across local workspaces and Bazel invocations without asking the upstream server again. A repository rule that shells out to wget inside a genrule gets neither property in the same structured way: Bazel does not know the action is an external fetch, bazel fetch and bazel vendor cannot manage it as a repository dependency, credentials tend to leak into build files, the tool dependency is undeclared, and Bazel's downloader cache is bypassed.⁵

There is one subtle cache-safety detail for rule authors: when sha256 or integrity is user-specified, the repository_ctx docs recommend setting an explicit canonical_id.² The built-in HTTP repository rules use URL-derived canonical IDs by default so that changing URLs without changing the hash is harder to miss. Otherwise, a stale local cache entry can hide a bad update until another machine tries to fetch from scratch.³

Prefer Archives To Git Checkouts

git_repository is useful when an archive genuinely is not available, but it is a weaker default. The official Git repository rule docs explicitly prefer http_archive: Git repository rules depend on system git(1), support only a single remote rather than a mirror list, and do not work with the repository cache the way http_archive does.⁶ Branches and tags are also not the same as immutable bytes. The rule may return reproducible parameters for the commit it checked out, but the fetch still depends on Git behavior and server support.⁶

Stable archive selection matters even when the URL is HTTPS and the hash is present. The Bzlmod migration guide warns that GitHub-generated source archives under /archive/... are not checksum-stable and recommends uploading release artifacts under /releases/download/... instead.⁷ BCR-facing infrastructure made the same lesson part of dependency hygiene: 3.1.6 BCR Infrastructure covers registry mirrors, source.json, and why generated tarballs are a fragile source artifact.

portable-ruby is a concrete release-side example: it publishes suffixed, platform-specific interpreter archives intended for checksum-pinned downstream use, and attaches provenance before publication.⁸ Treat its immutability statement as release policy rather than a substitute for verification—the workflow can upload with --clobber, so consumers still need to pin and check the exact archive bytes.

Large binary content has another trap. A git_repository clone does not solve Git LFS by itself. One real-world Open Image Denoise bazelization had to clone pretrained weights without Git LFS because Bazel's git_repository rule did not support the LFS-backed dependency they needed.⁹ For large binary payloads, prefer a release artifact, object-store artifact, or rule-specific downloader path whose bytes and checksum are explicit.

Mirrors, Auth, And Policy Hooks

Mirror lists belong in the dependency contract. http_archive and repository_ctx.download() accept multiple URLs for the same file, and the HTTP rule docs say the list is tried in order until one succeeds, so local or company mirrors can be placed first.^2,3 Registry-backed dependencies use the same archive-with-hash principle, but their source.json and registry mirror mechanics belong in 3.1.6 BCR Infrastructure. At the repository-rule layer, the lesson is to keep custom fetches on Bazel's downloader path instead of inventing a parallel one.¹⁰

Authentication should stay in the downloader layer, not in BUILD files or generated shell commands. http_archive supports auth_patterns with .netrc, while repository_ctx.download() accepts auth and headers parameters.^2,3 Bazel credential helpers extend that model for dynamic credentials: Bazel can invoke a domain-scoped helper, pass the URL on stdin, and use returned HTTP headers for the request, avoiding hard-coded secrets in repository declarations.⁵ The detailed protocol and scoping belong in 4.9.9 Credential Helper Protocol.

The same archive-fetching contract also gives infrastructure teams policy hooks. The external dependency FAQ recommends internal mirrors for mirror.bazel.build and GitHub source archives, using --downloader_config or --module_mirrors, or a prepopulated download cache to avoid live Internet access for source archives.¹¹ The custom-headers work in Bazel 7.1 made repository_ctx.download(headers = ...) usable for cases such as Docker registries that require an Accept header or Alpine packages that require Range requests, allowing rules to stay on Bazel's downloader instead of falling back to curl.¹² Remote downloader support takes this further by routing downloads through a gRPC proxy or pre-seeded cache, which is why it is treated separately in 4.9.10 Remote Downloader.⁵

What To Encode In A Repository Rule

The practical rule is simple: make the archive bytes the unit of truth. Put the URL list, checksum, extraction layout, archive type when inference is ambiguous, and any auth/header policy in the rule's declared inputs. Generate BUILD files after extraction, but do not let the generated repository depend on ambient network state, local tools, or mutable branch heads.

For built-in http_archive, review these attributes first:

Attribute	Why it matters
urls	Ordered mirrors for the same file. Put controlled mirrors before upstream.
sha256 or integrity	Verifies bytes and enables repository-cache reuse.
canonical_id	Narrows cache hits so URL/hash update mistakes are easier to catch.
strip_prefix / strip_components / add_prefix	Normalizes archive layout before BUILD files see it. Use only one of strip_prefix and strip_components.
remote_patches / remote_file_urls	Keeps fetched overlays and patches hash-checked too.
auth_patterns / netrc	Keeps authentication out of BUILD-file command strings.