docs.yml

name: Deploy docs

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - '.github/workflows/docs.yml'
  # Rebuild the docs when a release is published — both a release published
  # directly and a draft release promoted to published fire `published`.
  release:
    types: [published]
  workflow_dispatch:

# Allow only one concurrent deployment, skipping runs queued between the run
# in-progress and latest queued. Do not cancel in-progress runs, letting
# production deployments finish.
concurrency:
  group: pages
  cancel-in-progress: false

permissions:
  contents: write
  pages: write
  id-token: write

jobs:
  build:
    name: Build VitePress site
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          # Release events check out the release tag by default. The generated changelog is
          # committed to the default branch, so always build and update main.
          ref: main
          fetch-depth: 0 # for lastUpdated git timestamps
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - uses: actions/configure-pages@v6
      - run: bun install --frozen-lockfile
      - name: Refresh changelog
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: bun run docs:changelog
      - name: Commit refreshed changelog
        run: |
          if git diff --quiet -- docs/changelog.md; then
            echo "Changelog is already current."
            exit 0
          fi
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add docs/changelog.md
          git commit -m "docs: refresh release changelog [skip ci]"
          # main may have advanced since checkout (bun install + the API sweep take a
          # while); rebase so the push isn't rejected as non-fast-forward.
          git pull --rebase origin main
          git push origin HEAD:main
      - run: bun run docs:build
        env:
          # PostHog analytics token. PUBLIC_*, so Vite inlines it into the
          # static build here on the runner (not read at serve time), which is
          # why it must be present in this step. It's a repo *variable*, not a
          # secret: the project token is public by design and ships to every
          # browser. Absent -> analytics stays a silent no-op. Same var name as
          # the adc.co site, so one org value can feed both.
          PUBLIC_POSTHOG_PROJECT_TOKEN: ${{ vars.PUBLIC_POSTHOG_PROJECT_TOKEN }}
      - uses: actions/upload-pages-artifact@v5
        with:
          path: docs/.vitepress/dist

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5