deploy-docs.yml

name: Deploy Docs to GitHub Pages

on:
  workflow_dispatch:
    inputs:
      release-tag:
        description: "Published stable release tag (empty selects the latest stable release)"
        required: false
        type: string

permissions: {}

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - name: Require trusted dispatch
        run: |
          test "$GITHUB_EVENT_NAME" = workflow_dispatch && test "$GITHUB_REF" = refs/heads/dev || {
            echo '::error::Dispatch the trusted workflow from dev.'; exit 1;
          }
      - name: Checkout trusted workflow revision
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
        with:
          ref: ${{ github.sha }}
          fetch-depth: 0
          persist-credentials: false
      - name: Resolve published stable source
        id: source
        env:
          GH_TOKEN: ${{ github.token }}
          RELEASE_TAG: ${{ inputs.release-tag }}
        run: |
          set -euo pipefail
          if [ -n "$RELEASE_TAG" ]; then
            [[ "$RELEASE_TAG" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]] || {
              echo '::error::Expected a stable release tag such as v1.2.3.'; exit 1;
            }
            release="$(gh release view "$RELEASE_TAG" --json tagName,isDraft,isPrerelease)"
          else
            release="$(gh api "repos/$GITHUB_REPOSITORY/releases/latest")"
          fi
          tag="$(RELEASE_JSON="$release" node - <<'NODE'
          const r = JSON.parse(process.env.RELEASE_JSON);
          const tag = r.tagName ?? r.tag_name;
          const draft = r.isDraft ?? r.draft;
          const prerelease = r.isPrerelease ?? r.prerelease;
          if (draft !== false || prerelease !== false || typeof tag !== 'string' ||
              !/^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(tag) ||
              (process.env.RELEASE_TAG && tag !== process.env.RELEASE_TAG)) {
            throw new Error('Release is not the requested published stable release');
          }
          process.stdout.write(tag);
          NODE
          )"
          sha="$(git rev-parse --verify "refs/tags/${tag}^{commit}")"
          [[ "$sha" =~ ^[0-9a-f]{40}$ ]] || { echo '::error::Invalid release commit.'; exit 1; }
          echo "sha=$sha" >> "$GITHUB_OUTPUT"
          echo "Building published release $tag at $sha" >> "$GITHUB_STEP_SUMMARY"
      - name: Checkout published source
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
        with:
          ref: ${{ steps.source.outputs.sha }}
          persist-credentials: false
      - name: Build with Astro
        uses: withastro/action@e84f40bd8d2caa9e768ec82ad30dd81f0b280853 # v6.1.2
        with:
          path: ./docs-site
          node-version: 22
          # Must equal package.json dependencies.bun (asserted in ci-workflows.test.ts).
          package-manager: bun@1.4.4

  deploy:
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0