[RHDHBUGS-3010]: Fix GitHub publication workflow by themr0c · Pull Request #2100 · redhat-developer/red-hat-developers-documentation-rhdh

themr0c · 2026-04-24T13:45:05Z

IMPORTANT: Do Not Merge - To be merged by Docs Team Only

Version(s): All (main, release-1.9+)
Issue: https://redhat.atlassian.net/browse/RHDHBUGS-3010
Preview: N/A (workflow and build script changes)

Summary

Fix CQA-14 recursion that destroys PR builds by overwriting main/ on gh-pages (preliminary report + CQA_RUNNING guard)
Rewrite deploy-gh-pages.sh as Node.js (deploy-gh-pages.js) with integrated cleanup of merged/closed PRs and deleted branches, index regeneration with release notes links, and rebase retry on push conflicts
Remove unused scripts: build.sh, build-cqa.sh, lint-scripts.sh
Remove redundant CQA directory copy in pr.yml
Update build-asciidoc.yml to use single deploy step (replaces deploy + inline cleanup)
Add architecture documentation (docs/github-publication-workflow.md)
Update README.adoc: accurate Jira URLs, prerequisites, release notes info, .Prerequisites/.Procedure structure

Test plan

Verify PR build deploys to pr-N/ (not main/) on gh-pages
Verify main branch build deploys to main/ with cleanup and index regeneration
Verify release branch build deploys correctly
Verify CQA-14 standalone run does not destroy PR builds
Verify concurrent push retry works (rebase + rebuild)

🤖 Generated with Claude Code

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

…ode.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>

The rsync on line 148 already copies the entire build/scripts directory including cqa/. The subsequent rm + cp of the same cqa/ directory was a leftover from before rsync was used. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Legacy utility script with no references from any workflow, script, or documentation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

build-cqa.sh: thin wrapper for node cqa/index.js --all, never referenced by any workflow or script. lint-scripts.sh: local shellcheck runner superseded by the shellcheck.yml workflow using reviewdog. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Cleanup of merged PRs and deleted branches is now part of the deploy step (deploy-gh-pages.js), not a separate workflow step. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Quick reference for each script, CQA usage, and workflow mappings. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove reference to deleted build/scripts/build.sh asciidoctor alternative. Update deploy script reference from .sh to .js. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Fix prerequisites: Node.js + Podman (not asciidoctor) - Note that build includes lychee and CQA automatically - Fix lychee section: clarify manual vs automatic, remove false claim that orchestrator downloads lychee - Fix [code,terminal] to [source,terminal] - Fix missing link: prefix on RHDHPAI URL - Add link to architecture documentation - Remove redundant ccutil preference note Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

rhdh-bot · 2026-04-24T13:45:38Z

Shellcheck Analysis Results

Changed shell scripts in this PR: 1

Scripts analyzed:

build/scripts/deploy-gh-pages.sh

Check the Files changed tab for detailed shellcheck suggestions.

All findings are reported as warnings and won't block the PR.

Automated shellcheck analysis • See shellcheck.net for details

rhdh-bot · 2026-04-24T13:51:33Z

Shellcheck: filter out deleted .sh files before running shellcheck, preventing reviewdog parse error on empty input. SonarCloud: use http.extraHeader for git auth instead of embedding token in remote URL, avoiding security hotspot. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

nickboldt · 2026-04-24T14:37:12Z

+
+// ── Content application ──────────────────────────────────────────────────────
+
+function applyContent(deployDir, publishDir, branchDir) {


what does this wrapper achieve? why not call cpSync directly in the 2 places where this function lives?

nickboldt · 2026-04-24T14:38:47Z

+
+  // Branch cleanup: remove directories for deleted remote branches
+  const branchDirs = readdirSync(deployDir).filter(d =>
+    !d.startsWith('pr-') && !d.startsWith('.') && statSync(join(deployDir, d)).isDirectory()


would we add other patterns here, like rhdh-* and 1.* branches which are EOL?

Or do we just delete branches manually from https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/branches/stale so that they're not recreated?

- Replace node:https callback API with fetch() (Node 18+) - Remove unused branchDir parameter from applyContent() - Extract cleanup from stageAndCommit into pushWithRetry (runs once, not per retry) - Deduplicate readdirSync call for diagnostics - Add flow overview and inline comments for non-obvious decisions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

nickboldt

moving to .js for "easier maintainability and testing" is kinda funny when you have to replace cp with a method called cpsync and haven't added actual tests...

but sure.

/lgtm

The Node.js rewrite was 325 lines for functionality that fits naturally in ~289 lines of bash. The deploy script's core job is git operations (fetch, copy, add, commit, push) which read more naturally in shell. Changes from the original 88-line script: - Rebase-based retry replaces sleep-based retry (instant vs 2+ minutes) - Cleanup of stale PR/branch dirs integrated (was separate workflow step) - Index regeneration integrated (was in build-orchestrator.js) - Token auth via http.extraHeader (was in remote URL, leaked in logs) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add comment: orphan path is a bootstrap safety net - Add comment: branch cleanup catches all stale branches via ls-remote Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

openshift-ci · 2026-04-24T15:14:24Z

New changes are detected. LGTM label has been removed.

Keep the original CLI style: deploy-gh-pages.sh <publish_dir> [--message <msg>] Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Branch cleanup now fetches all remote heads in a single call instead of one ls-remote per directory. Also adds cross-reference to orchestrator's getReleaseNotesLink() for maintainability. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The gh-pages branch has existed for years; the orphan creation path was unreachable code. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

SonarCloud S7682 flags implicit returns in bash functions as unclear intent. Adding explicit return 0 to all five flagged functions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

sonarqubecloud · 2026-04-24T15:31:42Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

themr0c and others added 8 commits April 24, 2026 14:48

chore: remove unused build/scripts/build.sh

71c6f6e

Legacy utility script with no references from any workflow, script, or documentation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs: update CLAUDE.md workflow description for integrated cleanup

485abaa

Cleanup of merged PRs and deleted branches is now part of the deploy step (deploy-gh-pages.js), not a separate workflow step. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs: add README for build/scripts

a54e5a1

Quick reference for each script, CQA usage, and workflow mappings. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs: update README.adoc for removed build.sh and new deploy script

3383cd8

Remove reference to deleted build/scripts/build.sh asciidoctor alternative. Update deploy script reference from .sh to .js. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

themr0c temporarily deployed to internal April 24, 2026 13:45 — with GitHub Actions Inactive

themr0c mentioned this pull request Apr 24, 2026

[RHDHBUGS-3010]: Fix GitHub publication workflow (release-1.9) #2101

Merged

3 tasks

themr0c temporarily deployed to internal April 24, 2026 13:51 — with GitHub Actions Inactive

themr0c force-pushed the fix/gh-pages-workflow branch from 6d2a34b to 30613e9 Compare April 24, 2026 13:53

themr0c temporarily deployed to internal April 24, 2026 13:53 — with GitHub Actions Inactive

themr0c temporarily deployed to internal April 24, 2026 13:54 — with GitHub Actions Inactive

themr0c force-pushed the fix/gh-pages-workflow branch from 30613e9 to 3e1e807 Compare April 24, 2026 13:55

themr0c temporarily deployed to internal April 24, 2026 13:55 — with GitHub Actions Inactive

themr0c temporarily deployed to internal April 24, 2026 13:56 — with GitHub Actions Inactive

themr0c force-pushed the fix/gh-pages-workflow branch from 3e1e807 to b1f1b25 Compare April 24, 2026 13:57

themr0c temporarily deployed to internal April 24, 2026 13:57 — with GitHub Actions Inactive

themr0c temporarily deployed to internal April 24, 2026 13:58 — with GitHub Actions Inactive

themr0c force-pushed the fix/gh-pages-workflow branch from b1f1b25 to f7d888a Compare April 24, 2026 13:58

themr0c temporarily deployed to internal April 24, 2026 13:58 — with GitHub Actions Inactive

themr0c temporarily deployed to internal April 24, 2026 13:59 — with GitHub Actions Inactive

themr0c force-pushed the fix/gh-pages-workflow branch from f7d888a to 56c1458 Compare April 24, 2026 14:00

themr0c temporarily deployed to internal April 24, 2026 14:00 — with GitHub Actions Inactive

nickboldt reviewed Apr 24, 2026

View reviewed changes

Comment thread build/scripts/deploy-gh-pages.js Outdated

nickboldt reviewed Apr 24, 2026

View reviewed changes

themr0c temporarily deployed to internal April 24, 2026 14:55 — with GitHub Actions Inactive

nickboldt approved these changes Apr 24, 2026

View reviewed changes

openshift-ci Bot assigned nickboldt Apr 24, 2026

openshift-ci Bot added the lgtm label Apr 24, 2026

themr0c and others added 2 commits April 24, 2026 17:13

fix: address reviewer comments on deploy script

3ad2609

- Add comment: orphan path is a bootstrap safety net - Add comment: branch cleanup catches all stale branches via ls-remote Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

openshift-ci Bot removed the lgtm label Apr 24, 2026

themr0c temporarily deployed to internal April 24, 2026 15:14 — with GitHub Actions Inactive

fix: restore positional argument for publish_dir

ba54154

Keep the original CLI style: deploy-gh-pages.sh <publish_dir> [--message <msg>] Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

themr0c temporarily deployed to internal April 24, 2026 15:19 — with GitHub Actions Inactive

themr0c and others added 2 commits April 24, 2026 17:25

fix: remove dead orphan branch fallback from fetch_gh_pages

171f4a3

The gh-pages branch has existed for years; the orphan creation path was unreachable code. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

themr0c temporarily deployed to internal April 24, 2026 15:26 — with GitHub Actions Inactive

fix: add explicit return statements to bash functions (S7682)

d632148

SonarCloud S7682 flags implicit returns in bash functions as unclear intent. Adding explicit return 0 to all five flagged functions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

themr0c temporarily deployed to internal April 24, 2026 15:31 — with GitHub Actions Inactive

themr0c requested review from nickboldt and rh-tokeefe April 24, 2026 15:34

themr0c merged commit af9329d into redhat-developer:main Apr 27, 2026
8 of 9 checks passed

themr0c deleted the fix/gh-pages-workflow branch April 29, 2026 11:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[RHDHBUGS-3010]: Fix GitHub publication workflow#2100

[RHDHBUGS-3010]: Fix GitHub publication workflow#2100
themr0c merged 20 commits into
redhat-developer:mainfrom
themr0c:fix/gh-pages-workflow

themr0c commented Apr 24, 2026

Uh oh!

rhdh-bot commented Apr 24, 2026 •

edited

Loading

Uh oh!

rhdh-bot commented Apr 24, 2026 •

edited

Loading

Uh oh!

Uh oh!

nickboldt Apr 24, 2026

Uh oh!

nickboldt Apr 24, 2026

Uh oh!

nickboldt left a comment

Uh oh!

openshift-ci Bot commented Apr 24, 2026

Uh oh!

sonarqubecloud Bot commented Apr 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		// ── Content application ──────────────────────────────────────────────────────

		function applyContent(deployDir, publishDir, branchDir) {

Conversation

themr0c commented Apr 24, 2026

Summary

Test plan

Uh oh!

rhdh-bot commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Shellcheck Analysis Results

Scripts analyzed:

Uh oh!

rhdh-bot commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Build Results

Content Quality Assessment

CQA Report

Summary

Uh oh!

Uh oh!

nickboldt Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

nickboldt Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

nickboldt left a comment

Choose a reason for hiding this comment

Uh oh!

openshift-ci Bot commented Apr 24, 2026

Uh oh!

sonarqubecloud Bot commented Apr 24, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rhdh-bot commented Apr 24, 2026 •

edited

Loading

rhdh-bot commented Apr 24, 2026 •

edited

Loading