[workflow] Clean up wiki preview branches (#83) (#86)

* Clean up wiki preview branches

* Update wiki submodule pointer for PR #86

---------

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

Author: coisa

.github/wiki

@@ -3,6 +3,8 @@ name: Update Wiki
 on:
   workflow_call:
   workflow_dispatch:
+  schedule:
+    - cron: '17 3 * * *'
   pull_request:
     types: [opened, synchronize, reopened]
   pull_request_target:
@@ -148,4 +150,87 @@ jobs:
 
       - name: Delete wiki preview branch
         working-directory: .github/wiki
-        run: git push origin --delete "${WIKI_PREVIEW_BRANCH}"
+        run: |
+          if git ls-remote --exit-code --heads origin "${WIKI_PREVIEW_BRANCH}" >/dev/null 2>&1; then
+            git push origin --delete "${WIKI_PREVIEW_BRANCH}"
+          else
+            echo "Wiki preview branch ${WIKI_PREVIEW_BRANCH} does not exist. Nothing to delete."
+          fi
+
+  cleanup_closed_preview:
+    name: Delete Closed PR Wiki Preview
+    if: github.event_name == 'pull_request_target' && github.event.pull_request.merged == false
+    runs-on: ubuntu-latest
+
+    env:
+      WIKI_PREVIEW_BRANCH: pr-${{ github.event.pull_request.number }}
+
+    steps:
+      - name: Checkout main branch
+        uses: actions/checkout@v6
+        with:
+          token: ${{ github.token }}
+          ref: main
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Mark wiki workspace as safe for git
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE/.github/wiki"
+
+      - name: Delete wiki preview branch
+        working-directory: .github/wiki
+        run: |
+          if git ls-remote --exit-code --heads origin "${WIKI_PREVIEW_BRANCH}" >/dev/null 2>&1; then
+            git push origin --delete "${WIKI_PREVIEW_BRANCH}"
+          else
+            echo "Wiki preview branch ${WIKI_PREVIEW_BRANCH} does not exist. Nothing to delete."
+          fi
+
+  cleanup_orphaned_previews:
+    name: Delete Orphaned Wiki Previews
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout main branch
+        uses: actions/checkout@v6
+        with:
+          token: ${{ github.token }}
+          ref: main
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Mark wiki workspace as safe for git
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE/.github/wiki"
+
+      - name: Delete wiki branches for closed pull requests
+        working-directory: .github/wiki
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          git fetch origin '+refs/heads/pr-*:refs/remotes/origin/pr-*' || true
+
+          git for-each-ref --format='%(refname:short)' refs/remotes/origin/pr-* | while read -r remote_branch; do
+            branch="${remote_branch#origin/}"
+            pull_request_number="${branch#pr-}"
+
+            if ! [[ "${pull_request_number}" =~ ^[0-9]+$ ]]; then
+              echo "Skipping non-PR wiki preview branch ${branch}."
+              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 wiki preview branch ${branch} for ${state} pull request #${pull_request_number}."
+                git push origin --delete "${branch}" || true
+                ;;
+              OPEN)
+                echo "Keeping wiki preview branch ${branch} for open pull request #${pull_request_number}."
+                ;;
+              *)
+                echo "Could not resolve pull request #${pull_request_number} for wiki preview branch ${branch}. Keeping it."
+                ;;
+            esac
+          done

.github/workflows/wiki.yml

@@ -34,7 +34,13 @@ reject direct commits.
 After the pull request is merged into ``main``, the publish job copies the
 content from the wiki preview branch, such as ``pr-123``, to the wiki
 ``master`` branch. That makes the reviewed wiki content live only after the
-source code merge is complete.
+source code merge is complete. The workflow then deletes the ``pr-123`` branch
+because it is no longer needed.
+
+If the pull request is closed without merge, the workflow deletes the matching
+wiki preview branch without promoting it to ``master``. A scheduled cleanup also
+scans existing ``pr-<number>`` wiki branches and removes branches whose pull
+requests are already closed.
 
 Reports Preview Lifecycle
 -------------------------
@@ -111,6 +117,7 @@ Operational Checklist
 - Review PR preview links before merging documentation-heavy changes.
 - 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.
 
 See :doc:`consumer-automation` for how reusable workflows and consumer stubs fit

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

@@ -227,6 +227,8 @@ Recovery:
 - rerun the cleanup workflow for the closed pull request when available;
 - remove stale preview directories or branches only after confirming the pull
   request is closed or merged;
+- use the scheduled wiki cleanup workflow to remove leftover ``pr-<number>``
+  branches for pull requests that are already closed;
 - check the reports and wiki workflow logs before deleting artifacts manually.
 
 Related References

docs/troubleshooting.rst

@@ -48,6 +48,7 @@ The ``wiki.yml`` workflow synchronizes the documentation generated by the ``dev-
 *   **Submodule Management**: It manages a submodule at ``.github/wiki`` that points to the actual wiki repository.
 *   **Pull Requests**: Pushes documentation changes to a dedicated branch (e.g., ``pr-123``) in the wiki repository for review.
 *   **Merge**: When a PR is merged into ``main``, it pushes the changes to the ``master`` branch of the wiki, making them live.
+*   **Cleanup**: When a PR is closed, the workflow deletes the matching wiki preview branch. A scheduled cleanup also removes stale ``pr-{number}`` branches for already closed pull requests.
 
 .. note::
    See :doc:`../configuration/repository-setup` for mandatory initial setup required for the Wiki workflow to function.

docs/usage/github-actions.rst

@@ -5,6 +5,8 @@ on:
     types: [opened, synchronize, reopened]
   pull_request_target:
     types: [closed]
+  schedule:
+    - cron: '17 3 * * *'
   workflow_dispatch:
 
 permissions: