docs-preview-trigger.yml

name: Trigger Docs Preview Build

on:
    pull_request:
        paths:
            - 'docs/**'
    push:
        branches:
            - master
        paths:
            - 'docs/**'

permissions:
    pull-requests: write

jobs:
    trigger-preview:
        # The queue's branch is deleted the moment it merges, so its Vercel
        # preview is torn down before anyone could open it. No gate coverage is
        # lost either: the frontmatter, internal-docs and link checks below are
        # all continue-on-error, so they never blocked a merge anyway.
        if: ${{ !startsWith(github.head_ref, 'trunk-merge/') }}
        name: Trigger posthog.com preview build
        runs-on: ubuntu-latest
        timeout-minutes: 5
        steps:
            - name: Checkout
              uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

            - name: Check frontmatter in published docs
              continue-on-error: true
              run: |
                  echo "Checking for required frontmatter in published docs..."

                  MISSING_FRONTMATTER=0

                  # Find all markdown/mdx files in published docs
                  for file in docs/published/**/*.{md,mdx}; do
                    if [ -f "$file" ]; then
                      # Check if file starts with ---
                      if ! head -1 "$file" | grep -q "^---"; then
                        echo "❌ Missing frontmatter in: $file"
                        MISSING_FRONTMATTER=1
                      fi
                    fi
                  done

                  if [ $MISSING_FRONTMATTER -eq 1 ]; then
                    echo "Some files are missing required frontmatter. All docs in /docs/published/ must have YAML frontmatter."
                    exit 1
                  fi

                  echo "✅ All published docs have frontmatter"

            - name: Verify internal docs not in published
              continue-on-error: true
              run: |
                  echo "Verifying internal docs are not accidentally in published..."

                  if find docs/published -name "*internal*" -o -name "*private*" -o -name "*secret*" 2>/dev/null | grep -q .; then
                    echo "❌ Found internal/private docs in published directory!"
                    exit 1
                  fi

                  echo "✅ No internal docs found in published directory"

            - name: Check for broken links
              continue-on-error: true
              run: node .github/scripts/check-docs-links.js

            - name: Trigger Vercel build
              id: trigger-build
              env:
                  BRANCH_NAME: ${{ github.event.pull_request.head.ref || github.ref_name }}
                  VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
                  VERCEL_TEAM_ID: ${{ secrets.VERCEL_TEAM_ID }}
                  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
              run: .github/scripts/trigger-vercel-preview.sh "$BRANCH_NAME"

            - name: Post docs preview to CI report
              if: github.event_name == 'pull_request'
              env:
                  GITHUB_TOKEN: ${{ github.token }}
                  TRIGGER_STATUS: ${{ steps.trigger-build.outputs.trigger_status }}
                  DEPLOYMENT_URL: ${{ steps.trigger-build.outputs.deployment_url }}
                  DEPLOYMENT_ID: ${{ steps.trigger-build.outputs.deployment_id }}
              run: node .github/scripts/post-docs-preview-section.mjs