[workflow] Validate wiki publish before cleanup (#69) (#87)

* Validate wiki publish before cleanup

* Update wiki submodule pointer for PR #87

---------

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

Author: coisa

.github/wiki

@@ -137,9 +137,14 @@ jobs:
           git config --global --add safe.directory "$GITHUB_WORKSPACE/.github/wiki"
 
       - name: Prepare wiki publish branch from preview branch
+        id: prepare_publish
         working-directory: .github/wiki
         run: |
           git fetch origin "${WIKI_PUBLISH_BRANCH}" "${WIKI_PREVIEW_BRANCH}"
+          expected_preview_sha="$(git rev-parse "origin/${WIKI_PREVIEW_BRANCH}")"
+          echo "expected_preview_sha=${expected_preview_sha}" >> "$GITHUB_OUTPUT"
+          echo "Expected wiki preview SHA: ${expected_preview_sha}"
+
           git switch -C "${WIKI_PUBLISH_BRANCH}" --track "origin/${WIKI_PUBLISH_BRANCH}" || git switch "${WIKI_PUBLISH_BRANCH}"
           git reset --hard "origin/${WIKI_PREVIEW_BRANCH}"
           git clean -fd
@@ -148,6 +153,26 @@ jobs:
         working-directory: .github/wiki
         run: git push --force-with-lease origin HEAD:"${WIKI_PUBLISH_BRANCH}"
 
+      - name: Validate wiki publish branch
+        working-directory: .github/wiki
+        env:
+          EXPECTED_PREVIEW_SHA: ${{ steps.prepare_publish.outputs.expected_preview_sha }}
+        run: |
+          actual_publish_sha="$(git ls-remote origin "refs/heads/${WIKI_PUBLISH_BRANCH}" | awk '{print $1}')"
+
+          echo "Expected wiki publish SHA: ${EXPECTED_PREVIEW_SHA}"
+          echo "Actual wiki publish SHA: ${actual_publish_sha}"
+
+          if [ -z "${actual_publish_sha}" ]; then
+            echo "Remote wiki publish branch ${WIKI_PUBLISH_BRANCH} was not found after push." >&2
+            exit 1
+          fi
+
+          if [ "${actual_publish_sha}" != "${EXPECTED_PREVIEW_SHA}" ]; then
+            echo "Remote wiki publish branch ${WIKI_PUBLISH_BRANCH} does not match preview branch ${WIKI_PREVIEW_BRANCH}." >&2
+            exit 1
+          fi
+
       - name: Delete wiki preview branch
         working-directory: .github/wiki
         run: |

.github/workflows/wiki.yml

@@ -34,8 +34,10 @@ 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. The workflow then deletes the ``pr-123`` branch
-because it is no longer needed.
+source code merge is complete. The workflow validates that remote ``master``
+points to the expected preview commit before it deletes the ``pr-123`` branch
+because the preview branch is the last rollback source for that generated
+content.
 
 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

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.
+- the wiki publish validation detected that remote ``master`` does not match
+  the preview branch SHA.
 
 Recovery:
 
@@ -229,6 +231,8 @@ 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;
+- 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.
 
 Related References

docs/troubleshooting.rst

@@ -47,7 +47,7 @@ The ``wiki.yml`` workflow synchronizes the documentation generated by the ``dev-
 **Behavior:**
 *   **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.
+*   **Merge**: When a PR is merged into ``main``, it pushes the changes to the ``master`` branch of the wiki, validates the remote branch SHA, and makes 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::