@redpanda-data/docs-extensions-and-macros 5.44.0 → 5.44.1

package/cli-utils/git-credential-env.js

@@ -0,0 +1,84 @@
+'use strict'
+
+/**
+ * Git credential helper environment
+ *
+ * Every doc-tools code path that clones or fetches a private Redpanda repo
+ * with the git CLI needs the same thing: hand git a GitHub token without the
+ * token ever becoming visible outside the process. This module is the single
+ * implementation of that.
+ *
+ * The token travels through a per-invocation credential helper registered
+ * with GIT_CONFIG_* environment variables, so:
+ *
+ * - It is never a `git -c` argument or part of the remote URL, so it cannot
+ *   be read out of argv (`ps`, /proc/<pid>/cmdline) for the length of a
+ *   multi-minute clone, and git cannot echo it back in an error message.
+ * - It is never written into the clone's .git/config, where it would sit
+ *   readable on disk for every later step that reads the checkout.
+ * - Nothing goes through a shell the caller has to quote for.
+ *
+ * Use getGitHubToken() from ./github-token to resolve the token, then pass
+ * the result here. Pair it with redactCredentials() on any git stderr that
+ * reaches an Error message or a CI log.
+ */
+
+// The variable the helper reads the token from at callback time. Only the
+// name appears in the (static, secret-free) helper command string.
+const TOKEN_ENV_VAR = 'DOC_TOOLS_GIT_CREDENTIAL_TOKEN'
+
+/**
+ * Environment for a git subprocess that must authenticate to github.com.
+ *
+ * With no token, `baseEnv` is returned unchanged rather than half-configured:
+ * git then falls back to the host's own credential helpers, which is what a
+ * local run relies on and all a public repo needs. Callers that require a
+ * token should check for one and fail with their own message first.
+ *
+ * The helper is scoped to `credential.https://github.com.helper`, so no other
+ * host is ever offered the token, and entry 0 clears inherited helpers so a
+ * system credential manager cannot intercept (or prompt) before ours answers.
+ * Any GIT_CONFIG_* entries already in `baseEnv` are replaced.
+ *
+ * @param {string|null|undefined} token - GitHub token, or falsy for no auth
+ * @param {NodeJS.ProcessEnv} [baseEnv=process.env] - Environment to extend
+ * @returns {NodeJS.ProcessEnv} Environment to pass as a spawn/exec `env`
+ */
+function gitAuthEnv(token, baseEnv = process.env) {
+  if (!token) return baseEnv
+  return {
+    ...baseEnv,
+    [TOKEN_ENV_VAR]: token,
+    GIT_CONFIG_COUNT: '2',
+    GIT_CONFIG_KEY_0: 'credential.helper',
+    GIT_CONFIG_VALUE_0: '',
+    GIT_CONFIG_KEY_1: 'credential.https://github.com.helper',
+    GIT_CONFIG_VALUE_1: `!f() { echo "username=x-access-token"; echo "password=$${TOKEN_ENV_VAR}"; }; f`
+  }
+}
+
+/**
+ * Strip anything credential-shaped out of text before it is surfaced
+ * anywhere that gets logged -- an Error message ends up in plain CI logs.
+ *
+ * Covers a credential in a remote URL's userinfo (https://<token>@github.com/...),
+ * which git echoes back verbatim on common failures (a private repo it cannot
+ * see, a bad ref), and a Basic-auth header in case git ever echoes failing
+ * config back. Defense in depth: gitAuthEnv() already keeps the token out of
+ * argv and URLs, so this covers credentials that came from somewhere else,
+ * such as a URL the caller was handed.
+ *
+ * @param {string} text - Text to scrub (nullish becomes '')
+ * @returns {string} Text with credentials replaced by ***
+ */
+function redactCredentials(text) {
+  return String(text || '')
+    .replace(/\/\/[^/@\s]+@/g, '//***@')
+    .replace(/(authorization:\s*basic\s+)\S+/gi, '$1***')
+}
+
+module.exports = {
+  gitAuthEnv,
+  redactCredentials,
+  TOKEN_ENV_VAR
+}

package/extensions/git-full-clone.js

@@ -6,6 +6,7 @@ const { execSync } = require('child_process')
 const fs = require('fs')
 const path = require('path')
 const { getGitHubToken } = require('../cli-utils/github-token')
+const { gitAuthEnv, redactCredentials } = require('../cli-utils/git-credential-env')
 
 /**
  * Configure Antora to use full git clones instead of shallow clones.
@@ -72,27 +73,21 @@ module.exports.register = function ({ config, playbook }) {
 
     // Private repos need credentials: the git CLI does not share Antora's
     // built-in credential manager, so resolve a token (GIT_CREDENTIALS first,
-    // then the common token env vars) and hand it to git through a credential
-    // helper. Both the config and the token travel via environment variables
-    // (GIT_CONFIG_* and GIT_FULL_CLONE_TOKEN), so nothing touches the command
-    // line, the remote URL, or the cached .git/config, and there is no shell
-    // quoting to break on other platforms. Config entry 0 clears any inherited
-    // helpers; entry 1 registers a helper scoped to github.com so no other
-    // host is ever offered the token.
+    // then the common token env vars) and hand it to git through gitAuthEnv's
+    // credential helper. Both the config and the token travel via environment
+    // variables, so nothing touches the command line, the remote URL, or the
+    // cached .git/config, and there is no shell quoting to break on other
+    // platforms.
     const token = getGitHubToken()
     const gitCommand = 'git fetch --unshallow'
-    const gitEnv = { ...process.env, GIT_TERMINAL_PROMPT: '0' }
     if (token) {
       logger.info('  → Using GitHub token for unshallow fetches')
-      gitEnv.GIT_FULL_CLONE_TOKEN = token
-      gitEnv.GIT_CONFIG_COUNT = '2'
-      gitEnv.GIT_CONFIG_KEY_0 = 'credential.helper'
-      gitEnv.GIT_CONFIG_VALUE_0 = ''
-      gitEnv.GIT_CONFIG_KEY_1 = 'credential.https://github.com.helper'
-      gitEnv.GIT_CONFIG_VALUE_1 = '!f() { echo "username=x-access-token"; echo "password=$GIT_FULL_CLONE_TOKEN"; }; f'
     } else {
       logger.info('  → No GitHub token found; unshallow may fail for private repos')
     }
+    // GIT_TERMINAL_PROMPT=0 in both cases: a prompt in a build has no one to
+    // answer it, so fail fast instead of hanging.
+    const gitEnv = gitAuthEnv(token, { ...process.env, GIT_TERMINAL_PROMPT: '0' })
 
     for (const aggregate of contentAggregate) {
       for (const origin of aggregate.origins || []) {
@@ -123,7 +118,7 @@ module.exports.register = function ({ config, playbook }) {
             if (err.killed) {
               logger.warn(`    ✗ Unshallow timeout after ${duration}ms for ${path.basename(gitdir)} (increase unshallowTimeout if needed)`)
             } else {
-              logger.warn(`    ✗ Failed to unshallow ${path.basename(gitdir)}: ${err.message}`)
+              logger.warn(`    ✗ Failed to unshallow ${path.basename(gitdir)}: ${redactCredentials(err.message)}`)
             }
             logger.warn(`    ⚠️  Git dates may be inaccurate for this repo - consider using a pre-cloned cache`)
           }

package/package.json

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

package/tools/bundle-openapi.js

@@ -5,6 +5,7 @@ const path = require('path');
 const { execSync, execFileSync, spawnSync } = require('child_process');
 const yaml = require('yaml');
 const { getMajorMinor } = require('../cli-utils/version');
+const { gitAuthEnv, redactCredentials } = require('../cli-utils/git-credential-env');
 
 /**
  * Normalize a Git tag into a semantic version string.
@@ -662,24 +663,16 @@ async function bundleOpenAPI(options) {
       throw new Error('redpanda-data/streaming-enterprise is a private repository: set GH_TOKEN, GITHUB_TOKEN, or REDPANDA_GITHUB_TOKEN so the clone can authenticate.');
     }
 
-    // Auth travels via a credential helper registered through GIT_CONFIG_*
-    // environment variables, never as a git -c argument, so the token
-    // cannot appear in this process's argv (visible to anything that can
-    // list processes) or get embedded in an exec error's command-line
-    // message. It's also never embedded in the remote URL or persisted in
-    // the clone's .git/config.
-    const gitEnv = { ...process.env };
-    if (token && repositoryUrl.includes('github.com')) {
-      if (!quiet) {
-        console.log('🔑 Using authenticated clone (token provided)');
-      }
-      gitEnv.BUNDLE_OPENAPI_CLONE_TOKEN = token;
-      gitEnv.GIT_CONFIG_COUNT = '2';
-      gitEnv.GIT_CONFIG_KEY_0 = 'credential.helper';
-      gitEnv.GIT_CONFIG_VALUE_0 = '';
-      gitEnv.GIT_CONFIG_KEY_1 = 'credential.https://github.com.helper';
-      gitEnv.GIT_CONFIG_VALUE_1 = '!f() { echo "username=x-access-token"; echo "password=$BUNDLE_OPENAPI_CLONE_TOKEN"; }; f';
+    // gitAuthEnv hands the token to git through a credential helper carried
+    // in the subprocess environment, so it cannot appear in this process's
+    // argv (visible to anything that can list processes) or in an exec
+    // error's command line, and is never embedded in the remote URL or
+    // persisted in the clone's .git/config.
+    const useToken = Boolean(token) && repositoryUrl.includes('github.com');
+    if (useToken && !quiet) {
+      console.log('🔑 Using authenticated clone (token provided)');
     }
+    const gitEnv = gitAuthEnv(useToken ? token : null, { ...process.env });
 
     try {
       execFileSync('git', ['clone', '--depth', '1', '--branch', tag, repositoryUrl, 'redpanda'], {
@@ -689,7 +682,7 @@ async function bundleOpenAPI(options) {
         timeout: 60000 // 1 minute timeout
       });
     } catch (cloneError) {
-      throw new Error(`Failed to clone repository: ${cloneError.message}`);
+      throw new Error(`Failed to clone repository: ${redactCredentials(cloneError.message)}`);
     }
 
     const repoDir = path.join(tempDir, 'redpanda');

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

@@ -5,6 +5,7 @@ const fs = require('fs')
 const os = require('os')
 const path = require('path')
 const { getGitHubToken, getGitHubApiToken } = require('../../cli-utils/github-token')
+const { gitAuthEnv, redactCredentials } = require('../../cli-utils/git-credential-env')
 
 /**
  * rp_util's config schema JSON, for any streaming-enterprise ref (tag,
@@ -58,49 +59,6 @@ const SCHEMA_FLAGS = [
  * @param {string} ref - Branch, tag, or commit SHA
  * @param {string} destDir - Destination directory (must not exist yet)
  */
-/**
- * Strip a credential out of text before it's surfaced anywhere that gets
- * logged -- an Error message ends up in plain CI logs. Covers a credential
- * embedded in a Git remote URL's userinfo (e.g. https://<token>@github.com/...),
- * which Git echoes back verbatim in common failures (a private repo it can't
- * access, a bad ref, ...), and a Basic-auth header in case Git ever echoes
- * failing config back -- defense in depth: this module keeps the token out
- * of argv and URLs entirely (see gitAuthEnv).
- */
-function redactCredentials(text) {
-  return String(text || '')
-    .replace(/\/\/[^/@\s]+@/g, '//***@')
-    .replace(/(authorization:\s*basic\s+)\S+/gi, '$1***')
-}
-
-/**
- * Build the environment that authenticates git's github.com requests via a
- * per-invocation credential helper, injected through GIT_CONFIG_* env vars.
- * No token byte ever appears in argv (readable by any local process via
- * `ps`/`/proc/<pid>/cmdline` for the full multi-minute clone) or in a URL
- * (echoed verbatim by git on common failures), and nothing is written into
- * the resulting clone's .git/config, where it would otherwise sit readable
- * on disk for the entire downstream Bazel/Docker build. Same env-only
- * pattern the property-docs Makefile migration uses.
- * @param {string} token
- * @returns {object} env for spawnSync
- */
-function gitAuthEnv(token) {
-  return {
-    ...process.env,
-    RP_UTIL_FETCH_GIT_TOKEN: token,
-    GIT_CONFIG_COUNT: '2',
-    // Clear any inherited helpers first so a system credential manager
-    // can't intercept (or prompt) before ours answers.
-    GIT_CONFIG_KEY_0: 'credential.helper',
-    GIT_CONFIG_VALUE_0: '',
-    GIT_CONFIG_KEY_1: 'credential.https://github.com.helper',
-    // The helper reads the token from its own environment at callback time;
-    // argv carries only this static, secret-free string.
-    GIT_CONFIG_VALUE_1: '!f() { echo "username=x-access-token"; echo "password=$RP_UTIL_FETCH_GIT_TOKEN"; }; f'
-  }
-}
-
 function cloneStreamingEnterprise(ref, destDir) {
   const token = getGitHubToken()
   if (!token) {

package/tools/rpk-docs/generate-plugin-stubs.js

@@ -17,6 +17,8 @@ const fs = require('fs')
 const path = require('path')
 const os = require('os')
 const { spawnSync } = require('child_process')
+const { getGitHubToken } = require('../../cli-utils/github-token')
+const { gitAuthEnv, redactCredentials } = require('../../cli-utils/git-credential-env')
 
 /**
  * Read command titles from generated partials. The title line is
@@ -78,21 +80,35 @@ function fetchPartialsDir({ docsRepo, docsRef, plugin, sourcePath }) {
   // both carry the single-source tag, so either family can be stubbed
   const sparsePath = sourcePath || `modules/reference/partials/rpk-${plugin}`
 
-  console.log(`Fetching ${sparsePath} from ${docsRepo}@${docsRef}...`)
+  // The docs repo is private, so authenticate when the environment offers a
+  // token (GIT_CREDENTIALS in Antora builds; ACTIONS_BOT_TOKEN, GITHUB_TOKEN,
+  // and friends in workflows). Clone anonymously otherwise, and say so, so a
+  // failed run in CI names the missing piece instead of a bare git prompt.
+  const token = getGitHubToken()
+  // gitAuthEnv keeps the token in the subprocess environment only: never in
+  // argv, never in the remote URL, never in the clone's .git/config.
+  const env = gitAuthEnv(token)
+  const authNote = token ? '' : ' (no GitHub token found; cloning anonymously)'
+  console.log(`Fetching ${sparsePath} from ${docsRepo}@${docsRef}${authNote}...`)
   const cloneResult = spawnSync('git', [
     'clone', '--depth', '1', '--filter=blob:none', '--sparse',
     '--branch', docsRef,
     `https://github.com/${docsRepo}.git`, repoDir
-  ], { encoding: 'utf8', timeout: 180000 })
+  ], { encoding: 'utf8', timeout: 180000, env })
   if (cloneResult.status !== 0) {
-    throw new Error(`Failed to clone ${docsRepo}@${docsRef}: ${cloneResult.stderr}`)
+    const hint = token
+      ? ''
+      : `\nIf ${docsRepo} is private, set ACTIONS_BOT_TOKEN, GITHUB_TOKEN, REDPANDA_GITHUB_TOKEN, or GIT_CREDENTIALS so the clone can authenticate.`
+    throw new Error(`Failed to clone ${docsRepo}@${docsRef}: ${redactCredentials(cloneResult.stderr)}${hint}`)
   }
 
+  // --filter=blob:none deferred the blobs, so the sparse checkout pulls them
+  // now and needs the same credential helper as the clone.
   const sparseResult = spawnSync('git', ['sparse-checkout', 'set', sparsePath], {
-    cwd: repoDir, encoding: 'utf8', timeout: 60000
+    cwd: repoDir, encoding: 'utf8', timeout: 60000, env
   })
   if (sparseResult.status !== 0) {
-    throw new Error(`Failed sparse checkout of ${sparsePath}: ${sparseResult.stderr}`)
+    throw new Error(`Failed sparse checkout of ${sparsePath}: ${redactCredentials(sparseResult.stderr)}`)
   }
 
   const partialsDir = path.join(repoDir, sparsePath)

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

@@ -12,6 +12,7 @@ const { downloadRpkBinary, RPK_RELEASE_TAG_RE, RPK_CDN_BASE } = require('../../c
 const { generateRpkDiff, printDiffReport, generateWhatsNewSection, flattenToMap } = require('./report-delta')
 const { loadAndValidateOverrides, ValidationResult } = require('./validate-overrides')
 const { validateDirectory, formatResults } = require('./validate-output')
+const { gitAuthEnv, redactCredentials } = require('../../cli-utils/git-credential-env')
 
 /**
  * Known rpk plugins that are managed separately (have install/uninstall commands)
@@ -241,12 +242,10 @@ function prepareSourceFromRef(sourceRef, sourcePath = null) {
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rpk-source-'))
   const repoDir = path.join(tmpDir, 'redpanda')
 
-  // streaming-enterprise is private, so a token is required. Auth travels
-  // via a credential helper registered through GIT_CONFIG_* environment
-  // variables, never as a git -c argument, so the token cannot appear in
-  // this process's argv (visible to anything that can list processes) and
-  // never embedded in the remote URL, so no token is persisted in the
-  // clone's .git/config either.
+  // streaming-enterprise is private, so a token is required. gitAuthEnv
+  // hands it to git through a credential helper carried in the subprocess
+  // environment, so it never reaches argv, the remote URL, or the clone's
+  // .git/config.
   const { getGitHubToken } = require('../../cli-utils/github-token')
   const token = getGitHubToken()
   if (!token) {
@@ -255,15 +254,7 @@ function prepareSourceFromRef(sourceRef, sourcePath = null) {
       'Set GH_TOKEN, GITHUB_TOKEN, or REDPANDA_GITHUB_TOKEN so the clone can authenticate.'
     )
   }
-  const gitEnv = {
-    ...process.env,
-    RPK_SOURCE_CLONE_TOKEN: token,
-    GIT_CONFIG_COUNT: '2',
-    GIT_CONFIG_KEY_0: 'credential.helper',
-    GIT_CONFIG_VALUE_0: '',
-    GIT_CONFIG_KEY_1: 'credential.https://github.com.helper',
-    GIT_CONFIG_VALUE_1: '!f() { echo "username=x-access-token"; echo "password=$RPK_SOURCE_CLONE_TOKEN"; }; f'
-  }
+  const gitEnv = gitAuthEnv(token)
 
   console.log(`Sparse-cloning streaming-enterprise repo (ref: ${sourceRef}) to ${repoDir}...`)
 
@@ -287,7 +278,7 @@ function prepareSourceFromRef(sourceRef, sourcePath = null) {
     throw new Error(
       `Failed to clone streaming-enterprise repo with ref '${sourceRef}'.\n` +
       `Make sure the branch or tag exists.\n` +
-      `Error: ${cloneResult.stderr}`
+      `Error: ${redactCredentials(cloneResult.stderr)}`
     )
   }
 
@@ -302,7 +293,7 @@ function prepareSourceFromRef(sourceRef, sourcePath = null) {
   })
 
   if (sparseResult.status !== 0) {
-    throw new Error(`Failed to set sparse checkout: ${sparseResult.stderr}`)
+    throw new Error(`Failed to set sparse checkout: ${redactCredentials(sparseResult.stderr)}`)
   }
 
   console.log(`Sparse checkout complete`)