webdocs-release.yml

name: Publish release documentation

on:
  release:
    types: [published]
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: release-documentation
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    outputs:
      tag: ${{ steps.release.outputs.tag }}
      revision: ${{ steps.artifact.outputs.revision }}
    steps:
      - name: Select the latest published release
        id: release
        uses: actions/github-script@v7
        with:
          script: |
            const { data } = await github.rest.repos.getLatestRelease(context.repo);
            if (!/^v\d+\.\d+\.\d+$/.test(data.tag_name)) throw new Error('Unexpected release tag');
            if (context.eventName === 'release' && context.payload.release.tag_name !== data.tag_name) {
              throw new Error('Only the latest published release can update documentation');
            }
            core.setOutput('tag', data.tag_name);
      - uses: actions/checkout@v4
        with:
          # Manual runs support docs corrections on main; publication verifies product parity.
          ref: ${{ github.event_name == 'release' && steps.release.outputs.tag || 'main' }}
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: corepack enable
      - run: corepack prepare pnpm@10.21.0 --activate
      - run: pnpm install --frozen-lockfile
        working-directory: webdocs
      - name: Dependency security scan
        run: pnpm audit --prod --audit-level high
        continue-on-error: true
        working-directory: webdocs
      - name: Verify published product baseline
        working-directory: webdocs
        run: node scripts/prepare.mjs --publish
      - name: Verify selected release matches the documentation
        id: artifact
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('node:fs');
            const release = JSON.parse(fs.readFileSync('webdocs/lib/generated/release.json', 'utf8'));
            const { data } = await github.rest.repos.getLatestRelease(context.repo);
            if (release.tag !== data.tag_name || release.status !== 'release') throw new Error('Release mismatch');
            core.setOutput('revision', release.documentationRevision);
      - name: Download the release CLI
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh release download '${{ steps.release.outputs.tag }}' --pattern 'fastskill-x86_64-unknown-linux-musl.tar.gz' --dir /tmp/fastskill-docs-cli
          tar -xzf /tmp/fastskill-docs-cli/fastskill-x86_64-unknown-linux-musl.tar.gz -C /tmp/fastskill-docs-cli
      - name: Validate release examples and user journeys
        run: |
          python3 webdocs/scripts/check-content.py --binary /tmp/fastskill-docs-cli/fastskill
          python3 webdocs/scripts/check-journeys.py /tmp/fastskill-docs-cli/fastskill
      - run: pnpm lint
        working-directory: webdocs
      - run: pnpm typecheck
        working-directory: webdocs
      - run: pnpm build
        working-directory: webdocs
      - run: pnpm check:export
        working-directory: webdocs
      - uses: actions/upload-artifact@v4
        with:
          name: fastskill-static-docs
          path: webdocs/out

  publish-static-site:
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: write
    steps:
      - name: Reject a superseded release
        uses: actions/github-script@v7
        with:
          script: |
            const { data } = await github.rest.repos.getLatestRelease(context.repo);
            if (data.tag_name !== '${{ needs.build.outputs.tag }}') throw new Error('A newer release was published');
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/download-artifact@v4
        with:
          name: fastskill-static-docs
          path: /tmp/fastskill-static-docs
      - name: Publish the static site branch
        env:
          PUBLISH_BRANCH: docs-static
          RELEASE_TAG: ${{ needs.build.outputs.tag }}
          DOCUMENTATION_REVISION: ${{ needs.build.outputs.revision }}
        run: |
          publish_dir="$(mktemp -d)"
          if git ls-remote --exit-code --heads origin "$PUBLISH_BRANCH" > /dev/null; then
            git fetch origin "$PUBLISH_BRANCH:refs/remotes/origin/$PUBLISH_BRANCH"
            git worktree add "$publish_dir" "origin/$PUBLISH_BRANCH"
            git -C "$publish_dir" switch -C "$PUBLISH_BRANCH" --track "origin/$PUBLISH_BRANCH"
          else
            git worktree add --detach "$publish_dir"
            git -C "$publish_dir" switch --orphan "$PUBLISH_BRANCH"
            git -C "$publish_dir" rm -rf . || true
          fi
          find "$publish_dir" -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} +
          cp -a /tmp/fastskill-static-docs/. "$publish_dir/"
          printf 'Release: %s\nDocumentation revision: %s\n' "$RELEASE_TAG" "$DOCUMENTATION_REVISION" > "$publish_dir/PUBLISH.txt"
          git -C "$publish_dir" add --all
          if git -C "$publish_dir" diff --cached --quiet; then
            echo "docs-static already serves $RELEASE_TAG at $DOCUMENTATION_REVISION"
            exit 0
          fi
          git -C "$publish_dir" config user.name 'github-actions[bot]'
          git -C "$publish_dir" config user.email '41898282+github-actions[bot]@users.noreply.github.com'
          git -C "$publish_dir" commit -m "docs: publish $RELEASE_TAG"
          git -C "$publish_dir" push origin "HEAD:refs/heads/$PUBLISH_BRANCH"