4.9.9 Credential Helper Protocol

A credential helper is the authentication hook for Bazel's downloader. Instead of putting tokens in BUILD files, repository rule attributes, or command-line headers, you configure a helper program for the DNS names Bazel downloads from. When a matching download needs credentials, Bazel asks that helper for HTTP headers and keeps the secret-handling logic outside the build graph.¹

Where It Sits

Repository rules such as http_archive, http_file, and custom rules that call repository_ctx.download() already have a privileged place in the build: they run while external repositories are being materialized, before ordinary analysis actions and before execution sandboxing. That is why earlier items in 4.9 Repository Rules stress hashes, repository cache behavior, and explicit host interactions.

Credential helpers extend that downloader path. They are not a new dependency mechanism, and they do not replace sha256 or integrity. The downloaded bytes still need an expected hash so Bazel can reuse the repository cache safely. The helper only supplies the request headers needed to reach a protected URL.² With a known hash, Bazel can check the repository cache first and avoid the network entirely when the file is already present.³

Private fetches should still go through repository rules rather than action-time shell downloads. 4.9.2 Archive Downloads & Integrity covers that archive-fetching contract. This article adds the narrower auth piece: once the URL and expected bytes are modeled, the downloader can ask a helper for credentials when needed.⁴

Scoping Helpers

Configure helpers with --credential_helper. There are three forms: exact DNS match, wildcard match, and a default fallback.⁵

# .bazelrc
common --credential_helper=downloads.example.com=%workspace%/tools/example-helper
common --credential_helper=*.corp.example.com=%workspace%/tools/corp-helper
common --credential_helper=%workspace%/tools/default-helper

An exact match applies only to that DNS name and takes precedence over other helpers for that host. A wildcard match covers the configured DNS name and its subdomains, while still losing to an exact helper for the same host. A default helper is the fallback when no exact or wildcard scope matches.⁶

Prefer putting this configuration in the workspace .bazelrc when the whole repository needs the same authenticated endpoints. That makes private fetching part of project invocation policy instead of tribal shell setup.⁷ It also keeps the helper path reviewable: a credential helper is executable code, so treat changes to it like changes to any other authentication boundary.

The Protocol

The helper is just a program with a small request/response contract. Bazel invokes the helper with the get command, passes the request URI on standard input as JSON, and expects JSON on standard output containing HTTP headers.⁸

For a GCS-backed dependency, the helper can obtain an access token from gcloud and return an authorization header:

{"headers":{"Authorization":["Bearer ${TOKEN}"]}}

Bazel then attaches those headers to the downloader request.⁹ If the request fails or returns unexpected content, credentials are invalidated and the helper can be invoked again.¹⁰

This shape is intentionally domain-oriented. The helper decides how to talk to the real credential source: cloud CLI, OS keychain, metadata service, short-lived token broker, or vendor SDK. Bazel does not need to learn every provider-specific login flow. It only needs the headers for this request.

The Tweag implementation shows how that small protocol grows without widening Bazel's contract: a short-lived client delegates provider lookup and caching to an in-memory agent, while examples/customized/ replaces the built-in provider and cache behind documented Go interfaces.¹¹ Start from the provider docs and the full consumer example. Use agent, cache, and authentication packages only to diagnose or extend the helper itself.

Why Not Just Use Headers In .bazelrc?

Bazel has several older or narrower authentication paths. The built-in HTTP repository rules expose netrc and auth_patterns, where values from a .netrc file are formatted into an Authorization header for matching hosts.¹² Repository-rule authors can also use helper utilities such as get_auth() and use_netrc() to turn .netrc data into an auth dict for repository_ctx.download().¹³ For non-secret protocol requirements, repository_ctx.download() and download_and_extract() also accept a headers dict directly.¹⁴

Those mechanisms are still useful. For example, custom headers let a repository rule request a Docker v2 manifest with an Accept header or issue range requests for stable archive segments.¹⁵ But a bearer token is different from an Accept header. The common failure mode is that command-line authentication flags such as --remote_header can show up in CI logs or Build Event Protocol UIs, and redaction is hard to make universal across all header-like flags.¹⁶

Credential helpers move the secret retrieval step into a separate binary and keep the configured Bazel flag focused on which helper handles which domain, not on the token value itself.¹⁷ That is the same design reason Git and Docker grew credential helpers: the build tool should delegate provider-specific secret lookup instead of growing a built-in authentication matrix.¹⁸

Designing A Helper Setup

Start from the endpoint, not from the token. Ask which hosts Bazel will contact during repository fetching and give each sensitive domain the narrowest helper scope that works. storage.googleapis.com is a good concrete example: rules_gcs configures Bazel to use a workspace-local helper only for that host, so private GCS object downloads get credentials without making the helper responsible for every URL Bazel may fetch.¹⁹

Keep these design rules in review:

• Hash every downloaded artifact with sha256 or integrity. The helper authenticates the request, not the content.
• Scope helpers by DNS name instead of using a default helper unless most downloads really share one credential authority.
• Do not pass long-lived bearer tokens through .bazelrc, CI command lines, or repository rule attributes.
• Use direct headers only for protocol negotiation or other non-secret request metadata.
• Keep helper binaries and scripts under normal code review, and prefer vendor-provided helpers or small wrappers over ad hoc shell that prints tokens.