docs-preview.yml

name: Docs Preview

# Label-triggered docs preview. Adding `trigger:docs` to a PR dispatches a
# preview build to pydantic/unified-docs; that repo builds the unified docs
# against this PR's head SHA, deploys to a shared Cloudflare Worker, and
# updates a comment on this PR with the preview URL.
#
# This workflow is purely a dispatcher — the build, deploy, and final
# URL-comment all happen in the unified-docs repo. The `trigger:docs` label
# is removed at the end so re-adding it re-runs the preview.

on:
  # zizmor: ignore[dangerous-triggers] -- pull_request_target is required so fork PRs can
  # access the DOCS_APP credentials. The dispatch is gated on a maintainer adding the
  # `trigger:docs` label, and this workflow does not check out or execute PR code.
  pull_request_target:
    types: [labeled]

permissions: {}

concurrency:
  group: docs-preview-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  dispatch:
    if: github.event.label.name == 'trigger:docs'
    runs-on: ubuntu-latest
    permissions:
      # Needed to post the "queued" comment and to remove the trigger:docs label.
      pull-requests: write

    steps:
      - name: Generate app token (for dispatching to unified-docs)
        id: app-token
        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        with:
          app-id: ${{ vars.DOCS_APP_ID }}
          private-key: ${{ secrets.DOCS_APP_PRIVATE_KEY }}
          owner: ${{ github.repository_owner }}
          repositories: unified-docs

      - name: Dispatch preview build
        env:
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          REPO: ${{ github.repository }}
        run: |
          gh api repos/pydantic/unified-docs/dispatches \
            --method POST \
            -f event_type=docs-preview \
            -f "client_payload[library]=logfire" \
            -f "client_payload[source_repo]=${REPO}" \
            -f "client_payload[source_pr]=${PR_NUMBER}" \
            -f "client_payload[source_sha]=${HEAD_SHA}"

      - name: Acknowledge on PR
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          REPO: ${{ github.repository }}
        run: |
          sha7=$(echo "$HEAD_SHA" | cut -c1-7)
          body=$(cat <<EOF
          ## Docs Preview — queued

          The preview build for commit \`${sha7}\` has been dispatched to [pydantic/unified-docs](https://github.com/pydantic/unified-docs/actions/workflows/docs-preview.yml). This comment will be updated with the preview URL once the build completes.
          EOF
          )

          # Update an existing "Docs Preview" comment if present (covers re-runs); otherwise post a new one.
          existing=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" \
            --jq '[.[] | select(.user.login == "github-actions[bot]" and (.body | startswith("## Docs Preview")))][0].url // empty')
          if [ -n "$existing" ]; then
            gh api -X PATCH "$existing" -f body="$body"
          else
            gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" -f body="$body"
          fi

      - name: Comment failure on PR
        if: failure()
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          REPO: ${{ github.repository }}
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
          body=$(cat <<EOF
          ## Docs Preview — dispatch failed

          The dispatch to pydantic/unified-docs failed. See [the workflow run](${RUN_URL}) for details.

          <sub>Re-add the \`trigger:docs\` label to retry.</sub>
          EOF
          )
          gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" -f body="$body"

      - name: Remove trigger:docs label
        if: always()
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          REPO: ${{ github.repository }}
        run: gh api -X DELETE "repos/${REPO}/issues/${PR_NUMBER}/labels/trigger:docs" || true