main.yml

name: ci

on:
  pull_request:
    types: [opened, reopened, synchronize]

  push:
    branches: [main]

concurrency:
  # <workflow_name>-<branch_name>-<true || commit_sha if branch is protected>
  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.ref_protected && github.sha || ''}}
  cancel-in-progress: true

env:
  DO_NOT_TRACK: 1 # Disable Turbopack telemetry
  NEXT_TELEMETRY_DISABLED: 1 # Disable Next telemetry
  NODE_OPTIONS: --max-old-space-size=4096
  NODE_HEAP_HIGH: --max-old-space-size=8192

permissions:
  contents: read

jobs:
  changes:
    runs-on: ubuntu-26.04
    permissions:
      contents: read
      pull-requests: read
    outputs:
      needs_build: ${{ steps.filter.outputs.needs_build }}
      needs_tests: ${{ steps.filter.outputs.needs_tests }}
      needs_visual: ${{ steps.filter.outputs.needs_visual }}
      needs_a11y: ${{ steps.a11y_filter.outputs.needs_a11y }}
      a11y_files: ${{ steps.a11y_report_files.outputs.files }}
      templates: ${{ steps.filter.outputs.templates }}
      build_approvals: ${{ steps.filter.outputs.build_approvals }}
      needs_sbom: ${{ steps.filter.outputs.needs_sbom }}
    steps:
      # https://github.com/actions/virtual-environments/issues/1187
      - name: tune linux network
        run: sudo ethtool -K eth0 tx off rx off

      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
        id: filter
        with:
          filters: |
            needs_build:
              - '.github/filters/a11y.yml'
              - '.github/scripts/a11y/**'
              - '.github/workflows/main.yml'
              - '.github/actions/start-services/**'
              - '.github/actions/setup/**'
              - '.github/scripts/visual/**'
              - '.github/scripts/audit-deps/**'
              - '.github/actions/setup-playwright/**'
              - 'packages/**'
              - 'test/**'
              - 'pnpm-lock.yaml'
              - 'package.json'
              - 'templates/**'
              - 'vitest.config.ts'
            needs_tests:
              - '.github/filters/a11y.yml'
              - '.github/scripts/a11y/**'
              - '.github/workflows/main.yml'
              - '.github/actions/start-services/**'
              - '.github/scripts/audit-deps/**'
              - 'packages/**'
              - 'test/**'
              - 'pnpm-lock.yaml'
              - 'package.json'
              - 'vitest.config.ts'
            templates:
              - 'templates/**'
            # Also gates tests-unit via its own `if`. Excludes plain `packages/**/*.ts` changes on
            # purpose: matching all `.ts` would fire on nearly every PR.
            needs_visual:
              - '.github/workflows/main.yml'
              - '.github/scripts/visual/**'
              - 'packages/**/*.css'
              - 'packages/**/*.scss'
              - 'packages/**/*.tsx'
              - 'packages/**/*.jsx'
              - 'packages/**/*.svg'
              - 'test/**/*.css'
              - 'test/**/*.scss'
              - 'test/**/*.tsx'
              - 'test/**/*.jsx'
              - 'test/**/e2e.spec.ts'
              - 'test/**/__snapshots__/**'
              - 'test/__helpers/e2e/expectScreenshot.ts'
              - 'test/__helpers/e2e/visual.ts'
              - 'test/playwright.config.ts'
              - 'test/buildConfigWithDefaults.ts'
              # `test/admin/e2e/visual/e2e.spec.ts` renders the posts list view with the full admin
              # sidebar nav, which test/admin/config.ts assembles from every collection/global here
              # (labels, grouping, visibility) — plain .ts, so not caught by the *.tsx/*.scss
              # patterns above. Scoped to config-defining files rather than all of `test/admin/**`
              # (100+ files spanning unrelated e2e suites) for the same reason `packages/**/*.ts`
              # is excluded above: a blanket match would fire on nearly every admin-suite PR.
              # seed.ts generates the post titles shown in the posts-list-view baseline.
              - 'test/admin/config.ts'
              - 'test/admin/slugs.ts'
              - 'test/admin/seed.ts'
              - 'test/admin/collections/**'
              - 'test/admin/globals/**'
            build_approvals:
              - '.github/workflows/main.yml'
              # Any dependency-graph change (packages/* or the blank workspace member) lands in
              # the root lockfile; that, plus the allowlist itself, is what can introduce drift.
              - 'pnpm-lock.yaml'
              - 'packages/create-payload-app/src/lib/configure-pnpm-builds.ts'
            # Inputs of the release SBOMs (the dependency graph, the pnpm version, the generator) and this job.
            needs_sbom:
              - 'pnpm-lock.yaml'
              - 'pnpm-workspace.yaml'
              - 'packages/*/package.json'
              - '.tool-versions'
              - 'tools/releaser/src/release-sbom.ts'
              - 'tools/releaser/src/lib/sbom/**'
              - 'tools/releaser/src/lib/publishList.ts'
              - 'tools/releaser/src/lib/getPackageDetails.ts'
              - 'tools/releaser/package.json'
              - 'tools/constants/**'
              - 'package.json'
              - '.github/actions/setup/**'
              - '.github/workflows/main.yml'
      - name: Filter accessibility changes
        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
        id: a11y_filter
        with:
          list-files: json
          filters: .github/filters/a11y.yml

      - name: Bound accessibility report file list
        id: a11y_report_files
        continue-on-error: true
        # The full JSON list travels through stdin, never an argument or environment variable.
        run: |
          node .github/scripts/a11y/matched-files.mjs <<'A11Y_MATCHED_FILES_JSON'
          ${{ steps.a11y_filter.outputs.needs_a11y_files }}
          A11Y_MATCHED_FILES_JSON

      - name: Log filter results
        run: |
          echo "needs_build: ${{ steps.filter.outputs.needs_build }}"
          echo "needs_tests: ${{ steps.filter.outputs.needs_tests }}"
          echo "needs_visual: ${{ steps.filter.outputs.needs_visual }}"
          echo "needs_a11y: ${{ steps.a11y_filter.outputs.needs_a11y }}"
          echo "templates: ${{ steps.filter.outputs.templates }}"
          echo "build_approvals: ${{ steps.filter.outputs.build_approvals }}"
          echo "needs_sbom: ${{ steps.filter.outputs.needs_sbom }}"

  # Detects upstream Next.js canary publishes that are missing `@next/env` or
  # `@next/eslint-plugin-next` for the same version (would break
  # `pnpm create next-app@canary` with `ERR_PNPM_NO_MATCHING_VERSION`).
  probe-next-canary:
    name: probe-next-canary
    runs-on: ubuntu-26.04
    needs: changes
    if: needs.changes.outputs.needs_tests == 'true'
    outputs:
      healthy: ${{ steps.probe.outputs.healthy }}
      next_version: ${{ steps.probe.outputs.next_version }}
    steps:
      - name: Probe registry for complete canary publish
        id: probe
        run: |
          retry_npm_view() {
            local spec="$1"
            for attempt in 1 2 3; do
              if npm view "$spec" version >/dev/null 2>&1; then
                return 0
              fi
              sleep $((attempt * 2))
            done
            return 1
          }

          NEXT_VERSION=""
          for attempt in 1 2 3; do
            NEXT_VERSION="$(npm view next@canary version 2>/dev/null || true)"
            if [ -n "$NEXT_VERSION" ]; then
              break
            fi
            sleep $((attempt * 2))
          done
          echo "Resolved next@canary version: ${NEXT_VERSION:-<empty>}"
          echo "next_version=${NEXT_VERSION}" >> "$GITHUB_OUTPUT"
          if [ -z "$NEXT_VERSION" ]; then
            echo "healthy=unknown" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          if retry_npm_view "@next/env@${NEXT_VERSION}" \
            && retry_npm_view "@next/eslint-plugin-next@${NEXT_VERSION}"; then
            echo "healthy=true" >> "$GITHUB_OUTPUT"
          else
            echo "healthy=false" >> "$GITHUB_OUTPUT"
          fi

  lint:
    runs-on: ubuntu-26.04
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
        with:
          fetch-depth: 0

      # Rules live in .github/zizmor.yml. Bump `version` deliberately: new releases add audits.
      # The action only accepts zizmor versions released before it, so bump the action with it.
      - name: Lint GitHub Actions pins
        uses: zizmorcore/zizmor-action@53290badfa369cb0bf7ad16342cb62c2fa47ac7b # v0.8.0
        with:
          inputs: .github
          version: 1.31.1
          # `ref-version-mismatch` flags a missing version comment only in the pedantic persona.
          persona: pedantic
          advanced-security: false
          annotations: true

      - name: Node setup
        uses: ./.github/actions/setup

      - name: Check formatting
        run: pnpm format:check

      - name: Lint TypeScript/JavaScript
        run: pnpm lint --quiet
        env:
          NODE_OPTIONS: ${{ env.NODE_HEAP_HIGH }}

      - name: Lint CSS
        run: pnpm run lint:css

  build:
    needs: changes
    if: needs.changes.outputs.needs_build == 'true' || needs.changes.outputs.needs_a11y == 'true'
    runs-on: ubuntu-26.04

    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0

      - name: Node setup
        uses: ./.github/actions/setup

      - run: pnpm run build:all
        env:
          DO_NOT_TRACK: 1 # Disable Turbopack telemetry

      - name: Cache build
        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
        with:
          path: ./*
          key: ${{ github.sha }}

      # Narrower than "Cache build" above: just the compiled, platform-independent package
      # output, with no `node_modules`. The `visual-regression` job restores this directly onto
      # the runner (not inside its Docker container's own install) to skip re-running `build:all`
      # without reintroducing the native-module ABI mismatch that job's own install step exists to
      # avoid — see the comment on that job for why it can't reuse the `Cache build` entry above.
      - name: Cache dist output
        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
        with:
          path: packages/*/dist
          key: dist-${{ github.sha }}

  # Catches SBOM generation regressions before a release. Push to main only, not part of all-green.
  sbom:
    needs: changes
    if: github.event_name == 'push' && needs.changes.outputs.needs_sbom == 'true'
    runs-on: ubuntu-26.04

    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
        with:
          persist-credentials: false

      - name: Node setup
        uses: ./.github/actions/setup

      - name: Generate SBOMs
        run: pnpm release-sbom --out-dir "$RUNNER_TEMP/sboms"

  tests-unit:
    permissions:
      actions: read
      contents: read
    runs-on: ubuntu-26.04
    needs: [changes, build]
    if: needs.changes.outputs.needs_tests == 'true' || needs.changes.outputs.needs_visual == 'true'
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0

      - name: Node setup
        uses: ./.github/actions/setup
        with:
          restore-build: true

      - name: Unit Tests
        run: pnpm test:unit
        env:
          NODE_OPTIONS: ${{ env.NODE_HEAP_HIGH }}

      - name: Browser setup
        uses: ./.github/actions/setup-playwright

      - name: Component Tests
        run: pnpm test:components

  tests-types:
    permissions:
      actions: read
      contents: read
    runs-on: ubuntu-26.04
    needs: [changes, build]
    if: needs.changes.outputs.needs_tests == 'true'
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0

      - name: Node setup
        uses: ./.github/actions/setup
        with:
          restore-build: true

      - name: Types Tests
        run: pnpm test:types --target '>=5.7'
        env:
          NODE_OPTIONS: ${{ env.NODE_HEAP_HIGH }}

  # Generate the integration test matrix from TypeScript config
  int-matrix:
    name: Setup Int Matrix
    runs-on: ubuntu-26.04
    outputs:
      matrix: ${{ steps.generate.outputs.matrix }}
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
        with:
          sparse-checkout: |
            .github/workflows
            .tool-versions

      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
        with:
          node-version-file: .tool-versions

      - name: Generate matrix
        id: generate
        run: |
          matrix=$(node .github/workflows/int.config.ts)
          echo "matrix=$matrix" >> $GITHUB_OUTPUT

  tests-int:
    permissions:
      actions: read
      contents: read
    runs-on: ubuntu-26.04
    needs: [changes, build, int-matrix, probe-next-canary]
    if: needs.changes.outputs.needs_tests == 'true'
    name: int-${{ matrix.database }}${{ matrix.total-shards > 1 && format(' ({0}/{1})', matrix.shard, matrix.total-shards) || '' }}
    timeout-minutes: 45
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.int-matrix.outputs.matrix) }}

    env:
      AWS_ENDPOINT_URL: http://127.0.0.1:4566
      AWS_ACCESS_KEY_ID: localstack
      AWS_SECRET_ACCESS_KEY: localstack
      AWS_REGION: us-east-1

    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0

      - name: Node setup
        uses: ./.github/actions/setup
        with:
          restore-build: true

      - name: Configure Redis
        run: |
          echo "REDIS_URL=redis://127.0.0.1:6379" >> $GITHUB_ENV

      - name: Start services
        id: db
        uses: ./.github/actions/start-services
        with:
          database: ${{ matrix.database }}

      - name: Integration Tests
        env:
          NODE_OPTIONS: ${{ env.NODE_HEAP_HIGH }}
          PAYLOAD_DATABASE: ${{ matrix.database }}
          POSTGRES_URL: ${{ steps.db.outputs.POSTGRES_URL }}
          MONGODB_URL: ${{ steps.db.outputs.MONGODB_URL }}
          MONGODB_ATLAS_URL: ${{ steps.db.outputs.MONGODB_ATLAS_URL }}
        run: |
          if [ "${{ needs.probe-next-canary.outputs.healthy }}" = "false" ]; then
            echo "::warning::Next.js canary publish is incomplete on npm (next@${{ needs.probe-next-canary.outputs.next_version }}); skipping Canary tests for this run."
            pnpm test:int --shard=${{ matrix.shard }}/${{ matrix.total-shards }} -t '^(?!.*Canary).*$'
          else
            pnpm test:int --shard=${{ matrix.shard }}/${{ matrix.total-shards }}
          fi

  # Generate the E2E test matrix from TypeScript config
  e2e-matrix:
    name: Setup E2E Matrix
    runs-on: ubuntu-26.04
    outputs:
      matrix: ${{ steps.generate.outputs.matrix }}
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
        with:
          sparse-checkout: |
            .github/workflows
            .tool-versions

      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
        with:
          node-version-file: .tool-versions

      - name: Generate matrix
        id: generate
        run: |
          matrix=$(node .github/workflows/e2e.config.ts)
          echo "matrix=$matrix" >> $GITHUB_OUTPUT

  # Prepare prod test environment once, shared by all E2E shards
  e2e-prep:
    permissions:
      actions: read
      contents: read
    name: E2E Prep
    runs-on: ubuntu-26.04
    needs: [changes, build]
    if: needs.changes.outputs.needs_tests == 'true' || needs.changes.outputs.needs_a11y == 'true'
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0

      - name: Node setup
        uses: ./.github/actions/setup
        with:
          restore-build: true

      - name: Prepare prod test environment
        run: pnpm prepare-run-test-against-prod:ci

      # Tar first: upload-artifact is extremely slow with pnpm node_modules (many small files + symlinks).
      - name: Archive prepared test environment
        run: tar --zstd -cf e2e-prep.tar.zst test/packed test/node_modules test/package.json test/pnpm-lock.yaml

      # Artifact (not cache) so that re-runs of individual E2E shards survive the 10 GB cache LRU eviction.
      - name: Upload prepared test environment
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: e2e-prep-${{ github.sha }}
          path: e2e-prep.tar.zst
          if-no-files-found: error

  tests-e2e:
    permissions:
      actions: read
      contents: read
    runs-on: ubuntu-26.04
    needs: [changes, e2e-matrix, e2e-prep]
    if: needs.changes.outputs.needs_tests == 'true'
    name: E2E - ${{ matrix.suite || 'all suites' }} [${{ matrix.framework }}]${{ matrix.total-shards > 1 && format(' ({0}/{1})', matrix.shard, matrix.total-shards) || '' }}${{ matrix.disableCacheComponents && ' [without cacheComponents]' || '' }}
    timeout-minutes: 45
    # TanStack Start suites are optional for now: their failures must not block the
    # `all-green` gate. `matrix.optional` is true for tanstack-start entries (see e2e-matrix.ts).
    continue-on-error: ${{ matrix.optional }}
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.e2e-matrix.outputs.matrix) }}
    env:
      SUITE_NAME: ${{ matrix.suite }}
      PAYLOAD_DISABLE_CACHE_COMPONENTS: ${{ matrix.disableCacheComponents && 'true' || '' }}
      PAYLOAD_FRAMEWORK: ${{ matrix.framework }}
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0

      - name: Node setup
        uses: ./.github/actions/setup
        with:
          restore-build: true

      - name: Download prepared test environment
        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
        with:
          name: e2e-prep-${{ github.sha }}
          path: .

      - name: Extract prepared test environment
        shell: bash
        run: |
          if [ ! -f e2e-prep.tar.zst ]; then
            echo "::error::The 'e2e-prep-${{ github.sha }}' artifact did not contain e2e-prep.tar.zst."
            echo "::error::This usually means the 'E2E Prep' job did not run or failed to upload."
            echo "::error::Re-run the entire workflow so 'E2E Prep' regenerates the artifact."
            exit 1
          fi
          tar --zstd -xf e2e-prep.tar.zst
          rm e2e-prep.tar.zst
          if [ ! -d test/packed ] || [ ! -d test/node_modules ]; then
            echo "::error::Extracted artifact is missing expected directories (test/packed or test/node_modules)."
            exit 1
          fi

      - name: Start services
        id: db
        uses: ./.github/actions/start-services
        with:
          database: mongodb

      - name: Setup Playwright
        uses: ./.github/actions/setup-playwright
        timeout-minutes: 10

      - name: E2E Tests
        # E2E Test Execution Strategy:
        #
        # The e2e.config.ts defines each test suite with: { file, framework?, shards, parallel? }
        # - shards: Number of CI runners to split this suite across
        # - framework: Framework adapter used to boot the test app (default: next)
        # - parallel: Whether tests within the suite can run concurrently (default: false)
        # - disableCacheComponents: Whether to disable Next.js `cacheComponents` (default: false)
        # - grep: Only run matching tests. An entry with an empty `file` runs them from every suite
        #   (used to run `@also-without-cache-components` tests with cacheComponents disabled)
        #
        # Flags explained:
        # - --fully-parallel: Enables test-level sharding (distributes individual tests across shards,
        #   not just files). There is an arbitrary limitation that disables sharding if fullyParallel
        #   is not set.
        # - --workers=1: Forces serial execution within each shard. Added when parallel=false.
        #
        # How it works:
        # - Most suites: parallel=false → tests run serially (--workers=1) but are sharded across runners
        # - Parallel suites (e.g. LexicalFullyFeatured): parallel=true → tests run concurrently within each shard
        #
        # Local vs CI behavior:
        # - Locally: playwright.config.ts has workers=16. Without --fully-parallel, Playwright
        #   runs tests serially by default (one test at a time per file). Suites with
        #   test.describe.configure({ mode: 'parallel' }) opt into parallel execution.
        # - CI: We must use --fully-parallel to enable test-level sharding across runners.
        #   However, --fully-parallel would also run all tests in parallel within each shard.
        #   To maintain serial execution for most suites, we pass --workers=1 when parallel=false.
        #   Suites with parallel=true (e.g. LexicalFullyFeatured) use the default 16 workers.
        #
        # Note: The e2e-prep job runs prepare-run-test-against-prod:ci once and uploads the result
        # as an artifact. This job downloads that artifact, so we skip preparation. Each shard runs a
        # real production server (next build / vite build, ~10s), booted per shard by runE2E.
        #
        # --grep-invert="@visual": screenshot comparisons are handled exclusively by the dedicated
        # `visual-regression` job (gated on `needs_visual`), never by this unconditional matrix —
        # otherwise a `@visual` test would also run here on every PR that touches test/packages
        # code, including under the tanstack-start framework it was never baselined against.
        run: PLAYWRIGHT_JSON_OUTPUT_NAME=results_${{ matrix.suite }}_${{ matrix.framework }}_${{ matrix.shard }}.json pnpm test:e2e:prod:server:run ${{ matrix.suite }} --shard=${{ matrix.shard }}/${{ matrix.total-shards }} --fully-parallel --grep-invert="@visual"${{ matrix.parallel == false && ' --workers=1' || '' }}${{ matrix.grep && format(' --grep="{0}"', matrix.grep) || '' }}
        env:
          PLAYWRIGHT_JSON_OUTPUT_NAME: results_${{ matrix.suite }}_${{ matrix.framework }}_${{ matrix.shard }}.json
          NEXT_TELEMETRY_DISABLED: 1
          PAYLOAD_DATABASE: mongodb

      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        if: always()
        with:
          name: test-results-${{ matrix.suite || 'all-suites' }}_${{ matrix.framework }}_${{ matrix.shard }}${{ matrix.disableCacheComponents && '_without-cc' || '' }}
          path: test/test-results/
          if-no-files-found: ignore
          retention-days: 1

      # Disabled until this is fixed: https://github.com/daun/playwright-report-summary/issues/156
      # - uses: daun/playwright-report-summary@v3
      #   with:
      #     report-file: results_${{ matrix.suite }}.json
      #     report-tag: ${{ matrix.suite }}
      #     job-summary: true

  tests-a11y:
    permissions:
      actions: read
      contents: read
    name: Accessibility [${{ matrix.framework }}]
    runs-on: ubuntu-26.04
    needs: [changes, e2e-prep]
    if: needs.changes.outputs.needs_a11y == 'true'
    timeout-minutes: 45
    strategy:
      fail-fast: false
      matrix:
        framework: [next, tanstack-start]
    env:
      PAYLOAD_FRAMEWORK: ${{ matrix.framework }}
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0

      - name: Node setup
        uses: ./.github/actions/setup
        with:
          restore-build: true

      - name: Download prepared test environment
        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
        with:
          name: e2e-prep-${{ github.sha }}
          path: .

      - name: Extract prepared test environment
        shell: bash
        run: |
          tar --zstd -xf e2e-prep.tar.zst
          rm e2e-prep.tar.zst

      - name: Start services
        uses: ./.github/actions/start-services
        with:
          database: mongodb

      - name: Setup Playwright
        uses: ./.github/actions/setup-playwright
        timeout-minutes: 10

      - name: Accessibility tests
        id: a11y_tests
        run: pnpm test:e2e:prod:server:run a11y --workers=1 --grep-invert="@visual"
        env:
          PLAYWRIGHT_JSON_OUTPUT_NAME: results_a11y_${{ matrix.framework }}_1.json
          A11Y_REPORT_PATH: ${{ github.workspace }}/test/test-results/a11y-summary.md
          A11Y_MATCHED_FILES: ${{ needs.changes.outputs.a11y_files }}
          NEXT_TELEMETRY_DISABLED: 1
          PAYLOAD_DATABASE: mongodb

      - id: a11y_evidence
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        if: always()
        with:
          name: test-results-a11y_${{ matrix.framework }}_${{ github.run_attempt }}
          path: test/test-results/
          if-no-files-found: ignore
          retention-days: 7

      - name: Publish accessibility workflow summary
        if: always()
        continue-on-error: true
        env:
          A11Y_TEST_OUTCOME: ${{ steps.a11y_tests.outcome }}
          A11Y_EVIDENCE_URL: ${{ steps.a11y_evidence.outputs.artifact-url }}
        run: node .github/scripts/a11y/report.mjs test/test-results/a11y-summary.md

      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        if: always()
        continue-on-error: true
        with:
          name: a11y-summary-${{ matrix.framework }}-${{ github.run_attempt }}
          path: test/test-results/a11y-summary.md
          if-no-files-found: warn
          retention-days: 7

  # Runs `@visual`-tagged e2e tests (screenshot comparisons against baselines).
  # If this fails, reproduce locally with `pnpm test:visual`; update an intentional baseline with
  # `pnpm test:visual:update`. Both must run inside the pinned Playwright Docker image, since font
  # rendering differs enough from a bare host to fail the comparison even with no real change.
  #
  # For the same reason, this job reinstalls node_modules fresh inside that Docker image rather
  # than reusing the `build`/`e2e-prep` node_modules from the bare runner, which would mix
  # runner-built native modules (sharp, etc.) with the container's own Node/glibc. It restores only
  # `packages/*/dist` (plain compiled JS, no native bindings) from the `build` job's cache.
  visual-regression:
    name: Visual Regression
    runs-on: ubuntu-26.04
    needs: [changes, build]
    if: needs.changes.outputs.needs_visual == 'true'
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0

      - name: Start services
        uses: ./.github/actions/start-services
        with:
          database: mongodb

      - name: Resolve pinned Playwright version
        id: playwright-version
        # This job skips ./.github/actions/setup, so there's no node_modules for `pnpm ls` to
        # read (unlike elsewhere in this file) — read package.json directly instead. Strip a
        # leading ^/~ in case the pin ever becomes a range.
        run: |
          VERSION=$(node -p "require('./package.json').devDependencies['@playwright/test']" | sed -E 's/^[\^~]//')
          echo "Resolved Playwright version: $VERSION"
          echo "version=$VERSION" >> "$GITHUB_OUTPUT"

      # Every `needs_visual` path is also a `needs_build` path (a subset of `packages/**`/
      # `test/**`), so `build` always runs alongside this job — restoring here should always hit.
      # The container command below builds fresh as a fallback on the rare miss (e.g. a cache
      # eviction) rather than failing outright.
      - name: Restore dist output from build job
        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
        with:
          path: packages/*/dist
          key: dist-${{ github.sha }}

      # `pnpm install` still runs inside the container (see the job comment on why), but this
      # avoids re-downloading every package from the registry each run. Safe across environments
      # because pnpm's side-effects cache (built native addons like sharp) is itself keyed by
      # platform/arch/Node version, so a mismatched entry is rebuilt rather than reused. Read-write
      # (not cache/restore) so a lockfile change or a newly-cached package gets saved back.
      - name: Restore pnpm store cache
        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
        with:
          path: .pnpm-store
          key: visual-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}
          restore-keys: |
            visual-pnpm-store-

      # A long-lived, named container that the steps below `docker exec` into, so setup and the
      # actual test run show as separate steps instead of one `docker run ... && ... && ...` step
      # that buries the test output under several minutes of install/build output.
      - name: Start visual regression container
        # PLAYWRIGHT_VERSION is read from package.json, which on a `pull_request` checkout is
        # fork-controlled content — passed via env and referenced as "$PLAYWRIGHT_VERSION" so it's
        # shell *data*, never spliced as raw text into the script the way a `${{ }}` reference
        # inside `run:` would be.
        env:
          PLAYWRIGHT_VERSION: ${{ steps.playwright-version.outputs.version }}
        run: |
          docker run -d --rm \
            --name visual-regression \
            --network host \
            --ipc=host \
            -v "$PWD":/repo \
            -w /repo \
            -e CI=true \
            -e PAYLOAD_DATABASE=mongodb \
            -e NEXT_TELEMETRY_DISABLED=1 \
            "mcr.microsoft.com/playwright:v${PLAYWRIGHT_VERSION}-noble" \
            sleep infinity

      - name: Install dependencies
        run: |
          docker exec visual-regression bash -lc "
            apt-get update -qq -o Acquire::Retries=5 &&
            apt-get install -y -qq -o Acquire::Retries=5 build-essential python3 > /dev/null &&
            npm install -g pnpm@\$(grep '^pnpm ' .tool-versions | awk '{print \$2}') &&
            # --location=user avoids writing storeDir into pnpm-workspace.yaml, which pnpm
            # does by default when the cwd is a workspace root.
            pnpm config set store-dir /repo/.pnpm-store --location=user &&
            pnpm install --frozen-lockfile
          "

      - name: Build packages
        run: docker exec visual-regression bash -lc "[ -d packages/payload/dist ] || pnpm run build:all"

      - name: Prepare test environment
        run: docker exec visual-regression bash -lc "pnpm prepare-run-test-against-prod:ci"

      - name: Run visual regression tests
        run: docker exec visual-regression bash -lc "bash .github/scripts/visual/run-visual-suites.sh -- --fully-parallel"

      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        if: always()
        with:
          name: test-results-visual-regression
          path: test/test-results/
          if-no-files-found: ignore
          retention-days: 1

      - name: Stop visual regression container
        if: always()
        run: docker stop visual-regression

  # Build listed templates with packed local packages and then runs their int and e2e tests
  build-and-test-templates:
    permissions:
      actions: read
      contents: read
    runs-on: ubuntu-26.04
    needs: [changes, build]
    if: needs.changes.outputs.needs_build == 'true'
    name: build-template-${{ matrix.template }}-${{ matrix.database }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - template: blank
            database: mongodb

          - template: blank-tanstack
            database: mongodb

          - template: website
            database: mongodb

          - template: with-vercel-mongodb
            database: mongodb

          # Postgres
          - template: with-postgres
            database: postgres

          - template: with-vercel-postgres
            database: postgres

          - template: plugin

          # Re-enable once PG conncection is figured out
          # - template: with-vercel-website
          #   database: postgres

    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0

      - name: Node setup
        uses: ./.github/actions/setup
        with:
          restore-build: true

      - name: Start services
        id: db
        if: matrix.database
        uses: ./.github/actions/start-services
        with:
          database: ${{ matrix.database }}

      - name: Build Template
        run: |
          pnpm run script:pack --all --dest templates/${{ matrix.template }}
          pnpm run script:build-template-with-local-pkgs ${{ matrix.template }} $DB_CONNECTION
        env:
          NODE_OPTIONS: ${{ env.NODE_HEAP_HIGH }}
          DB_CONNECTION: ${{ steps.db.outputs.POSTGRES_URL || steps.db.outputs.MONGODB_URL }}

      - name: Setup Playwright
        uses: ./.github/actions/setup-playwright
        timeout-minutes: 10

      - name: Runs Template Int Tests
        run: pnpm --filter ${{ matrix.template }} run test:int
        env:
          NODE_OPTIONS: ${{ env.NODE_HEAP_HIGH }}
          PAYLOAD_DATABASE: ${{ matrix.database }}
          POSTGRES_URL: ${{ steps.db.outputs.POSTGRES_URL }}
          MONGODB_URL: ${{ steps.db.outputs.MONGODB_URL }}

      - name: Runs Template E2E Tests
        run: PLAYWRIGHT_JSON_OUTPUT_NAME=results_${{ matrix.template }}.json pnpm --filter ${{ matrix.template }} test:e2e
        env:
          NODE_OPTIONS: ${{ env.NODE_HEAP_HIGH }}
          PAYLOAD_DATABASE: ${{ matrix.database }}
          POSTGRES_URL: ${{ steps.db.outputs.POSTGRES_URL }}
          MONGODB_URL: ${{ steps.db.outputs.MONGODB_URL }}
          NEXT_TELEMETRY_DISABLED: 1

  # Fails if create-payload-app's build-script allowlist drifts from the blank template's deps:
  # scaffolds blank, installs it standalone under pnpm v11, and asserts no ERR_PNPM_IGNORED_BUILDS.
  check-template-build-approvals:
    runs-on: ubuntu-26.04
    needs: [changes, build]
    if: needs.changes.outputs.build_approvals == 'true'
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0

      - name: Node setup
        uses: ./.github/actions/setup

      - name: Check create-payload-app build approvals
        run: pnpm --filter scripts check-template-build-approvals

  tests-type-generation:
    permissions:
      actions: read
      contents: read
    runs-on: ubuntu-26.04
    needs: [changes, build]
    if: needs.changes.outputs.needs_tests == 'true'
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0

      - name: Node setup
        uses: ./.github/actions/setup
        with:
          restore-build: true

      - name: Generate Payload Types
        run: pnpm dev:generate-types fields

      - name: Generate GraphQL schema file
        run: pnpm dev:generate-graphql-schema graphql-schema-gen

  # Test content-api integration with packed packages. Each job runs its own
  # ephemeral Content API instance pulled from Figma's ECR, backed by a Postgres
  # service container, a Valkey container (required at startup for rate
  # limiting), and a LocalStack container for S3 storage tests. This
  # gives each run an isolated sandbox, avoiding data collisions between
  # concurrent CI runs and removing the need for shared credentials.
  tests-content-api:
    name: Content API Tests
    runs-on: ubuntu-26.04
    needs: [changes, build]
    # Skip fork PRs, bot PRs and audit fix branches. This job assumes an AWS role, and a bot PR
    # runs dependency versions that no person has reviewed.
    if: >-
      needs.changes.outputs.needs_tests == 'true'
      && github.event.pull_request.head.repo.fork == false
      && github.event.pull_request.user.type != 'Bot'
      && !startsWith(github.head_ref, 'ci/audit-deps-fix-')
    # Non-blocking while adapter coverage is incomplete. Once the full suite
    # passes, migrate to the `tests-int` matrix pattern (`pnpm test:int`
    # with --shard); `test:int:summary` cannot shard.
    continue-on-error: true
    permissions:
      actions: read
      id-token: write
      contents: read
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_DB: figma_content_api
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
        ports:
          - 5432:5432
        options: >-
          --health-cmd "pg_isready -U postgres"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
      localstack:
        image: localstack/localstack:4.10.0
        env:
          SERVICES: s3
        ports:
          - 4566:4566
        options: >-
          --health-cmd "curl -f http://localhost:4566/_localstack/health || exit 1"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 10
      valkey:
        image: valkey/valkey:8
        ports:
          - 6379:6379
        options: >-
          --health-cmd "valkey-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0

      - name: Node setup
        uses: ./.github/actions/setup
        with:
          restore-build: true

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4.3.1
        with:
          role-to-assume: arn:aws:iam::060562746757:role/content-api-external-ci-pull
          aws-region: us-west-2

      - name: Login to Amazon ECR
        uses: aws-actions/amazon-ecr-login@fa648b43de3d4d023bcb3f89ed6940096949c419 # v2.1.5

      # Figma publishes ECR tags as the 40-char SHA of the figma/figma commit
      # that built the image. There is no reliable floating alias, so pick the
      # most recently pushed SHA tag (skipping cosign `.sig` signatures).
      # `--max-results 100 --no-paginate` bounds the call to a single page;
      # without it the CLI pages through the full history and takes ~50s.
      - name: Resolve latest Content API image tag
        id: resolve-image
        run: |
          TAG=$(aws ecr describe-images \
            --repository-name payload/content-api \
            --region us-west-2 \
            --max-results 100 \
            --no-paginate \
            --query 'reverse(sort_by(imageDetails,& imagePushedAt))[].imageTags[]' \
            --output text | tr '\t' '\n' | grep -E '^[a-f0-9]{40}$' | head -n1)
          if [ -z "$TAG" ]; then
            echo "::error::No git-SHA-like tag found in payload/content-api ECR"
            exit 1
          fi
          echo "Using tag: $TAG"
          echo "tag=$TAG" >> "$GITHUB_OUTPUT"

      # Cache the image tarball by resolved SHA so repeated runs on the same
      # figma/figma image skip the ~55s ECR pull.
      - name: Cache Content API image
        id: cache-content-api-image
        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          path: /tmp/content-api-image.tar
          key: content-api-image-${{ steps.resolve-image.outputs.tag }}

      - name: Start Content API
        run: |
          IMAGE=060562746757.dkr.ecr.us-west-2.amazonaws.com/payload/content-api:${{ steps.resolve-image.outputs.tag }}
          if [ -f /tmp/content-api-image.tar ]; then
            echo "Loading Content API image from cache"
            docker load -i /tmp/content-api-image.tar
          else
            echo "Pulling Content API image from ECR"
            docker pull "$IMAGE"
            docker save -o /tmp/content-api-image.tar "$IMAGE"
          fi
          docker run -d \
            --name content-api \
            --network host \
            -e DATABASE_URL="postgresql://postgres:postgres@localhost:5432/figma_content_api" \
            -e NODE_ENV=development \
            -e TARGET_ENV=development \
            -e CONTENT_API_PORT=8080 \
            -e JWKS_URI=http://localhost:8080/.well-known/jwks.json \
            -e S3_ENDPOINT=http://localhost:4566 \
            -e RATE_LIMIT_VALKEY_URL=redis://localhost:6379 \
            -e VALKEY_URL=redis://localhost:6379 \
            "$IMAGE"

      - name: Wait for Content API to be ready
        run: |
          for i in $(seq 1 60); do
            if curl -sf http://localhost:8080/health > /dev/null; then
              echo "Content API is ready"
              exit 0
            fi
            sleep 2
          done
          echo "Content API failed to start within timeout"
          docker logs content-api || true
          exit 1

      - name: Run Content API Integration Tests
        continue-on-error: true
        run: pnpm test:int:summary
        env:
          NODE_OPTIONS: ${{ env.NODE_HEAP_HIGH }}
          PAYLOAD_DATABASE: content-api

      - name: Dump Content API logs on failure
        if: failure()
        run: docker logs content-api || true

  all-green:
    name: All Green
    if: always()
    runs-on: ubuntu-26.04
    needs:
      [
        lint,
        build,
        build-and-test-templates,
        tests-unit,
        tests-int,
        e2e-prep,
        tests-e2e,
        tests-a11y,
        tests-types,
        tests-type-generation,
        tests-content-api,
        visual-regression,
      ]

    steps:
      - if: ${{ always() && (contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')) }}
        run: exit 1

  publish-canary:
    name: Publish Canary
    runs-on: ubuntu-26.04
    if: ${{ needs.all-green.result == 'success' && github.ref_name == 'main' }}
    needs:
      - all-green

    steps:
      # debug github.ref output
      - run: |
          echo github.ref: ${{ github.ref }}
          echo isV3: ${{ github.ref == 'refs/heads/main' }}
  analyze:
    runs-on: ubuntu-26.04
    needs: [changes, build]
    timeout-minutes: 5
    permissions:
      contents: read # for checkout repository
      actions: read # for fetching base branch bundle stats
      pull-requests: write # for comments
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0

      - name: Node setup
        uses: ./.github/actions/setup
        with:
          restore-build: true

      - run: pnpm run build:bundle-for-analysis # Esbuild packages that haven't already been built in the build step for the purpose of analyzing bundle size
        env:
          DO_NOT_TRACK: 1 # Disable Turbopack telemetry

      - name: Analyze esbuild bundle size
        # Temporarily disable this for community PRs until this can be implemented in a separate workflow
        if: github.event.pull_request.head.repo.fork == false
        uses: exoego/esbuild-bundle-analyzer@42795b5c2540f6c622dc3445103fabbb7776a6f9 # v1.5.5
        with:
          metafiles: 'packages/payload/meta_index.json,packages/payload/meta_shared.json,packages/ui/meta_client.json,packages/ui/meta_shared.json,packages/next/meta_index.json,packages/richtext-lexical/meta_client.json'