From 32005b9a591104b9fb3c616418286b878a9bf5ca Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Tue, 4 Aug 2026 11:17:00 +0100 Subject: [PATCH 1/3] DOC-2303: Add Antora GitHub auth prerequisites to README Co-Authored-By: Claude Fable 5 --- README.adoc | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.adoc b/README.adoc index 1da74fee61..1d4585b393 100644 --- a/README.adoc +++ b/README.adoc @@ -60,6 +60,23 @@ Check the open docs issues. If you find an issue you'd like to work on: - If the issue is already assigned to someone else, please consider another one. - If the issue is unassigned, add a comment expressing your interest in working on it. +== Prerequisites: GitHub authentication + +The Antora playbook in this repository fetches content from private GitHub repositories (`cloud-docs`, `rp-connect-docs`, and `adp-docs`), so building the site requires a GitHub token — even for read-only builds. + +IMPORTANT: Antora does not use git credential helpers (such as the `gh` CLI helper or the macOS keychain), so this step is required even if `git clone` already works on your machine. Antora reads credentials only from the `GIT_CREDENTIALS` environment variable or the `~/.git-credentials` file. + +One-time setup using the https://cli.github.com[GitHub CLI]: + +```bash +echo "https://$(gh auth token):@github.com" >> ~/.git-credentials +chmod 600 ~/.git-credentials +``` + +If you don't use the GitHub CLI, https://github.com/settings/personal-access-tokens/new[create a fine-grained personal access token] with `Contents: Read-only` permission on the `redpanda-data` doc repositories and use it in place of `$(gh auth token)`. + +NOTE: Tokens from `gh auth token` rotate when you sign in to the GitHub CLI again. If Antora builds start failing with `401` or `404` errors on remote content sources, remove the stale `github.com` line from `~/.git-credentials` and re-run the setup command. + == Local development If you want to run the website locally, install and update the packages: From 6a7e75e7cd5549605640772daa73bfd3912a077a Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Tue, 4 Aug 2026 12:00:41 +0100 Subject: [PATCH 2/3] DOC-2303: Address CodeRabbit and style review feedback Fix repo lists to match each playbook, soften credential-source wording, add XDG fallback path, remove em dash, use verb-phrase heading, add new-tab carets to external links. Co-Authored-By: Claude Fable 5 --- README.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.adoc b/README.adoc index 1d4585b393..a4fba33c98 100644 --- a/README.adoc +++ b/README.adoc @@ -60,20 +60,20 @@ Check the open docs issues. If you find an issue you'd like to work on: - If the issue is already assigned to someone else, please consider another one. - If the issue is unassigned, add a comment expressing your interest in working on it. -== Prerequisites: GitHub authentication +== Set up GitHub authentication -The Antora playbook in this repository fetches content from private GitHub repositories (`cloud-docs`, `rp-connect-docs`, and `adp-docs`), so building the site requires a GitHub token — even for read-only builds. +The Antora playbook in this repository fetches content from other GitHub repositories, including the private `cloud-docs` and `rp-connect-docs` repositories and this repository's own versioned branches, so building the site requires a GitHub token, even for read-only builds. -IMPORTANT: Antora does not use git credential helpers (such as the `gh` CLI helper or the macOS keychain), so this step is required even if `git clone` already works on your machine. Antora reads credentials only from the `GIT_CREDENTIALS` environment variable or the `~/.git-credentials` file. +IMPORTANT: Antora does not use git credential helpers (such as the `gh` CLI helper or the macOS keychain), so you must complete this step even if `git clone` already works on your machine. By default, Antora reads credentials from the `GIT_CREDENTIALS` environment variable or the `~/.git-credentials` file (with a fallback to `$XDG_CONFIG_HOME/git/credentials`). -One-time setup using the https://cli.github.com[GitHub CLI]: +To store credentials one time using the https://cli.github.com[GitHub CLI^], run: ```bash echo "https://$(gh auth token):@github.com" >> ~/.git-credentials chmod 600 ~/.git-credentials ``` -If you don't use the GitHub CLI, https://github.com/settings/personal-access-tokens/new[create a fine-grained personal access token] with `Contents: Read-only` permission on the `redpanda-data` doc repositories and use it in place of `$(gh auth token)`. +If you don't use the GitHub CLI, https://github.com/settings/personal-access-tokens/new[create a fine-grained personal access token^] with `Contents: Read-only` permission on the `redpanda-data` doc repositories and use it in place of `$(gh auth token)`. NOTE: Tokens from `gh auth token` rotate when you sign in to the GitHub CLI again. If Antora builds start failing with `401` or `404` errors on remote content sources, remove the stale `github.com` line from `~/.git-credentials` and re-run the setup command. From 9891f863ec41315ac1b365ca2821056a755b1ddd Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Tue, 4 Aug 2026 12:04:19 +0100 Subject: [PATCH 3/3] DOC-2303: Document gh auth login prerequisite and PAT repo selection Co-Authored-By: Claude Fable 5 --- README.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.adoc b/README.adoc index a4fba33c98..e9320f7d55 100644 --- a/README.adoc +++ b/README.adoc @@ -66,14 +66,14 @@ The Antora playbook in this repository fetches content from other GitHub reposit IMPORTANT: Antora does not use git credential helpers (such as the `gh` CLI helper or the macOS keychain), so you must complete this step even if `git clone` already works on your machine. By default, Antora reads credentials from the `GIT_CREDENTIALS` environment variable or the `~/.git-credentials` file (with a fallback to `$XDG_CONFIG_HOME/git/credentials`). -To store credentials one time using the https://cli.github.com[GitHub CLI^], run: +If you aren't already signed in to the https://cli.github.com[GitHub CLI^], run `gh auth login` first. Then store credentials one time: ```bash echo "https://$(gh auth token):@github.com" >> ~/.git-credentials chmod 600 ~/.git-credentials ``` -If you don't use the GitHub CLI, https://github.com/settings/personal-access-tokens/new[create a fine-grained personal access token^] with `Contents: Read-only` permission on the `redpanda-data` doc repositories and use it in place of `$(gh auth token)`. +If you don't use the GitHub CLI, https://github.com/settings/personal-access-tokens/new[create a fine-grained personal access token^]: select `redpanda-data` as the resource owner, grant the token access to the private doc repositories, and set the `Contents` permission to read-only. Use the token in place of `$(gh auth token)`. Organization approval may be required before the token becomes active. NOTE: Tokens from `gh auth token` rotate when you sign in to the GitHub CLI again. If Antora builds start failing with `401` or `404` errors on remote content sources, remove the stale `github.com` line from `~/.git-credentials` and re-run the setup command.