DOC-2303: Add local-build GitHub auth instructions for private content repos - #661
DOC-2303: Add local-build GitHub auth instructions for private content repos#661JakeSCahill wants to merge 7 commits into
Conversation
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughREADME.adoc adds instructions for authenticating Antora against private GitHub content sources. It covers GitHub CLI credential setup, Estimated code review effort: 1 (Trivial) | ~2 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.adoc`:
- Line 63: Update the README sentence describing Antora’s private GitHub
dependencies to match the repository names in local-antora-playbook.yml,
including every listed private source; alternatively, replace the parenthetical
repository list with “private GitHub content sources.”
- Line 65: Update the credential-source statement in the README to present
GIT_CREDENTIALS and ~/.git-credentials as examples rather than the exclusive
supported sources. Qualify the wording to acknowledge other Antora-supported
sources, including GIT_CREDENTIALS_PATH, playbook credential paths or contents,
URL credentials, and custom credential managers.
- Line 74: Update the fine-grained personal access token guidance in the README
to specify selecting redpanda-data as the resource owner and granting Contents:
Read-only access to docs, rp-connect-docs, and adp-docs, or all repositories in
that organization where applicable; mention that organization approval may be
required.
- Around line 67-70: Update the one-time GitHub CLI setup instructions near the
credential-writing command to include the prerequisite `gh auth login --hostname
github.com`, or explicitly require a successful `gh auth status` before running
`gh auth token`.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
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 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
Docs-team-standards review
Files reviewed: 1 (README.adoc, +17/−0)
Overall assessment: Technically accurate and style-compliant. No critical issues. Every factual claim I could check verified clean against Antora 3.1.2, the playbook, and the ticket. The real gaps are outside this file: two repos/guides in the same workflow that no PR in the set covers.
What this PR does
Adds a == Set up GitHub authentication section documenting the one-time ~/.git-credentials setup writers need once the content repos go private. Covers why gh/keychain auth isn't enough, the gh auth token command, a fine-grained PAT fallback, and a rotation troubleshooting note. Four sibling PRs carry the same section: docs#1879, rp-connect-docs#476, adp-docs#186, docs-site#200.
Jira ticket alignment
Ticket: DOC-2303 — Make doc content repos private and add GitHub token auth to Antora builds
Addresses the ticket's README auth-instructions item. The ticket's private set (docs, cloud-docs, rp-connect-docs, adp-docs, with labs and docs-site staying public) matches this PR's repo list exactly, and the ticket's own note about isomorphic-git ignoring credential helpers matches the README's IMPORTANT block. Two items in the ticket's scope remain unaddressed by any PR in the set — see impact below.
Critical issues
None. Specifically verified rather than assumed:
- Repo list — cloud-docs'
local-antora-playbook.ymlfetchesdocs,docs-site,redpanda-labs,rp-connect-docs,adp-docs. The private subset is the three listed.cloud-docsitself isurl: ., so excluding it is right. I checked all five PRs against their own playbooks; each list is correct, including docs#1879's "this repository's own versioned branches" (docs fetches its ownv/*,shared,site-searchover HTTPS). - Credential mechanism — Antora's docs confirm:
GIT_CREDENTIALSenv var, then$HOME/.git-credentials, then$XDG_CONFIG_HOME/git/credentials; no credential helpers, no keychain. The "By default" hedge keeps the sentence accurate despiteGIT_CREDENTIALS_PATHalso existing. - Credential line format —
https://TOKEN:@github.comwith the trailing colon is exactly Antora's documented form. Easy to get wrong; it's right.
Suggestions
-
[README.adoc:76 — the NOTE] The troubleshooting string won't match what writers actually see. In
@antora/content-aggregator@3.1.2,transformGitCloneErrormaps status 401 toContent repository not found or credentials were rejected(or...or requires credentials) and 404 toContent repository not found. The digits401/404never appear in Antora's output, so anyone searching their terminal for "401" finds nothing.- Suggested: "If Antora builds start failing with
Content repository not found or credentials were rejectedon remote content sources, remove the stale…"
- Suggested: "If Antora builds start failing with
-
[README.adoc:70]
>>blind-appends. Git's ownstorehelper writes to the same file, so a writer who already has agithub.comline ends up with two — and the first match wins, so the new line silently does nothing. The NOTE gives the cure but not the prevention.- Suggested: precede the command with a check (
grep github.com ~/.git-credentials) and tell the reader to replace an existing line rather than add one.
- Suggested: precede the command with a check (
-
[README.adoc:70] No mention that the token is stored in plaintext. Antora's own docs call this out, and we're telling writers to mint a long-lived PAT.
chmod 600implies it without saying it. One clause would set expectations. -
[README.adoc:78 —
== Local development] The section that actually saysnpm run starthas no pointer back to the auth prerequisite. Readers jump straight to "Local development" in a README. A one-line cross-reference would close the gap. -
[README.adoc:74] Passive voice: "Organization approval may be required before the token becomes active." → "Your organization may need to approve the token before it becomes active." (style guide: active voice, second person)
-
[README.adoc:65] Nit: "git credential helpers" — "Git" as a proper noun would be conventional. The team terminology list doesn't cover it, so take it or leave it.
Impact on other files
Files not in this PR (or any of the five) that need updates:
docs-site/meta-docs/CONTRIBUTING.adoc— the strongest gap. This is the guide this very README links to at line 49 as "Submit your first contribution." It documents the Node.js prerequisite, cloning, andnpm run start/build/serve, and has zero mentions of credentials (0 matches forgit-credentials,GIT_CREDENTIALS, orauth token). docs-site#200 touches onlyREADME.adoc. Anyone who follows the link instead of reading the README hits a build failure with no instructions.redpanda-labs— not in the PR set at all. Itsdocs/local-antora-playbook.ymlfetchescloud-docsandrp-connect-docs, both going private, so writers' local labs builds break the same way.README.mdhas no auth section and no local-build section. DOC-2303 also accounts for the labs preview build needing the same credentials, which confirms labs builds Antora against these sources. That playbook additionally still points at the pre-renameredpanda-data/documentationURL — tracked separately in the ticket, but worth landing together.- Follow-up, out of scope here: the README's "Contribute content" section tells external contributors to use Make a contribution > Edit on GitHub, and CONTRIBUTING tells non-employees to fork. Neither works on a private repo. Someone should own rewriting that contributor path.
- Merge sequencing: the section states the repos are private in present tense, while the visibility flip is a later step in DOC-2303. The PR description already flags "merge alongside the repo visibility change," so this is confirmation rather than a new finding — but all five READMEs read as wrong in the interim if they land early.
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
please see Claude's suggestions
- 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 <noreply@anthropic.com>
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
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
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
2 participants
Description
Related to https://redpandadata.atlassian.net/browse/DOC-2303.
Adds local-build GitHub auth instructions for the private content repos (
docs,rp-connect-docs,adp-docs) this repo's Antora playbook fetches — see the commit history for the docs-team-standards review round.Update: auth setup and contribution link now point to cupboard
The full "how to build/author docs locally" reference (including the GitHub-auth steps this PR originally documented in full) has moved to internal-only
redpanda-data/cupboard(redpanda-data/cupboard#677), since every content repo's local build already requires the same private-repo access the guide assumes. This repo's own copy of the auth section was replaced with a short pointer there, and the "clone locally" contribution link was fixed to match (it pointed at a since-deleteddocs-site/meta-docs/CONTRIBUTING.adoc).Also folds in and supersedes the separate link fix opened as #663 (closed).