From 422e5a8efb452db99ed69f633b29947c1954c8ec Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Tue, 4 Aug 2026 11:17:06 +0100 Subject: [PATCH 1/7] 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 bb0591b19..ba34ff0b6 100644 --- a/README.adoc +++ b/README.adoc @@ -58,6 +58,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 (`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 4121d65f93183d7ea5bd7839ce0fbd4600204c7f Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Tue, 4 Aug 2026 12:00:43 +0100 Subject: [PATCH 2/7] 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 ba34ff0b6..b7d71e45d 100644 --- a/README.adoc +++ b/README.adoc @@ -58,20 +58,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 (`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 `docs`, `rp-connect-docs`, and `adp-docs` repositories, 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 6f204095015f2659cd6553b55815c23bbf5edbf6 Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Tue, 4 Aug 2026 12:04:20 +0100 Subject: [PATCH 3/7] 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 b7d71e45d..ff0346f79 100644 --- a/README.adoc +++ b/README.adoc @@ -64,14 +64,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. From acc552cce0e2c1df89fa6a52ec0117ad015da4e8 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 4 Aug 2026 16:03:48 +0100 Subject: [PATCH 4/7] Address docs-team-standards review findings on the auth setup section - Fix the troubleshooting NOTE to quote Antora's real error text ("Content repository not found or credentials were rejected") instead of HTTP status codes that never appear in its output - Prevent a silently-ignored duplicate ~/.git-credentials entry by replacing any existing github.com line instead of blind-appending - Note that the credential is stored in plaintext, not just chmod 600'd - Add a cross-reference from Local development back to the auth prerequisite - Active voice for the org-approval sentence - Capitalize "Git" as a proper noun Co-Authored-By: Claude Sonnet 5 --- README.adoc | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/README.adoc b/README.adoc index ff0346f79..170c140c7 100644 --- a/README.adoc +++ b/README.adoc @@ -62,21 +62,27 @@ Check the open docs issues. If you find an issue you'd like to work on: The Antora playbook in this repository fetches content from other GitHub repositories, including the private `docs`, `rp-connect-docs`, and `adp-docs` repositories, 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 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`). +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`). -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: +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, replacing any existing `github.com` entry so an old, stale line can't silently win over the new one: ```bash -echo "https://$(gh auth token):@github.com" >> ~/.git-credentials +grep -v '@github\.com$' ~/.git-credentials 2>/dev/null > ~/.git-credentials.new || true +echo "https://$(gh auth token):@github.com" >> ~/.git-credentials.new +mv ~/.git-credentials.new ~/.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^]: 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. +This stores the token in plaintext. `chmod 600` limits the file to your user, but treat it as a secret — it's a live credential, not just a config file. -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. +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)`. Your organization may need to approve the token before it becomes active. + +NOTE: Tokens from `gh auth token` rotate when you sign in to the GitHub CLI again. If Antora builds start failing with `Content repository not found or credentials were rejected` on remote content sources, remove the stale `github.com` line from `~/.git-credentials` and re-run the setup command. == Local development +Local builds require the GitHub authentication set up in <> above. + If you want to run the website locally, install and update the packages: ```bash From 93da357bb730826df5492c1704997d319f2ae844 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 4 Aug 2026 17:00:47 +0100 Subject: [PATCH 5/7] Point auth setup and contribution link at the shared authoring guide Now that docs-site/meta-docs/AUTHORING.adoc centralizes this content (redpanda-data/docs-site#201) and every content repo needs the same GitHub auth setup for local builds, replace this repo's full copy with the same short pointer used everywhere else, and repoint the CONTRIBUTING.adoc link (now split/renamed) to AUTHORING.adoc. Supersedes the separate fix opened as #663. Related: https://redpandadata.atlassian.net/browse/DOC-2303 --- README.adoc | 23 +++-------------------- 1 file changed, 3 insertions(+), 20 deletions(-) diff --git a/README.adoc b/README.adoc index 170c140c7..f277ed779 100644 --- a/README.adoc +++ b/README.adoc @@ -51,7 +51,7 @@ If you are a Redpanda employee, submit doc issues in `redpanda-data/documentatio You have two options to contribute to the documentation: . Directly edit a page on GitHub by selecting **Make a contribution** > **Edit on GitHub** located at the bottom of a documentation page. -. Clone the docs repository to make changes locally on your machine. For a guide, see {url-playbook}/blob/main/meta-docs/CONTRIBUTING.adoc[Submit your first contribution]. +. Clone the docs repository to make changes locally on your machine. For a guide, see {url-playbook}/blob/main/meta-docs/AUTHORING.adoc[Build and test your changes locally]. Check the open docs issues. If you find an issue you'd like to work on: @@ -60,28 +60,11 @@ Check the open docs issues. If you find an issue you'd like to work on: == Set up GitHub authentication -The Antora playbook in this repository fetches content from other GitHub repositories, including the private `docs`, `rp-connect-docs`, and `adp-docs` repositories, 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 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`). - -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, replacing any existing `github.com` entry so an old, stale line can't silently win over the new one: - -```bash -grep -v '@github\.com$' ~/.git-credentials 2>/dev/null > ~/.git-credentials.new || true -echo "https://$(gh auth token):@github.com" >> ~/.git-credentials.new -mv ~/.git-credentials.new ~/.git-credentials -chmod 600 ~/.git-credentials -``` - -This stores the token in plaintext. `chmod 600` limits the file to your user, but treat it as a secret — it's a live credential, not just a config file. - -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)`. Your organization may need to approve the token before it becomes active. - -NOTE: Tokens from `gh auth token` rotate when you sign in to the GitHub CLI again. If Antora builds start failing with `Content repository not found or credentials were rejected` on remote content sources, remove the stale `github.com` line from `~/.git-credentials` and re-run the setup command. +Building this site locally fetches content from other GitHub repositories, including the private `docs`, `rp-connect-docs`, and `adp-docs` repositories, so you need a GitHub token even for read-only builds. See "Set up GitHub authentication" in the {url-playbook}/blob/main/meta-docs/AUTHORING.adoc[authoring guide]. == Local development -Local builds require the GitHub authentication set up in <> above. +Local builds require the GitHub authentication set up above. If you want to run the website locally, install and update the packages: From 059e5fa8729e38f08c6ab35225d53ab6faee22f6 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 4 Aug 2026 17:20:33 +0100 Subject: [PATCH 6/7] Repoint authoring guide link at cupboard instead of docs-site docs-site/meta-docs/AUTHORING.adoc has been deleted entirely (redpanda-data/docs-site#201) since every content repo's local build already requires the same private-repo GitHub access the guide assumed, making its old public location moot. The full guide now lives at redpanda-data/cupboard#677. Related: https://redpandadata.atlassian.net/browse/DOC-2303 --- README.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.adoc b/README.adoc index f277ed779..875376bb8 100644 --- a/README.adoc +++ b/README.adoc @@ -51,7 +51,7 @@ If you are a Redpanda employee, submit doc issues in `redpanda-data/documentatio You have two options to contribute to the documentation: . Directly edit a page on GitHub by selecting **Make a contribution** > **Edit on GitHub** located at the bottom of a documentation page. -. Clone the docs repository to make changes locally on your machine. For a guide, see {url-playbook}/blob/main/meta-docs/AUTHORING.adoc[Build and test your changes locally]. +. Clone the docs repository to make changes locally on your machine. For a guide, see https://github.com/redpanda-data/cupboard/blob/main/sales/customer-success/documentation/2026-08-04-authoring-guide.md[Build and test your changes locally]. Check the open docs issues. If you find an issue you'd like to work on: @@ -60,7 +60,7 @@ Check the open docs issues. If you find an issue you'd like to work on: == Set up GitHub authentication -Building this site locally fetches content from other GitHub repositories, including the private `docs`, `rp-connect-docs`, and `adp-docs` repositories, so you need a GitHub token even for read-only builds. See "Set up GitHub authentication" in the {url-playbook}/blob/main/meta-docs/AUTHORING.adoc[authoring guide]. +Building this site locally fetches content from other GitHub repositories, including the private `docs`, `rp-connect-docs`, and `adp-docs` repositories, so you need a GitHub token even for read-only builds. See "Set up GitHub authentication" in the https://github.com/redpanda-data/cupboard/blob/main/sales/customer-success/documentation/2026-08-04-authoring-guide.md[authoring guide]. == Local development From b91d3276cfd27254c78b0e175e8f6d36622f9cc0 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 4 Aug 2026 17:30:01 +0100 Subject: [PATCH 7/7] Repoint style guide link at docs-team-standards, drop stale copy docs-site/meta-docs/STYLE-GUIDE.adoc has been deleted (redpanda-data/docs-site#201) since redpanda-data/docs-team-standards already has a more current, canonical style guide. Related: https://redpandadata.atlassian.net/browse/DOC-2303 --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index 875376bb8..c96c41e11 100644 --- a/README.adoc +++ b/README.adoc @@ -20,7 +20,7 @@ This repository hosts the documentation content for Redpanda. The Redpanda docs are open source, and we welcome your contributions! -Before you add or edit content, consult the Redpanda https://github.com/redpanda-data/docs-site/blob/main/meta-docs/STYLE-GUIDE.adoc[Style Guide] for product documentation guidelines. +Before you add or edit content, consult the Redpanda https://github.com/redpanda-data/docs-team-standards/blob/main/resources/writing-style/style-guide.md[Style Guide] for product documentation guidelines. To contribute to the Redpanda docs, you have the following options: