ci(docs-preview): decouple preview pruning, fix removal on close, scope preview paths

[banana-three-join]

Summary

Brings this repository's docs-preview workflows in line with meshery-extensions/tcslabs-academy#72. Pruning old previews is now a separate cleanup workflow, previews are removed reliably when a PR is closed, and the build only triggers on paths that affect the Hugo site.

Changes

Build (build-docs-preview.yml)

• On closed events the job still runs but skips setup and build. Previously the whole job was skipped, so no PR metadata reached the post-build workflow and closed PRs kept their previews.
• PR metadata and the built site are uploaded under one preview/ directory, so the artifact has the same layout whether or not public/ exists.
• The paths filter covers the Hugo directories this repository uses (content, layouts, assets, static, data, i18n where present) and the build inputs (hugo.yaml, go.mod, go.sum, package.json, package-lock.json, postcss.config.js).

Post-build (deploy-docs-preview.yml)

• Pruning moved out of this workflow; it now only deploys or removes the preview for the triggering PR.
• The concurrency group includes the head repository, so forks with the same branch name no longer share a queue.
• actions/download-artifact is pinned to a commit SHA.
• Deploy and remove commits name the PR.
• The sticky comment says "Preview deployment" or "Preview updated", and a separate comment confirms removal on close.

Cleanup (cleanup-docs-preview.yml, new)

• Keeps the 6 most recently updated previews on gh-pages and removes the rest.
• Runs after each post-build run, every 5 days on a schedule, or manually with a custom retention input.
• Pushes to gh-pages are retried with backoff against the latest remote state, so concurrent preview runs don't fail the job.
• Comments on each pruned PR explaining why its preview was removed.

How to verify

• Open a PR that touches a tracked path: the preview deploys and the PR gets a preview URL comment.
• Push another commit: the comment changes to "Preview updated".
• Close the PR: the preview directory is removed from gh-pages and a removal comment is posted.
• Run Docs Preview Cleanup manually with a low retention: excess previews are pruned and their PRs get a comment.

Signed commits

• Yes, I signed my commits.

Summary by CodeRabbit

• Improvements
  • Documentation previews now update when related site assets, layouts, data, and configuration change.
  • Preview builds are skipped for closed pull requests, while their preview metadata remains available for deployment cleanup.
  • Old previews are automatically pruned, keeping the six most recently updated. When a preview is removed, a comment is added to or updated on its pull request.
  • Closed pull requests receive a separate comment when their preview is removed.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: db6bcfbc-279d-47e3-b817-066e0fb1c3ae

📥 Commits

Reviewing files that changed from the base of the PR and between e512af5 and c4d8dc9.

📒 Files selected for processing (3)

• .github/workflows/build-docs-preview.yml
• .github/workflows/cleanup-docs-preview.yml
• .github/workflows/deploy-docs-preview.yml

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The workflows now build preview artifacts under a shared directory, deploy or remove PR previews with corresponding comments, and prune older preview directories through a separate cleanup workflow.

Changes

Docs preview lifecycle

Layer / File(s)	Summary
Prepare preview artifacts .github/workflows/build-docs-preview.yml	The build workflow watches additional preview inputs. It skips setup and building for closed PRs, and uploads metadata and available build output under preview/.
Deploy previews and report status .github/workflows/deploy-docs-preview.yml	The deploy workflow uses actions/download-artifact v8.0.1 and sets explicit commit messages. It posts a preview URL comment for active PRs and a removal comment for closed PRs.
Prune old previews and notify PRs .github/workflows/cleanup-docs-preview.yml	The new workflow prunes previews beyond the configured retention limit, retries failed pushes, and updates or creates comments for PRs with removed previews.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant PostBuild as Docs Preview Post-Build
  participant Cleanup as Cleanup workflow
  participant Pages as gh-pages
  participant PR as Pull request

  PostBuild->>Cleanup: Workflow completion triggers cleanup
  Cleanup->>Pages: Fetch latest state and identify previews beyond retention limit
  loop Up to five attempts when push fails
    Cleanup->>Pages: Remove old preview directories and push changes
  end
  opt Previews were successfully removed
    Cleanup->>PR: Update or create preview removal comment
  end

Loading

Merge Risk: ⚪ Minimal · up to c4d8d

The preview build, removal, and cleanup paths show no identified merge-blocking issue. Normal workflow checks remain appropriate.

Architecture Summary

Architecture risk: 🔵 Low · up to c4d8d

The changed surface does not map to a changed system, dependency edge, entrypoint, or external dependency.

Changed systems: None identified.

Architecture concerns
No architecture-level concerns identified.

Review details

Before / after behavior

• observed — Modified behavior in .github/workflows/build-docs-preview.yml: The pull-request path filter adds assets, data, layouts, static files, Go and npm dependency manifests, PostCSS configuration, and the cleanup-preview workflow. It replaces the former docs-preview-cleanup workflow path; the existing content, Markdown, Go, Hugo configuration, and build/deploy workflow filters remain.
• observed — Modified behavior in .github/workflows/build-docs-preview.yml: The job-level condition that skipped the job when the pull-request action was closed was removed.
• observed — Modified behavior in .github/workflows/build-docs-preview.yml: Go setup, Node setup, and dependency installation now each run only when the pull-request action is not closed; previously these steps had no such condition.
• observed — Modified behavior in .github/workflows/build-docs-preview.yml: The preview build step now runs only when the pull-request action is not closed.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main docs-preview workflow changes: separating preview pruning, fixing removal on PR close, and scoping preview paths.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🧹 Preview removed because the pull request was closed.