[workflow] Add reports preview concurrency and cleanup (#68) (#88)

* Add reports preview concurrency cleanup

* Update wiki submodule pointer for PR #88

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.github/wiki

@@ -2,7 +2,21 @@ name: Generate Reports and Deploy to GitHub Pages
 
 on:
     workflow_call:
+        inputs:
+            cleanup-previews:
+                description: Remove stale pull request previews without publishing production reports.
+                required: false
+                type: boolean
+                default: false
     workflow_dispatch:
+        inputs:
+            cleanup-previews:
+                description: Remove stale pull request previews without publishing production reports.
+                required: false
+                type: boolean
+                default: false
+    schedule:
+        - cron: '41 3 * * *'
     pull_request:
         types: [ "opened", "synchronize", "reopened", "closed" ]
     push:
@@ -13,12 +27,12 @@ permissions:
     pull-requests: write
 
 concurrency:
-    group: "pages"
-    cancel-in-progress: false
+    group: ${{ github.event_name == 'pull_request' && format('reports-preview-pr-{0}', github.event.pull_request.number) || 'reports-pages' }}
+    cancel-in-progress: ${{ github.event_name == 'pull_request' && github.event.action != 'closed' }}
 
 jobs:
     reports:
-        if: github.event_name != 'pull_request' || github.event.action != 'closed'
+        if: github.event_name != 'schedule' && !(github.event_name == 'workflow_dispatch' && inputs.cleanup-previews) && (github.event_name != 'pull_request' || github.event.action != 'closed')
         name: Generate Reports
         runs-on: ubuntu-latest
 
@@ -143,3 +157,72 @@ jobs:
               run: |
                 cd gh-pages
                 git push
+
+    cleanup_orphaned_previews:
+        if: github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.cleanup-previews)
+        name: Cleanup Orphaned Pull Request Previews
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout gh-pages
+              uses: actions/checkout@v6
+              with:
+                ref: gh-pages
+                path: gh-pages
+
+            - name: Remove previews for closed pull requests
+              env:
+                GH_TOKEN: ${{ github.token }}
+              run: |
+                cd gh-pages
+
+                deleted=0
+                skipped=0
+                unresolved=0
+
+                if [ ! -d previews ]; then
+                    echo "No previews directory exists. Nothing to clean."
+                    exit 0
+                fi
+
+                while read -r preview_dir; do
+                    branch="${preview_dir#previews/}"
+                    pull_request_number="${branch#pr-}"
+
+                    if ! [[ "${pull_request_number}" =~ ^[0-9]+$ ]]; then
+                        echo "Skipping preview directory ${preview_dir}: name does not match pr-<number>."
+                        skipped=$((skipped + 1))
+                        continue
+                    fi
+
+                    state="$(gh pr view "${pull_request_number}" --repo "${GITHUB_REPOSITORY}" --json state --jq '.state' 2>/dev/null || echo UNKNOWN)"
+
+                    case "${state}" in
+                        CLOSED|MERGED)
+                            echo "Deleting preview directory ${preview_dir} for ${state} pull request #${pull_request_number}."
+                            rm -rf "${preview_dir}"
+                            deleted=$((deleted + 1))
+                            ;;
+                        OPEN)
+                            echo "Keeping preview directory ${preview_dir} for open pull request #${pull_request_number}."
+                            skipped=$((skipped + 1))
+                            ;;
+                        *)
+                            echo "Could not resolve pull request #${pull_request_number} for preview directory ${preview_dir}. Keeping it."
+                            unresolved=$((unresolved + 1))
+                            ;;
+                    esac
+                done < <(find previews -mindepth 1 -maxdepth 1 -type d -name 'pr-*' | sort)
+
+                echo "Preview cleanup summary: deleted=${deleted}, skipped=${skipped}, unresolved=${unresolved}."
+
+                touch .nojekyll
+                git config user.name "github-actions[bot]"
+                git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+                git add -A
+                git diff --cached --quiet || git commit -m "chore: remove orphaned pull request previews"
+
+            - name: Push changes
+              run: |
+                cd gh-pages
+                git push

.github/workflows/reports.yml

@@ -55,6 +55,8 @@ On pull requests, the reports workflow:
 - generates docs, coverage, and report assets from the pull request code;
 - publishes them under ``previews/pr-<number>/`` in the Pages branch;
 - comments on the pull request with preview links when possible;
+- cancels older in-progress preview runs when a newer push updates the same
+  pull request;
 - keeps workflow artifacts available as a fallback when Pages publishing or the
   comment update is unavailable.
 
@@ -64,7 +66,9 @@ open pull requests can have independent previews without overwriting each other.
 
 When a pull request is closed, the workflow SHOULD remove its preview directory.
 This prevents stale documentation and coverage reports from looking like active
-review artifacts.
+review artifacts. A scheduled cleanup also scans ``previews/pr-<number>/``
+directories and removes preview directories whose pull requests are already
+closed.
 
 Branch Protection Interactions
 ------------------------------
@@ -120,7 +124,8 @@ Operational Checklist
 - Merge only through the protected ``main`` flow.
 - Let the post-merge wiki job publish to ``master``.
 - Let closed pull requests and scheduled cleanup remove wiki preview branches.
-- Let closed pull requests clean up their report preview directories.
+- Let closed pull requests and scheduled cleanup remove report preview
+  directories.
 
 See :doc:`consumer-automation` for how reusable workflows and consumer stubs fit
 into this model, and :doc:`../usage/github-actions` for the workflow summary.

docs/advanced/branch-protection-and-bot-commits.rst

@@ -221,6 +221,8 @@ Likely causes:
 - the cleanup workflow did not run on the pull request close event;
 - the workflow token lacks permission to update Pages or the wiki repository;
 - a preview was removed after the comment was posted.
+- a reports preview cleanup run skipped a preview because the pull request
+  number could not be resolved.
 - the wiki publish validation detected that remote ``master`` does not match
   the preview branch SHA.
 
@@ -231,6 +233,9 @@ Recovery:
   request is closed or merged;
 - use the scheduled wiki cleanup workflow to remove leftover ``pr-<number>``
   branches for pull requests that are already closed;
+- use the scheduled reports cleanup workflow to remove leftover
+  ``previews/pr-<number>/`` directories for pull requests that are already
+  closed;
 - keep the wiki preview branch until the publish validation log shows matching
   expected and actual SHAs;
 - check the reports and wiki workflow logs before deleting artifacts manually.

docs/troubleshooting.rst

@@ -38,6 +38,8 @@ The ``reports.yml`` workflow is responsible for generating technical documentati
     *   Deploys the preview to ``gh-pages`` under ``previews/pr-{number}/``.
     *   Posts a **Sticky Comment** on the PR with links to the live preview and coverage report.
     *   **Cleanup**: When a PR is closed, the workflow automatically removes the preview directory from the ``gh-pages`` branch to keep the repository clean.
+    *   **Concurrency**: New pushes to the same PR cancel older in-progress preview runs without affecting other PRs.
+*   **Scheduled Cleanup**: A scheduled/manual cleanup removes stale ``previews/pr-{number}/`` directories for already closed pull requests.
 
 Fast Forward Wiki
 -----------------

docs/usage/github-actions.rst

@@ -6,7 +6,15 @@ on:
   push:
     branches:
       - main
+  schedule:
+    - cron: '41 3 * * *'
   workflow_dispatch:
+    inputs:
+      cleanup-previews:
+        description: Remove stale pull request previews without publishing production reports.
+        required: false
+        type: boolean
+        default: false
 
 permissions:
   contents: write
@@ -16,3 +24,5 @@ jobs:
   reports:
     uses: php-fast-forward/dev-tools/.github/workflows/reports.yml@main
     secrets: inherit
+    with:
+      cleanup-previews: ${{ inputs.cleanup-previews || false }}