Make docs workflow dispatchable

ItsDrike · ItsDrike · commit 2d364cc1984f · 2025-08-08T16:56:03.000+02:00
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -2,20 +2,22 @@
 name: MkDocs
 
 on:
-  push:
-    branches:
-      - main
-  pull_request:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  # The requested write permissions will only be followed on 1st party triggers
-  # on 3rd party PRs (from forks), github will drop these permissions to read.
-  contents: write
-  pull-requests: write
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Project version (for releases)"
+        required: false
+        type: string
+      release_type:
+        description: "Type of release"
+        required: true
+        default: "latest"
+        type: choice
+        options:
+          - "latest"
+          - "release"
+          - "preview"
+          - "build-only" # no publish, doesn't require secrets / write access
 
 env:
   PYTHON_VERSION: "3.13"
@@ -24,9 +26,15 @@ jobs:
   mkdocs:
     runs-on: ubuntu-latest
     steps:
+      - name: Validate version input
+        if: inputs.release_type == 'release' && inputs.version == ''
+        run: |
+          echo "ERROR: version must be set for release builds"
+          exit 1
+
       - name: Generate token
         id: app-token
-        if: github.event.pull_request.head.repo.full_name == github.repository || github.event_name == 'push'
+        if: inputs.release_type != 'build-only'
         uses: actions/create-github-app-token@v2
         with:
           app-id: ${{ secrets.PYMINE_BOT_APP_ID }}
@@ -35,9 +43,9 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
-          # We should get a token that allows us to push to the repo when the workflow ran
-          # as 1st party (not from a forked PR). From 3rd parties, the token will be an
-          # empty string (as the token generation step was skipped), so pushing won't work.
+          # Clone with the token generated above, as it will allow push access to the repo
+          # If the above step was skipped, the token string will be empty, this is fine,
+          # it will just perform an unauthenticated anonymous public clone.
           token: "${{ steps.app-token.outputs.token }}"
           # Fetch the entire git history (all branches + tags)
           # We do this because the docs use git describe, which requires having all
@@ -48,7 +56,7 @@ jobs:
       # Make the github application be the committer
       # (see: https://stackoverflow.com/a/74071223 on how to obtain the committer email)
       - name: Setup git config
-        if: github.event.pull_request.head.repo.full_name == github.repository || github.event_name == 'push'
+        if: inputs.release_type != 'build-only'
         run: |
           git config --global user.name "py-mine-ci-bot"
           git config --global user.email "121461646+py-mine-ci-bot[bot]@users.noreply.github.com"
@@ -63,32 +71,33 @@ jobs:
           cache-suffix: "docs"
 
       - name: Install dependencies
-        run: |
-          uv sync --no-default-groups --group docs
+        run: uv sync --no-default-groups --group docs
 
-      # PRs (both 1st and 3rd party)
       - name: Build the documentation (mkdocs)
-        if: github.event_name == 'pull_request'
+        # Only build with mkdocs if we won't be using mike to deploy
+        # (since mike also performs building - it adjust the build to add versions)
+        if: inputs.release_type == 'build-only' || inputs.release_type == 'preview'
         run: mkdocs build
 
-      # 1st party PRs
+      - name: Build & Publish release docs (mike)
+        if: inputs.release_type == 'release'
+        env:
+          version: ${{ inputs.version }}
+        run: mike deploy --update-aliases "$version" release
+
+      - name: Build & Publish latest docs (mike)
+        if: inputs.release_type == 'latest'
+        run: mike deploy latest
+
       - name: Deploy docs - PR preview
-        if: >
-          github.event_name == 'pull_request' &&
-          github.event.pull_request.head.repo.full_name == github.repository
+        if: inputs.release_type == 'preview'
         uses: rossjrw/pr-preview-action@v1
         with:
           source-dir: ./site
           preview-branch: gh-pages
           umbrella-dir: pr-preview
           token: ${{ steps.app-token.outputs.token }}
 
-      # Push to main (1st party)
-      - name: Build the documentation (mike)
-        if: github.event_name == 'push'
-        run: mike deploy latest
-
-      # Push to main (1st party)
-      - name: Deploy docs - latest
-        if: github.event_name == 'push'
+      - name: Push Documentation
+        if: inputs.release_type == 'latest' || inputs.release_type == 'release'
         run: git push origin gh-pages
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -20,6 +20,22 @@ jobs:
   unit-tests:
     uses: ./.github/workflows/unit-tests.yml
 
+  mkdocs:
+    uses: ./.github/workflows/docs.yml
+    with:
+      # On a push to main: "latest"
+      # On a 1st party (non-fork) PR: "preview" (needs secrets access)
+      # On a 3rd party (fork) PR: "build-only"
+      # On a manual dispatch on main branch ref: "latest"
+      # On a manual dispatch on another ref: "build-only"
+      release_type: ${{
+        github.event_name == 'push' && github.ref_name == 'main' && 'latest' ||
+        github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name == github.repository && 'preview' || 'build-only') ||
+        github.event_name == 'workflow_dispatch' && (github.ref_name == 'main' && 'latest' || 'build-only') ||
+        'build-only'
+        }}
+    secrets: inherit
+
   # Produce a pull request payload artifact with various data about the
   # pull-request event (such as the PR number, title, author, ...).
   # This data is then be picked up by status-embed.yml action.
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -206,55 +206,11 @@ jobs:
   publish-docs:
     name: "Publish release docs"
     if: needs.build.outputs.tagged_release == 'true' # only publish release docs on tagged releases
-    needs: build
-    runs-on: ubuntu-latest
-    environment: release # requires approval
-    permissions:
-      contents: write
-
-    steps:
-      - name: Generate token
-        id: app-token
-        uses: actions/create-github-app-token@v2
-        with:
-          app-id: ${{ secrets.PYMINE_BOT_APP_ID }}
-          private-key: ${{ secrets.PYMINE_BOT_PRIVATE_KEY }}
-
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          token: "${{ steps.app-token.outputs.token }}"
-          # Fetch the entire git history (all branches + tags)
-          # We do this because the docs use git describe, which requires having all
-          # the commits up to the latest version tag.
-          # We also need the gh-pages branch to push the docs to.
-          fetch-depth: 0
-
-      # Make the github application be the committer
-      # (see: https://stackoverflow.com/a/74071223 on how to obtain the committer email)
-      - name: Setup git config
-        run: |
-          git config --global user.name "py-mine-ci-bot"
-          git config --global user.email "121461646+py-mine-ci-bot[bot]@users.noreply.github.com"
-
-      - name: Setup uv
-        uses: astral-sh/setup-uv@v6
-        with:
-          version: "latest"
-          python-version: ${{ env.PYTHON_VERSION }}
-          activate-environment: true
-          enable-cache: true
-          cache-suffix: "docs" # matches mkdocs.yml suffix
-
-      - name: Install dependencies
-        run: |
-          uv sync --no-default-groups --group docs
-
-      - name: Build the documentation (mike)
-        env:
-          version: ${{ needs.build.outputs.version }}
-        run: |
-          mike deploy --update-aliases "$version" release
-
-      - name: Deploy docs - release
-        run: git push origin gh-pages
+    # To prevent unapproved runs (outside of the release github environment), this job depends
+    # on the publish-pypi job succeeding. This works around not being able to specify environment: release
+    # for this job (since it's a dispatch job)
+    needs: publish-pypi
+    uses: ./.github/workflows/mkdocs.yml
+    with:
+      release_type: release
+      version: ${{ needs.build.outputs.version }}
