Skip to content

DOC-2303: Add local-build GitHub auth instructions for private content repos #1879

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JakeSCahill wants to merge 3 commits into
base: main
Choose a base branch
from
Open

DOC-2303: Add local-build GitHub auth instructions for private content repos #1879

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
32005b9
DOC-2303: Add Antora GitHub auth prerequisites to README
JakeSCahill Aug 4, 2026
6a7e75e
DOC-2303: Address CodeRabbit and style review feedback
JakeSCahill Aug 4, 2026
9891f86
DOC-2303: Document gh auth login prerequisite and PAT repo selection
JakeSCahill Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

== Set up GitHub authentication

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 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:

```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^]: 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.

== Local development

If you want to run the website locally, install and update the packages:
Expand Down
Loading