@redpanda-data/docs-extensions-and-macros 5.35.0 → 5.35.1

package/bin/doc-tools.js

@@ -122,9 +122,9 @@ programCli
  * - A GitHub token with access to redpanda-data/streaming-enterprise, which is
  *   private. Redpanda releases are published there now, and the old public repo
  *   is frozen, so this command exits rather than report a stale version when it
- *   has no token. Resolved from GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN,
- *   ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, or GH_TOKEN, in
- *   that priority order
+ *   has no token. Resolved from REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN,
+ *   GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, GH_TOKEN, or GIT_CREDENTIALS, in that
+ *   priority order (an API call, so the git credential is the last resort)
  */
 programCli
   .command('get-redpanda-version')
@@ -1908,7 +1908,7 @@ automation
  *
  * @requirements
  * - GitHub token with access to redpanda-data/cloudv2-infra repository
- * - Token is resolved from GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, or GH_TOKEN, in that priority order
+ * - Token is resolved from REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, GH_TOKEN, or GIT_CREDENTIALS, in that priority order (an API call, so the git credential is the last resort)
  * - Internet connection to access GitHub API
  */
 automation
@@ -1925,7 +1925,7 @@ automation
   .option('--dry-run', 'Print output to stdout instead of writing file')
   .action(async (options, command) => {
     const { generateCloudRegions } = require('../tools/cloud-regions/generate-cloud-regions.js')
-    const { getGitHubToken } = require('../cli-utils/github-token')
+    const { getGitHubApiToken } = require('../cli-utils/github-token')
 
     try {
       // The default output path holds the unfiltered table, so a filtered run
@@ -1947,7 +1947,7 @@ automation
       const absOutput = options.dryRun
         ? undefined
         : resolveInsideRepo(repoRoot, options.output, '--output')
-      const token = getGitHubToken()
+      const token = getGitHubApiToken()
       if (!token) {
         throw new Error('GitHub token is required to fetch from private cloudv2-infra repo.')
       }

package/cli-utils/enterprise-sources.js

@@ -12,7 +12,7 @@
 
 const fs = require('fs')
 const path = require('path')
-const { getGitHubToken } = require('./github-token')
+const { getGitHubApiToken } = require('./github-token')
 
 const RAW = 'https://raw.githubusercontent.com'
 
@@ -62,7 +62,7 @@ async function discardBody (resp) {
  * check runs on a weekly cron where nobody is watching live.
  *
  * @param {object} [deps]
- * @param {string|null} [deps.token] - GitHub token (defaults to getGitHubToken())
+ * @param {string|null} [deps.token] - GitHub token (defaults to getGitHubApiToken())
  * @param {Function} [deps.fetchImpl] - fetch implementation (defaults to global fetch)
  * @param {Function} [deps.warn] - warning sink (defaults to console.warn)
  * @param {Function} [deps.sleep] - delay implementation, for tests
@@ -72,7 +72,7 @@ async function discardBody (resp) {
  *   check that never ran. Failures without a sourceName throw instead.
  */
 function createSourceFetcher (deps = {}) {
-  const ghToken = deps.token !== undefined ? deps.token : getGitHubToken()
+  const ghToken = deps.token !== undefined ? deps.token : getGitHubApiToken()
   const fetchImpl = deps.fetchImpl || ((...args) => fetch(...args))
   const warn = deps.warn || ((msg) => console.warn(msg))
   const sleep = deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))

package/cli-utils/github-token.js

@@ -47,9 +47,25 @@ function getTokenFromGitCredentials(credentials = process.env.GIT_CREDENTIALS) {
   return null;
 }
 
+const API_TOKEN_VARS = [
+  'REDPANDA_GITHUB_TOKEN',
+  'ACTIONS_BOT_TOKEN',
+  'GITHUB_TOKEN',
+  'VBOT_GITHUB_API_TOKEN',
+  'GH_TOKEN'
+];
+
+function firstApiTokenVar() {
+  for (const name of API_TOKEN_VARS) {
+    if (process.env[name]) return process.env[name];
+  }
+  return null;
+}
+
 /**
- * Get GitHub token from environment variables
- * Checks multiple common variable names in priority order:
+ * Get the GitHub token for git operations (clone, fetch, authenticated URLs).
+ *
+ * Checks, in priority order:
  * 1. GIT_CREDENTIALS - Antora's credential store contents (github.com entry)
  * 2. REDPANDA_GITHUB_TOKEN - Custom Redpanda token
  * 3. ACTIONS_BOT_TOKEN - GitHub Actions bot token
@@ -57,21 +73,44 @@ function getTokenFromGitCredentials(credentials = process.env.GIT_CREDENTIALS) {
  * 5. VBOT_GITHUB_API_TOKEN - Legacy bot token
  * 6. GH_TOKEN - GitHub CLI default
  *
- * Note: this resolver feeds both git clone/fetch auth and GitHub API clients
- * (Octokit). Wherever GIT_CREDENTIALS is set (for example, Antora builds on
- * Netlify), API calls authenticate with that same token, whose API scopes may
- * differ from the token env vars it outranks.
+ * GIT_CREDENTIALS wins here on purpose: it is the credential Antora itself
+ * clones the content repos with, so anything else that clones in the same
+ * build should use the same identity. It is a git credential, not an API
+ * one; for REST calls use getGitHubApiToken().
  *
  * @returns {string|null} GitHub token or null if not found
  */
 function getGitHubToken() {
-  return getTokenFromGitCredentials() ||
-         process.env.REDPANDA_GITHUB_TOKEN ||
-         process.env.ACTIONS_BOT_TOKEN ||
-         process.env.GITHUB_TOKEN ||
-         process.env.VBOT_GITHUB_API_TOKEN ||
-         process.env.GH_TOKEN ||
-         null;
+  return getTokenFromGitCredentials() || firstApiTokenVar();
+}
+
+/**
+ * Get the GitHub token for REST API calls (Octokit, api.github.com,
+ * raw.githubusercontent.com).
+ *
+ * Same variables as getGitHubToken(), but GIT_CREDENTIALS comes LAST:
+ *
+ * 1. REDPANDA_GITHUB_TOKEN
+ * 2. ACTIONS_BOT_TOKEN
+ * 3. GITHUB_TOKEN
+ * 4. VBOT_GITHUB_API_TOKEN
+ * 5. GH_TOKEN
+ * 6. GIT_CREDENTIALS
+ *
+ * Why the different order: on the Netlify Antora sites GIT_CREDENTIALS holds
+ * a token scoped only to cloning the private docs content repos. Letting it
+ * outrank REDPANDA_GITHUB_TOKEN meant the release lookup against the private
+ * streaming-enterprise repo authenticated with a token that cannot see that
+ * repo, got a 404, and every latest-redpanda-* attribute went unset in the
+ * production build even though a token with access was sitting right there.
+ * An explicitly named API token always beats the git credential; the git
+ * credential remains a fallback so a build with only GIT_CREDENTIALS still
+ * authenticates.
+ *
+ * @returns {string|null} GitHub token or null if not found
+ */
+function getGitHubApiToken() {
+  return firstApiTokenVar() || getTokenFromGitCredentials();
 }
 
 /**
@@ -106,6 +145,7 @@ function hasGitHubToken() {
 
 module.exports = {
   getGitHubToken,
+  getGitHubApiToken,
   getTokenFromGitCredentials,
   getAuthenticatedGitHubUrl,
   hasGitHubToken

package/cli-utils/octokit-client.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const { Octokit } = require('@octokit/rest')
-const { getGitHubToken } = require('./github-token')
+const { getGitHubApiToken } = require('./github-token')
 
 /**
  * Shared Octokit client instance for GitHub API access
@@ -14,7 +14,7 @@ const { getGitHubToken } = require('./github-token')
  */
 
 // Get authentication token from environment
-const token = getGitHubToken()
+const token = getGitHubApiToken()
 
 // Configure Octokit options
 const octokitOptions = {

package/cli-utils/self-managed-docs-branch.js

@@ -1,6 +1,6 @@
 const yaml = require('js-yaml');
 const { spawnSync } = require('child_process');
-const { getGitHubToken } = require('./github-token');
+const { getGitHubApiToken } = require('./github-token');
 
 const ANTORA_URL = 'https://raw.githubusercontent.com/redpanda-data/docs/main/antora.yml'
 
@@ -23,7 +23,7 @@ const REJECTED_HINT = ' A GitHub token was sent but rejected, so it may be expir
  */
 async function fetchRemoteAntoraVersion(deps = {}) {
   const fetchImpl = deps.fetchImpl || fetch
-  const ghToken = 'token' in deps ? deps.token : getGitHubToken()
+  const ghToken = 'token' in deps ? deps.token : getGitHubApiToken()
 
   let resp = await fetchImpl(ANTORA_URL, ghToken ? { headers: { Authorization: `Bearer ${ghToken}` } } : undefined)
   const hint = ghToken ? REJECTED_HINT : TOKEN_HINT

package/extensions/version-fetcher/set-latest-version.js

@@ -10,10 +10,13 @@ module.exports.register = function ({ config }) {
   const GetLatestConnectVersion = require('./get-latest-connect');
   const logger = this.getLogger('set-latest-version-extension');
 
-  const { getGitHubToken } = require('../../cli-utils/github-token');
+  const { getGitHubApiToken } = require('../../cli-utils/github-token');
   // Shared with tools/bundle-openapi.js so there is one major.minor derivation.
   const { toShortVersion } = require('../../cli-utils/version');
-  const token = getGitHubToken();
+  // API token, not the git one: GIT_CREDENTIALS (Antora's clone credential)
+  // is only a last resort here, because on Netlify it is scoped to the docs
+  // content repos and cannot see streaming-enterprise.
+  const token = getGitHubApiToken();
 
   if (!token) {
     // Unauthenticated requests still work for the public repos this
@@ -21,7 +24,7 @@ module.exports.register = function ({ config }) {
     // version now comes from the private streaming-enterprise repo, whose
     // API 404s without a token -- the latest-redpanda-* attributes are then
     // left unset and pages fall back to their antora.yml values.
-    logger.warn('GitHub token not set (GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN, GITHUB_TOKEN, or GH_TOKEN). The Redpanda version lookup against the private streaming-enterprise repo will fail and leave latest-redpanda-* attributes unset; other lookups proceed unauthenticated.');
+    logger.warn('GitHub token not set (REDPANDA_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN, or GIT_CREDENTIALS). The Redpanda version lookup against the private streaming-enterprise repo will fail and leave latest-redpanda-* attributes unset; other lookups proceed unauthenticated.');
   }
 
   this.on('contentClassified', async ({ contentCatalog }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.35.0",
+  "version": "5.35.1",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/get-redpanda-version.js

@@ -2,7 +2,7 @@
 
 const GetLatestRedpandaVersion = require('../extensions/version-fetcher/get-latest-redpanda-version.js');
 const { getPrereleaseFromAntora } = require('../cli-utils/antora-utils.js');
-const { getGitHubToken } = require('../cli-utils/github-token');
+const { getGitHubApiToken } = require('../cli-utils/github-token');
 
 /**
  * Fetches and prints the latest Redpanda version and Docker repository.
@@ -20,7 +20,7 @@ module.exports = async function getRedpandaVersion({ beta = false, fromAntora =
   const owner = 'redpanda-data';
   const repo = 'streaming-enterprise';
 
-  if (!getGitHubToken()) {
+  if (!getGitHubApiToken()) {
     console.error(`❌ redpanda-data/${repo} is a private repository.`);
     console.error('   Set GH_TOKEN, REDPANDA_GITHUB_TOKEN, or GITHUB_TOKEN to a token with access.');
     process.exit(1);

package/tools/property-extractor/rp-util-fetch.js

@@ -4,7 +4,7 @@ const { spawnSync } = require('child_process')
 const fs = require('fs')
 const os = require('os')
 const path = require('path')
-const { getGitHubToken } = require('../../cli-utils/github-token')
+const { getGitHubToken, getGitHubApiToken } = require('../../cli-utils/github-token')
 
 /**
  * rp_util's config schema JSON, for any streaming-enterprise ref (tag,
@@ -287,7 +287,7 @@ const RELEASE_ASSET_TO_SCHEMA_KEY = {
  *   no release exists for this tag (caller should fall back to building)
  */
 async function fetchPublishedSchema(tag) {
-  const token = getGitHubToken()
+  const token = getGitHubApiToken()
   const headers = token ? { Authorization: `Bearer ${token}` } : {}
 
   const releaseResp = await fetch(

package/tools/rpk-docs/rpk-docs-handler.js

@@ -1324,8 +1324,8 @@ function downloadRpkRelease(tag, destDir) {
   // redpanda-data/redpanda. This function already has a fallback (the
   // caller builds from source instead), so a missing token warns and
   // returns null here rather than throwing the way the clone-only paths do.
-  const { getGitHubToken } = require('../../cli-utils/github-token')
-  const token = getGitHubToken()
+  const { getGitHubApiToken } = require('../../cli-utils/github-token')
+  const token = getGitHubApiToken()
   if (!token) {
     console.warn('No GitHub token available for the private streaming-enterprise release download; falling back to a source build.')
     return null