docs.yml

name: Docs

on:
  push:
    branches: [main]
    paths: ['website/**', 'skills/**', 'docs/**']
  pull_request:
    paths: ['website/**', 'skills/**', 'docs/**']
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      # Secrets are unavailable on fork PRs and may not be configured yet —
      # skip deployment (and the preview comment) instead of failing the build.
      HAS_CLOUDFLARE_SECRETS: ${{ secrets.CLOUDFLARE_API_TOKEN != '' && secrets.CLOUDFLARE_ACCOUNT_ID != '' }}
    permissions:
      contents: read
      deployments: write
      pull-requests: write
    defaults:
      run:
        working-directory: website
    steps:
      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false
      - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4.0.1
      - run: bun install --frozen-lockfile
      - run: bun scripts/sync-services.ts
      - name: Check generated service pages are up to date
        # git status --porcelain also catches untracked pages generated for
        # newly added skills, which git diff alone would miss.
        run: |
          if [ -n "$(git status --porcelain -- src/content/docs/services)" ]; then
            git status --short -- src/content/docs/services
            echo "::error::services/*.md is stale — run 'bun run sync:services' in website/ and commit"
            exit 1
          fi
      - run: bun run build
      # Pushes to main deploy to production; PR branches get a preview
      # deployment. Fork PRs are skipped (no access to secrets).
      - name: Deploy to Cloudflare Pages
        id: deploy
        if: env.HAS_CLOUDFLARE_SECRETS == 'true'
        uses: cloudflare/wrangler-action@ebbaa1584979971c8614a24965b4405ff95890e0 # v4.0.0
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
          workingDirectory: website
          command: pages deploy dist --project-name=emulate-docs --branch=${{ github.head_ref || github.ref_name }}
      - name: Comment preview URL on PR
        if: github.event_name == 'pull_request' && steps.deploy.outcome == 'success'
        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
        env:
          DEPLOYMENT_URL: ${{ steps.deploy.outputs.deployment-url }}
          ALIAS_URL: ${{ steps.deploy.outputs.pages-deployment-alias-url }}
        with:
          script: |
            const marker = '<!-- docs-preview -->'
            const url = process.env.DEPLOYMENT_URL
            const alias = process.env.ALIAS_URL
            const lines = [
              marker,
              '### 📖 Docs preview deployed',
              '',
              `| | URL |`,
              `| --- | --- |`,
              `| Preview | ${url} |`,
            ]
            if (alias && alias !== url) {
              lines.push(`| Branch alias | ${alias} |`)
            }
            lines.push('', `_Commit: ${context.payload.pull_request.head.sha}_`)
            const body = lines.join('\n')

            const { data: comments } = await github.rest.issues.listComments({
              ...context.repo,
              issue_number: context.issue.number,
              per_page: 100,
            })
            const existing = comments.find(c => c.body.includes(marker))
            if (existing) {
              await github.rest.issues.updateComment({ ...context.repo, comment_id: existing.id, body })
            }
            else {
              await github.rest.issues.createComment({ ...context.repo, issue_number: context.issue.number, body })
            }