🚦 Add doc verification to promotion

The `docs.yaml` workflow was not previously set up to be triggered
as part of the `promote` workflow. This isn't, strictly speaking,
"bad" -- but the lack of this does prevent catching workflow issues
earlier.

This modifies the `docs.yaml` workflow to now have a mode that skips
publishing that, and reuses this workflow as part of the promotion
process.

.github/workflows/docs.yaml

@@ -3,6 +3,13 @@ on:
   push:
     branches: [master]
   workflow_dispatch:
+  workflow_call:
+    inputs:
+      skip-publish:
+        default: false
+        description: "Creates the documentation in this workflow without publishing"
+        required: false
+        type: boolean
 
 jobs:
   generate:
@@ -61,6 +68,7 @@ jobs:
           find ./target -type d -exec chmod 0755 {} \;
 
       - name: Upload Pages Artifact
+        if: inputs.skip-publish != true
         uses: actions/upload-pages-artifact@v1
         with:
           path: ./target/doc
@@ -82,10 +90,11 @@ jobs:
     steps:
       - name: Upload GH Pages
         id: deployment
+        if: inputs.skip-publish != true
         uses: actions/deploy-pages@v1
 
       - name: Create summary
-        if: success()
+        if: success() && inputs.skip-publish != true
         run: |
           echo "# Documentation successfully deployed 🚀" >> "${GITHUB_STEP_SUMMARY}"
           echo "" >> "${GITHUB_STEP_SUMMARY}"

.github/workflows/promote.yaml

@@ -10,21 +10,30 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  verify:
+  verify-build:
     name: Verify build integrity
     uses: ./.github/workflows/build.yaml
     permissions:
       contents: read
       security-events: write
       actions: read
 
+  verify-docs:
+    name: Verify documentation
+    uses: ./.github/workflows/docs.yaml
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    with:
+      skip-publish: true
+
   promote:
     name: Promote to Master
     runs-on: ubuntu-latest
     environment: master
     if: success()
-    needs:
-      - verify
+    needs: [verify-build, verify-docs]
     steps:
       - name: Checkout develop
         uses: actions/checkout@v3
@@ -51,7 +60,7 @@ jobs:
           sha1=$(git rev-parse --short HEAD)
           echo '# ⏩ Accepted changes from `develop` into `master`'  >> "${GITHUB_STEP_SUMMARY}"
           echo ''                                                   >> "${GITHUB_STEP_SUMMARY}"
-          echo '${{github.sha}} is the new HEAD of `master`'        >> "${GITHUB_STEP_SUMMARY}"
+          echo '[${{github.sha}}] is the new HEAD of `master`'      >> "${GITHUB_STEP_SUMMARY}"
           echo ''                                                   >> "${GITHUB_STEP_SUMMARY}"
           echo '## Summary'                                         >> "${GITHUB_STEP_SUMMARY}"
           echo ''                                                   >> "${GITHUB_STEP_SUMMARY}"
@@ -67,6 +76,7 @@ jobs:
             --pretty='format:| [`%h`](https://github.com/${{github.repository}}/commit/%h) | %s |' \
             --no-show-signature                                                \
             ${old_sha1}..${new_sha1} >> "${GITHUB_STEP_SUMMARY}"
+          echo '[${{github.sha}}]: https://github.com/${{github.repository}}/commit/${{github.sha}}' >> "${GITHUB_STEP_SUMMARY}"
 
       - name: Summarize Failure
         if: failure()