feat(docs): add authentication guides for GitHub, GCS and AWS S3

Add detailed documentation for authenticating to GitHub, Google Cloud 
Storage (GCS) and AWS S3 using credential helpers. Include recommended methods, 
configuration steps, and troubleshooting tips to enhance user experience 
and streamline access to resources.

README.md

@@ -44,9 +44,9 @@ sequenceDiagram
 
 The following providers are supported as of today:
 
-- AWS S3
-- Google Cloud Storage
-- GitHub
+- [AWS S3](/docs/providers/s3.md)
+- [Google Cloud Storage (GCS)](/docs/providers/gcs.md)
+- [GitHub](/docs/providers/github.md)
 
 ## Installation and usage
 
@@ -86,6 +86,8 @@ You can also configure the helper to be used for every domain (`--credential_hel
 
 Now is a good time to install the credential helper. Simply run `bazel run @tweag-credential-helper//installer` to add the binary to your system. This step needs to be performed once per user.
 
+Follow the [provider-specific documentation](/docs/providers/) to ensure you can authenticate to the service.
+
 ## Configuration
 
 You can use environment variables to configure the helper.

docs/providers/gcs.md

@@ -0,0 +1,51 @@
+# Google Cloud Storage (GCS) Authentication
+
+This document explains how to setup your system for authenticating to Google Cloud Storage (GCS) using the credential helper to download objects.
+
+## IAM Setup
+
+In order to access data from a bucket, you need a Google Cloud user- or service account with read access to the objects you want to access (`storage.objects.get`). No other permissions are needed.
+Refer to [Google's documentation][gcs-iam] for more information.
+
+
+## Authentication Methods
+
+### Option 1: Using gcloud CLI as a regular user (Recommended)
+
+1. Install the [Google Cloud SDK][gcloud-install]
+2. Run:
+   ```bash
+   gcloud auth application-default login
+   ```
+3. Follow the browser prompts to authenticate
+
+### Option 2: Using a Service Account Key, OpenID Connect or other authentication mechanisms
+
+1. Follow [Google's documentation][google-cloud-auth] for choosing and setting up your method of choice
+2. Ensure your method of choice sets the [Application Default Credentials (ADC)][adc] environment variable (`GOOGLE_APPLICATION_CREDENTIALS`)
+3. Alternatively, check that the credentials file is in a well-known location (`$HOME/.config/gcloud/application_default_credentials.json`)
+
+## Configuration
+
+Add to your `.bazelrc`:
+
+```
+common --credential_helper=storage.googleapis.com=%workspace%/tools/credential-helper
+```
+
+## Troubleshooting
+
+### HTTP 401 or 403 error codes
+
+```
+ERROR: Target parsing failed due to unexpected exception: java.io.IOException: Error downloading [https://storage.googleapis.com/...] to ...: GET returned 403 Forbidden
+```
+
+First, verify your credentials are valid: `gcloud auth application-default print-access-token`.
+Then ensure the user you are logged in as has access to the bucket using `gsutil cp gs://<BUCKET_NAME>/<OBJECT> ./<OUTPUT_FILENAME>` and check if the credential helper is configured in `.bazelrc` like this: `--credential_helper=storage.googleapis.com=%workspace%/tools/credential-helper`.
+
+[adc]: https://cloud.google.com/docs/authentication/provide-credentials-adc
+[api-explorer-objects-get]: https://cloud.google.com/storage/docs/json_api/v1/objects/get
+[gcloud-install]: https://cloud.google.com/sdk/docs/install
+[gcs-iam]: https://cloud.google.com/storage/docs/access-control/iam-permissions
+[google-cloud-auth]: https://cloud.google.com/docs/authentication

docs/providers/github.md

@@ -0,0 +1,42 @@
+# GitHub Authentication
+
+This document explains how to setup your system for authenticating to GitHub using the credential helper.
+The credential helper can be used to download any assets GitHub hosts, including [the git protocol via https][git-http], raw code files (`raw.githubusercontent.com/<org>/<repo>/<commit>/<file>`), patches (`github.com/<org>/<repo>/<commit>.patch`), source tarballs (`github.com/<org>/<repo>/archive/refs/tags/v1.2.3.tar.gz`), release assets (`github.com/<org>/<repo>/releases/download/v1.2.3/<file>`), and more.
+With credentials, you are also less likely to be blocked by GitHub rate limits, even when accessing public repositories.
+
+## Authentication Methods
+
+### Option 1: Using the GitHub CLI as a regular user (Recommended)
+
+With this setup, credentials are stored in a local file (`hosts.yml`) or in the user's keyring.
+
+1. Install the [GitHub CLI (`gh`)][gh-install]
+2. Login via `gh auth login`
+3. Follow the browser prompts to authenticate
+
+### Option 2: Authentication using a GitHub App, GitHub Actions Token or Personal Access Token (PAT)
+
+1. Setup your authentication method of choice
+2. Set the required environment variable (`GH_TOKEN` or `GITHUB_TOKEN`) when running Bazel (or other tools that access credential helpers)
+3. Alternatively, add the secret to the system keyring under the `gh:github.com` key.
+
+## Configuration
+
+Add to your `.bazelrc`:
+
+```
+common --credential_helper=github.com=%workspace%/tools/credential-helper
+common --credential_helper=raw.githubusercontent.com=%workspace%/tools/credential-helper
+```
+
+## Troubleshooting
+
+### HTTP 401 or 403 error codes
+
+When using a regular user account with the GitHub CLI, validate that the token did not expire: `gh auth status`.
+Otherwise, ensure that your token is still valid and has the required permissions for the resource you are trying to access.
+Personal access tokens and automatic GitHub Actions tokens are limited in what resources they can access.
+If possible, switch to a GitHub CLI token (regular user) or a GitHub App (CI or automated system) instead, since they have access to more resources.
+
+[gh-install]: https://github.com/cli/cli#installation
+[git-http]: https://git-scm.com/book/ms/v2/Git-on-the-Server-The-Protocols#_the_http_protocols

docs/providers/s3.md

@@ -0,0 +1,42 @@
+# AWS Simple Storage Service (S3)
+
+This document explains how to setup you system for authenticating to S3 using the credential helper.
+
+## IAM Setup
+
+In order to access data from a bucket, you need an AWS user- or service account with read access to the objects you want to access (`s3:GetObject`).
+Refer to the [AWS documentation][aws-iam] for more information.
+
+## Authentication Methods
+
+### Option 1: Using the AWS CLI and Single Sign On (SSO) as a regular user (Recommended)
+
+- Install the [AWS CLI][aws-install]
+- Follow the [documentation][aws-sso-login] for using `aws configure sso` and `aws sso login` to sign in
+- Follow the browser prompts to authenticate
+
+### Option 2: Authenticate with other methods
+
+AWS has a lot of ways to authenticate and the credential helper uses the official SDK. If you have more complex requirements, follow the [AWS documentation][aws-sdk-auth] to setup your method of choice.
+This may require you to set environment variables when using Bazel (or other tools).
+
+## Configuration
+
+Add to your `.bazelrc`:
+
+```
+common --credential_helper=s3.amazonaws.com=%workspace%/tools/credential-helper
+common --credential_helper=*.s3.amazonaws.com=%workspace%/tools/credential-helper
+```
+
+# Troubleshooting
+
+## HTTP 401 or 403 error codes
+
+When using the AWS CLI with SSO, check if you are still authenticated using `aws sts get-caller-identity `.
+Then ensure your user has access to the object you are trying to access using `aws s3 cp s3://<BUCKET_NAME>/<OBJECT> ./<OUTPUT_FILENAME>` and check if the credential helper is configured in `.bazelrc`.
+
+[aws-iam]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-iam.html
+[aws-install]: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html
+[aws-sso-login]: https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html
+[aws-sdk-auth]: https://docs.aws.amazon.com/sdkref/latest/guide/access.html