From 9f633a36f9af318b0aa68dd993b40bb722d86827 Mon Sep 17 00:00:00 2001
From: Douglas Thor <doug.thor@gmail.com>
Date: Wed, 3 Apr 2024 10:59:35 -0700
Subject: [PATCH] Docs

---
 docs/sphinx/pip.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/docs/sphinx/pip.md b/docs/sphinx/pip.md
index 34248d2d1..e73c0c6a5 100644
--- a/docs/sphinx/pip.md
+++ b/docs/sphinx/pip.md
@@ -82,3 +82,51 @@ https://blog.aspect.dev/bazel-can-write-to-the-source-folder
 to put a copy of the generated requirements.bzl into your project.
 Then load the requirements.bzl file directly rather than from the generated repository.
 See the example in rules_python/examples/pip_parse_vendored.
+
+
+(credential-helper)=
+## Credential Helper
+
+The "use Bazel downloader for python wheels" experimental feature includes support for the Bazel
+[Credential Helper][cred-helper-design].
+
+Your python artifact registry may provide a credential helper for you. Refer to your index's docs
+to see if one is provided.
+
+See the [Credential Helper Spec][cred-helper-spec] for details.
+
+[cred-helper-design]: https://github.com/bazelbuild/proposals/blob/main/designs/2022-06-07-bazel-credential-helpers.md
+[cred-helper-spec]: https://github.com/EngFlow/credential-helper-spec/blob/main/spec.md
+
+
+### Basic Example:
+
+The simplest form of a credential helper is a bash script that accepts an arg and spits out JSON to
+stdout. For a service like Google Artifact Registry that uses ['Basic' HTTP Auth][rfc7617] and does
+not provide a credential helper that conforms to the [spec][cred-helper-spec], the script might
+look like:
+
+```bash
+#!/bin/bash
+# cred_helper.sh
+ARG=$1  # but we don't do anything with it as it's always "get"
+
+# formatting is optional
+echo '{'
+echo '  "headers": {'
+echo '    "Authorization": ["Basic dGVzdDoxMjPCow=="]
+echo '  }'
+echo '}'
+```
+
+Configure Bazel to use this credential helper for your python index `example.com`:
+
+```
+# .bazelrc
+build --credential_helper=example.com=/full/path/to/cred_helper.sh
+```
+
+Bazel will call this file like `cred_helper.sh get` and use the returned JSON to inject headers
+into whatever HTTP(S) request it performs against `example.com`.
+
+[rfc7617]: https://datatracker.ietf.org/doc/html/rfc7617