Skip to content

Commit cdc7f2f

Browse files
authored
docs: Add basic docs for using credential helper with Bazel downloader of python packages (bazel-contrib#1834)
Add credential helper docs that were requested in bazel-contrib#1827 (comment)
1 parent 5667a86 commit cdc7f2f

File tree

1 file changed

+48
-0
lines changed

1 file changed

+48
-0
lines changed

docs/sphinx/pip.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,3 +82,51 @@ https://blog.aspect.dev/bazel-can-write-to-the-source-folder
8282
to put a copy of the generated requirements.bzl into your project.
8383
Then load the requirements.bzl file directly rather than from the generated repository.
8484
See the example in rules_python/examples/pip_parse_vendored.
85+
86+
87+
(credential-helper)=
88+
## Credential Helper
89+
90+
The "use Bazel downloader for python wheels" experimental feature includes support for the Bazel
91+
[Credential Helper][cred-helper-design].
92+
93+
Your python artifact registry may provide a credential helper for you. Refer to your index's docs
94+
to see if one is provided.
95+
96+
See the [Credential Helper Spec][cred-helper-spec] for details.
97+
98+
[cred-helper-design]: https://github.com/bazelbuild/proposals/blob/main/designs/2022-06-07-bazel-credential-helpers.md
99+
[cred-helper-spec]: https://github.com/EngFlow/credential-helper-spec/blob/main/spec.md
100+
101+
102+
### Basic Example:
103+
104+
The simplest form of a credential helper is a bash script that accepts an arg and spits out JSON to
105+
stdout. For a service like Google Artifact Registry that uses ['Basic' HTTP Auth][rfc7617] and does
106+
not provide a credential helper that conforms to the [spec][cred-helper-spec], the script might
107+
look like:
108+
109+
```bash
110+
#!/bin/bash
111+
# cred_helper.sh
112+
ARG=$1 # but we don't do anything with it as it's always "get"
113+
114+
# formatting is optional
115+
echo '{'
116+
echo ' "headers": {'
117+
echo ' "Authorization": ["Basic dGVzdDoxMjPCow=="]
118+
echo ' }'
119+
echo '}'
120+
```
121+
122+
Configure Bazel to use this credential helper for your python index `example.com`:
123+
124+
```
125+
# .bazelrc
126+
build --credential_helper=example.com=/full/path/to/cred_helper.sh
127+
```
128+
129+
Bazel will call this file like `cred_helper.sh get` and use the returned JSON to inject headers
130+
into whatever HTTP(S) request it performs against `example.com`.
131+
132+
[rfc7617]: https://datatracker.ietf.org/doc/html/rfc7617

0 commit comments

Comments
 (0)