[RHDHBUGS-3010]: Fix CQA-14 PR build destruction, rewrite deploy as Node.js

- Fix CQA-14 recursion: write preliminary build-report.json before CQA
  so CQA-14 reads lychee results without triggering a full rebuild that
  wipes PR build output and overwrites main on gh-pages
- Remove stale CDN index fetch (fetchUrl, updateRootIndex) from orchestrator
- Rewrite deploy-gh-pages.sh as deploy-gh-pages.js with integrated cleanup
  (stale PR dirs via GitHub API, deleted branches via git ls-remote),
  index regeneration with release notes links, and rebase retry
- Consolidate deploy + cleanup into single gh-pages commit
- Add lychee exclusion for VPN-only release notes URL
- Add architecture documentation for the publication workflow

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: themr0c

.github/workflows/build-asciidoc.yml

@@ -70,37 +70,8 @@ jobs:
         touch .lycheecache
         build/scripts/build-ccutil.sh -b ${{ env.GIT_BRANCH }}
 
-    - name: Deploy to the gh-pages branch
+    - name: Deploy to gh-pages
       env:
         GITHUB_TOKEN: ${{ secrets.RHDH_BOT_TOKEN }}
         GITHUB_REPOSITORY: ${{ github.repository }}
-      run: bash build/scripts/deploy-gh-pages.sh ./titles-generated --message "Deploy ${{ env.GIT_BRANCH }}"
-
-    - name: Cleanup merged PR branches
-      run: |
-        PULL_URL="https://api.github.com/repos/redhat-developer/red-hat-developers-documentation-rhdh/pulls"
-        GITHUB_TOKEN="${{ secrets.RHDH_BOT_TOKEN }}"
-        git config user.name "rhdh-bot service account"
-        git config user.email "rhdh-bot@redhat.com"
-
-        git checkout gh-pages; git pull || true
-        dirs=$(find . -maxdepth 1 -name "pr-*" -type d | sed -r -e "s|^\./pr-||")
-        refs=$(cat pulls.html | grep pr- | sed -r -e "s|.+.html>pr-([0-9]+)</a>.+|\1|")
-        for d in $(echo -e "$dirs\n$refs" | sort -uV); do
-          PR="${d}"
-          echo -n "Check merge status of PR $PR ... "
-          PR_JSON=$(curl -sSL -H "Accept: application/vnd.github+json" -H "Authorization: Bearer $GITHUB_TOKEN" "$PULL_URL/$PR")
-          if [[ $(echo "$PR_JSON" | grep merged\") == *"merged\": true"* ]]; then
-            echo "merged, can delete from pulls.html and remove folder $d"
-            git rm -fr --quiet "pr-${d}" || rm -fr "pr-${d}"
-            sed -r -e "/pr-$PR\/index.html>pr-$PR</d" -i pulls.html
-          elif [[ $(echo "$PR_JSON" | grep \"state\") == *"state\": \"closed\""* ]]; then
-            echo "closed, can delete from pulls.html and remove folder pr-${d}"
-            git rm -fr --quiet "pr-${d}" || rm -fr "pr-${d}"
-            sed -r -e "/pr-$PR\/index.html>pr-$PR</d" -i pulls.html
-          else
-            echo "PR is not closed or merged (or could not read API)"
-          fi
-        done
-        git commit -s -m "remove merged PR branches" . || true # don't fail if there's nothing to do
-        git push origin gh-pages || true # don't fail if there's nothing to do
+      run: node build/scripts/deploy-gh-pages.js --publish-dir ./titles-generated --message "Deploy ${{ env.GIT_BRANCH }}"

.github/workflows/pr.yml

@@ -199,7 +199,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.RHDH_BOT_TOKEN }}
           GITHUB_REPOSITORY: ${{ github.repository }}
-        run: bash trusted-scripts/build/scripts/deploy-gh-pages.sh ./pr-content/titles-generated --message "Deploy PR ${{ github.event.number }} preview"
+        run: node trusted-scripts/build/scripts/deploy-gh-pages.js --publish-dir ./pr-content/titles-generated --message "Deploy PR ${{ github.event.number }} preview"
 
       # Post one consolidated PR comment with build results, preview link, and CQA checklist.
       # Preview link is always shown; marked stale when title build failed (HTML not generated).

.lycheeignore

@@ -8,3 +8,6 @@ file://.*titles-generated/index\.html$
 
 # External sites that block automated requests
 ^https://fonts\.google\.com/icons
+
+# Release notes site is behind Red Hat VPN, unreachable from GitHub Actions
+^https://red-hat-developers-documentation\.pages\.redhat\.com/red-hat-developer-hub-release-notes

build/scripts/build-orchestrator.js

@@ -16,7 +16,6 @@ import { resolve, dirname, join } from 'node:path';
 import { spawn } from 'node:child_process';
 import { cpus } from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { get as httpsGet } from 'node:https';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
@@ -437,51 +436,6 @@ function generateBranchIndex(branch, results, repoRoot) {
   writeFileSync(join(indexDir, 'index.html'), html);
 }
 
-function fetchUrl(url) {
-  return new Promise((resolve, reject) => {
-    httpsGet(url, (res) => {
-      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        fetchUrl(res.headers.location).then(resolve, reject);
-        return;
-      }
-      if (res.statusCode !== 200) {
-        res.resume();
-        reject(new Error(`HTTP ${res.statusCode}`));
-        return;
-      }
-      let data = '';
-      res.on('data', (chunk) => { data += chunk; });
-      res.on('end', () => resolve(data));
-      res.on('error', reject);
-    }).on('error', reject);
-  });
-}
-
-async function updateRootIndex(branch, repoRoot) {
-  const isPR = branch.startsWith('pr-');
-  const indexFile = isPR ? 'pulls.html' : 'index.html';
-  const indexPath = join(repoRoot, 'titles-generated', indexFile);
-  const url = `${PAGES_BASE}/${indexFile}`;
-
-  // Fetch existing index from GitHub Pages
-  try {
-    const data = await fetchUrl(url);
-    writeFileSync(indexPath, data);
-  } catch {
-    // If fetch fails, create a minimal file
-    writeFileSync(indexPath, '<html><body><ul>\n</ul></body></html>');
-  }
-
-  const content = readFileSync(indexPath, 'utf8');
-  const link = `./${branch}/index.html`;
-  if (!content.includes(link)) {
-    console.log(`Building root index for ${branch} in titles-generated/${indexFile} ...`);
-    const entry = `<li><a href=${link}>${branch}</a></li>`;
-    const updated = content.replace('</ul>', `${entry}\n</ul>`);
-    writeFileSync(indexPath, updated);
-  }
-}
-
 // ── Summary output ───────────────────────────────────────────────────────────
 
 function printFailedTitle(r) {
@@ -653,9 +607,6 @@ async function main() {
   // Generate branch index HTML (only for passed titles)
   generateBranchIndex(args.branch, buildResults, repoRoot);
 
-  // Update root index
-  await updateRootIndex(args.branch, repoRoot);
-
   // Run lychee link validation
   console.log('\nRunning link validation (lychee)...');
   const lycheeResult = await runLychee(repoRoot, args.branch, args.verbose);
@@ -664,20 +615,22 @@ async function main() {
   }
 
   // Run CQA content quality assessment
-  // Skip when CQA_RUNNING env is set (CQA-14 recursion guard)
-  const cqaResult = (process.env.CQA_RUNNING)
-    ? { status: 'skipped', duration: 0, output: '', stats: { total: 0, pass: 0, fail: 0 } }
-    : await (async () => {
-        console.log('\nRunning CQA content quality assessment...');
-        return runCqa(repoRoot, args.verbose);
-      })();
+  let cqaResult;
+  if (process.env.CQA_RUNNING) {
+    cqaResult = { status: 'skipped', duration: 0, output: '', stats: { total: 0, pass: 0, fail: 0 } };
+  } else {
+    // Write preliminary report so CQA-14 can read lychee results without rebuilding
+    const pendingCqa = { status: 'pending', duration: 0, output: '', stats: { total: 0, pass: 0, fail: 0 } };
+    writeReport(args.branch, buildResults, lycheeResult, pendingCqa, args.jobs, 0, repoRoot);
+
+    console.log('\nRunning CQA content quality assessment...');
+    process.env.CQA_RUNNING = '1';
+    cqaResult = await runCqa(repoRoot, args.verbose);
+    delete process.env.CQA_RUNNING;
+  }
 
   const totalDuration = Math.round((Date.now() - totalStart) / 1000);
-
-  // Print summary
   printSummary(buildResults, lycheeResult, cqaResult, patterns, totalDuration);
-
-  // Write JSON report
   writeReport(args.branch, buildResults, lycheeResult, cqaResult, args.jobs, totalDuration, repoRoot);
 
   // Exit with error if any builds, lychee, or CQA failed

build/scripts/cqa/checks/cqa-14-no-broken-links.js

@@ -88,18 +88,20 @@ function getLycheeIssues(root) {
   if (_lycheeIssuesCache !== null) return _lycheeIssuesCache;
   _lycheeIssuesCache = [];
 
-  try {
-    // Run build orchestrator (builds fresh HTML + runs lychee with remapping)
-    // Set CQA_RUNNING to prevent build-orchestrator from running CQA again (recursion)
-    execFileSync('node', ['build/scripts/build-orchestrator.js', '-b', 'main'], { // NOSONAR — fixed args, no user input
-      cwd: root,
-      stdio: 'pipe',
-      timeout: 600000, // 10 minutes
-      env: { ...process.env, CQA_RUNNING: '1' },
-    });
-  } catch {
-    // Build may exit non-zero if lychee finds broken links — that's expected
+  if (!process.env.CQA_RUNNING) {
+    // Standalone mode: build current state to get lychee results
+    try {
+      execFileSync('node', ['build/scripts/build-orchestrator.js', '-b', 'main'], { // NOSONAR — fixed args, no user input
+        cwd: root,
+        stdio: 'pipe',
+        timeout: 600000,
+        env: { ...process.env, CQA_RUNNING: '1' },
+      });
+    } catch {
+      // Build may exit non-zero if lychee finds broken links — that's expected
+    }
   }
+  // When CQA_RUNNING is set: preliminary report already exists with lychee results
 
   // Read the build report
   const reportPath = join(root, 'build-report.json');