@redpanda-data/docs-extensions-and-macros 5.3.7 → 5.7.0

package/cli-utils/github-token.js

@@ -5,19 +5,68 @@
  * Supports multiple common token variable names with priority order.
  */
 
+/**
+ * Extract a GitHub token from the GIT_CREDENTIALS environment variable.
+ *
+ * GIT_CREDENTIALS is the variable Antora's own credential manager reads, so in
+ * Antora builds (for example, Netlify) it is the source guaranteed to hold a
+ * working credential for private content sources. Entries follow the git
+ * credential store format and may be separated by commas or newlines:
+ *
+ *   https://<token>:@github.com
+ *   https://<username>:<password>@github.com
+ *   https://x-access-token:<token>@github.com
+ *
+ * @param {string} [credentials] - Credential contents (defaults to process.env.GIT_CREDENTIALS)
+ * @returns {string|null} GitHub token or null if no github.com entry found
+ */
+function getTokenFromGitCredentials(credentials = process.env.GIT_CREDENTIALS) {
+  if (!credentials) return null;
+
+  for (const entry of credentials.split(/[,\n]/)) {
+    const match = entry.trim().match(/^https?:\/\/([^@]+)@([^/]+)/);
+    // Exact host match (optional port) so entries for lookalike hosts such as
+    // github.com.evil.example or notgithub.com are never treated as GitHub.
+    if (!match || !/^github\.com(:\d+)?$/i.test(match[2])) continue;
+
+    const [username, ...passwordParts] = match[1].split(':');
+    const password = passwordParts.join(':');
+
+    // Token may sit in the username position (https://TOKEN:@github.com) or,
+    // when a username such as x-access-token is present, in the password position.
+    const token = password || username;
+    if (!token) continue;
+
+    try {
+      return decodeURIComponent(token);
+    } catch (err) {
+      return token;
+    }
+  }
+
+  return null;
+}
+
 /**
  * Get GitHub token from environment variables
  * Checks multiple common variable names in priority order:
- * 1. REDPANDA_GITHUB_TOKEN - Custom Redpanda token
- * 2. ACTIONS_BOT_TOKEN - GitHub Actions bot token
- * 3. GITHUB_TOKEN - GitHub Actions default
- * 4. VBOT_GITHUB_API_TOKEN - Legacy bot token
- * 5. GH_TOKEN - GitHub CLI default
+ * 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
+ * 4. GITHUB_TOKEN - GitHub Actions default
+ * 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.
  *
  * @returns {string|null} GitHub token or null if not found
  */
 function getGitHubToken() {
-  return process.env.REDPANDA_GITHUB_TOKEN ||
+  return getTokenFromGitCredentials() ||
+         process.env.REDPANDA_GITHUB_TOKEN ||
          process.env.ACTIONS_BOT_TOKEN ||
          process.env.GITHUB_TOKEN ||
          process.env.VBOT_GITHUB_API_TOKEN ||
@@ -57,6 +106,7 @@ function hasGitHubToken() {
 
 module.exports = {
   getGitHubToken,
+  getTokenFromGitCredentials,
   getAuthenticatedGitHubUrl,
   hasGitHubToken
 };

package/extensions/git-full-clone.js

@@ -3,6 +3,7 @@
 const { execSync } = require('child_process')
 const fs = require('fs')
 const path = require('path')
+const { getGitHubToken } = require('../cli-utils/github-token')
 
 /**
  * Configure Antora to use full git clones instead of shallow clones.
@@ -66,6 +67,30 @@ module.exports.register = function ({ config, playbook }) {
     let unshallowedCount = 0
     const unshallowTimeout = config?.unshallowTimeout || 60000 // Default 60 seconds per repo
 
+    // 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.
+    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')
+    }
+
     for (const aggregate of contentAggregate) {
       for (const origin of aggregate.origins || []) {
         const gitdir = origin.gitdir
@@ -80,11 +105,11 @@ module.exports.register = function ({ config, playbook }) {
             logger.info(`  → Unshallowing ${path.basename(gitdir)}...`)
 
             // Use git fetch --unshallow to convert to full clone
-            execSync('git fetch --unshallow', {
+            execSync(gitCommand, {
               cwd: gitdir,
               stdio: 'pipe',
               timeout: unshallowTimeout,
-              env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+              env: gitEnv
             })
 
             const duration = Date.now() - startTime

package/package.json

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