chore: switch to separate docs deployment job (#52)

- uses actions/deploy-pages (for better provenance)
- uses a separate conditional job to deploy docs (for a clean env with limited attack surface)
- uses action/upload-pages-artifact (for preparing artifact in expected format)
- an input option with a default value is not a required input

Author: 2bndy5

.github/workflows/mkdocs.yml

@@ -4,25 +4,39 @@ on:
   workflow_call:
 
 jobs:
-  mkdocs-deploy:
+  build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 #v5
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
       - uses: astral-sh/setup-uv@557e51de59eb14aaaba2ed9621916900a91d50c6 # v6.6.1
       - name: Install dependencies
         run: uv sync --group docs
       - name: Check mkdocs build
-        if: github.ref != 'refs/heads/main'
         run: uv run mkdocs build
       - name: Upload docs build as artifact
-        if: github.ref != 'refs/heads/main'
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 #v4
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
         with:
           name: ${{ github.event.repository.name }}_docs
           path: ${{ github.workspace }}/site
-      - name: Build docs and deploy to gh-pages
-        if: github.ref == 'refs/heads/main'
-        run: |
-          git config user.name 'github-actions'
-          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
-          uv run mkdocs gh-deploy --force
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    needs: [build]
+    permissions:
+      # to deploy to Pages
+      pages: write
+      # to verify the deployment originates from an appropriate source
+      id-token: write
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
+        with:
+          artifact_name: ${{ github.event.repository.name }}_docs

.github/workflows/sphinx.yml

@@ -4,34 +4,45 @@ on:
   workflow_call:
     inputs:
       path-to-doc:
-        required: true
+        required: false
         type: string
         default: docs/_build/html
         description: The docs path name
 
 jobs:
-  sphinx-deploy:
+  build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 #v5
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
       - uses: astral-sh/setup-uv@557e51de59eb14aaaba2ed9621916900a91d50c6 # v6.6.1
-
       - name: Install dependencies
         run: uv sync --group docs
-
       - name: Build docs
         run: uv run sphinx-build docs ${{ inputs.path-to-doc }}
-
       - name: Upload docs build as artifact
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 #v4
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
         with:
           name: ${{ github.event.repository.name }}_docs
           path: ${{ github.workspace }}/${{ inputs.path-to-doc }}
 
-      - name: Upload to github pages
-        # only publish doc changes from main branch
-        if: github.ref == 'refs/heads/main'
-        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e #v4
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    needs: [build]
+    permissions:
+      # to deploy to Pages
+      pages: write
+      # to verify the deployment originates from an appropriate source
+      id-token: write
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./${{ inputs.path-to-doc }}
+          artifact_name: ${{ github.event.repository.name }}_docs