Configuring Bazel's Credential Helper

Configuring Bazel to authenticate against external services like Remote Caching, Remote Execution, a Build Event Service, or external repositories like http_archive or http_file has historically been challenging for many for users. However as of Bazel 5.4.0, Credential Helpers provide a simple, extensible, and secure way to inject credentials into a build.

The primary flag for configuring Credential Helpers is --credential_helper (also known as --experimental_credential_helper before Bazel 7.0.0), which provides the following options:

• Exact Match, which specifies a scope in the form of a DNS name and a path to a Credential Helper, separated by =,

• Wildcard, which specifies a scope in the form of a DNS wildcard and a path to a Credential Helper, separated by =, and

• Default, which specifies a path to a Credential Helper to use as fallback.

Note

Credential Helpers are configured using command-line options (flags). Given that most bazel invocations will need the credentials to interact with the remote system, we recommend putting them into your .bazelrc file. However, it's also possible to specify them directly on the command-line.

Exact Match

This type of Credential Helper is scoped to the exact DNS name specified on the command-line, without subdomains. It takes precedence over any other Credential Helper or authentication mechanisms for the provided scope (DNS name).

Example

common --credential_helper=example.com=/path/to/helper/for/example.com
common --credential_helper=bucket.s3.us-east-1.amazonaws.com=/path/to/helper/for/aws-s3

Wildcard

Similarly to exact match, this type of Credential Helper applies to a specific DNS name. However, the scope of wildcards also include subdomains of the specified DNS name. It takes precedence over the default Credential Helper and other authentication mechanisms, but not over exact match.

Example

common --credential_helper=*.example.com=/path/to/helper/for/example.com
common --credential_helper=*.foo.example.com=/path/to/helper/for/example.com
common --credential_helper=*.s3.us-east-1.amazonaws.com=/path/to/helper/for/aws-s3

In this example, Bazel will use /path/to/helper/for/example.com for example.com and all its subdomains except for foo.example.com and its subdomains, which has its own Credential Helper.

Default

This type of Credential Helper specifies a fallback to use when there's no Credential Helper with a scope matching the URI to access. It takes precedence over any other authentication mechanism, but not over other Credential Helpers such as exact match or wildcard.

Example

common --credential_helper=/path/to/default/helper