From f877413e051ca3cfc9db2fa228829604aff5a851 Mon Sep 17 00:00:00 2001 From: Alaister Young Date: Tue, 4 Aug 2026 15:37:12 +0800 Subject: [PATCH] fix(docs ci): report Docs E2E check on every PR (#48681) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit \"Docs E2E\" is a required status check on master, but the workflow only triggered on docs-related paths. A required check whose workflow never starts creates no check run at all, so every non-docs PR sat blocked on \"Expected — waiting for status to be reported\" (e.g. #48677). The fix relies on the asymmetry in how branch protection treats the two kinds of skipping: a job skipped via an `if:` condition still reports a check run (counted as passing), while a workflow filtered out by `paths:` reports nothing. **Changed:** - Dropped the `paths:` filter from the `pull_request` trigger — the workflow now runs on every PR to master - Added a `dorny/paths-filter` step (same pattern as `studio-e2e-test.yml`) carrying the exact path list the trigger used to have; it runs before checkout using the API, so non-docs PRs skip the expensive full-history checkout entirely and report green in seconds - Folded the later \"Detect docs app changes\" step into the same filter (`docs_app` output) - Flipped downstream step guards from `skip != 'true'` to `skip == 'false'` so they stay off when the scope step itself was skipped (its output is empty then, and empty `!= 'true'` would have run them) This also fixes draft PRs: the job-level draft condition now produces a skipped-but-reported check instead of nothing, and `ready_for_review` triggers a real run. No behavior change for docs PRs or `workflow_dispatch` runs. The required-check context (`Docs E2E`) keeps its name. ## To test - On this PR (docs-related since it edits the workflow): the full suite should run as before - On a non-docs PR after merge: \"Docs E2E\" reports green in seconds instead of hanging as \"Expected\" - On a draft PR: check reports as skipped, run happens on ready-for-review ## Summary by CodeRabbit * **Tests** * Documentation end-to-end checks now report a status for every qualifying pull request. * Documentation changes automatically run the relevant browser tests and upload test reports. * Pull requests without documentation changes receive a successful skipped check. * Preview environment validation now runs only when documentation changes are detected. Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com> --- .github/workflows/docs-e2e.yml | 74 ++++++++++++++++++++-------------- 1 file changed, 43 insertions(+), 31 deletions(-) diff --git a/.github/workflows/docs-e2e.yml b/.github/workflows/docs-e2e.yml index 7a6b299186a..06c68d4c2f1 100644 --- a/.github/workflows/docs-e2e.yml +++ b/.github/workflows/docs-e2e.yml @@ -1,21 +1,14 @@ name: Docs E2E Tests +# "Docs E2E" is a required status check on master, so this workflow must +# produce a check run on every PR — a `paths` trigger filter would leave +# non-docs PRs waiting on a check that never reports. Path scoping happens +# in the "Detect changed paths" step instead; when nothing docs-related +# changed, the remaining steps are skipped and the check reports green. on: pull_request: types: [opened, synchronize, reopened, ready_for_review, converted_to_draft] branches: ['master'] - paths: - - 'apps/docs/content/guides/**/*.mdx' - - 'apps/docs/content/troubleshooting/**/*.mdx' - - 'apps/docs/content/_partials/**' - - 'e2e/docs/features/**' - - 'e2e/docs/utils/**' - - 'e2e/docs/scripts/**' - - 'e2e/docs/playwright.config.ts' - - 'e2e/docs/package.json' - - 'e2e/docs/tsconfig.json' - - 'pnpm-lock.yaml' - - '.github/workflows/docs-e2e.yml' workflow_dispatch: inputs: base_url: @@ -49,7 +42,32 @@ jobs: runs-on: blacksmith-4vcpu-ubuntu-2404 steps: + # Runs before checkout — reads the PR file list from the API. `docs` + # mirrors the path scope this workflow used to have as a trigger filter; + # `docs_app` decides whether a Vercel docs preview exists to test against. + - name: Detect changed paths + id: changes + if: github.event_name == 'pull_request' + uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2 + with: + filters: | + docs: + - 'apps/docs/content/guides/**/*.mdx' + - 'apps/docs/content/troubleshooting/**/*.mdx' + - 'apps/docs/content/_partials/**' + - 'e2e/docs/features/**' + - 'e2e/docs/utils/**' + - 'e2e/docs/scripts/**' + - 'e2e/docs/playwright.config.ts' + - 'e2e/docs/package.json' + - 'e2e/docs/tsconfig.json' + - 'pnpm-lock.yaml' + - '.github/workflows/docs-e2e.yml' + docs_app: + - 'apps/docs/**' + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + if: github.event_name == 'workflow_dispatch' || steps.changes.outputs.docs == 'true' with: persist-credentials: false # Need full history on PRs so we can diff against the base branch. @@ -65,6 +83,7 @@ jobs: apps/docs/scripts/federated-content/sources - name: Use Node.js + if: github.event_name == 'workflow_dispatch' || steps.changes.outputs.docs == 'true' uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version-file: '.nvmrc' @@ -73,6 +92,7 @@ jobs: # URLs. Harness-only PRs resolve to skip=true and exit before Playwright. - name: Resolve docs E2E scope id: scope + if: github.event_name == 'workflow_dispatch' || steps.changes.outputs.docs == 'true' env: EVENT_NAME: ${{ github.event_name }} BASE_REF: ${{ github.base_ref }} @@ -98,29 +118,21 @@ jobs: run: echo "No in-scope docs pages changed; skipping Playwright suite." - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9 - if: steps.scope.outputs.skip != 'true' + if: steps.scope.outputs.skip == 'false' name: Install pnpm with: run_install: false - name: Enable pnpm store cache - if: steps.scope.outputs.skip != 'true' + if: steps.scope.outputs.skip == 'false' uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version-file: '.nvmrc' cache: 'pnpm' # Vercel skips the docs preview when a PR only changes the harness - # (e2e/docs, workflow). Wait for a preview only when apps/docs changed. - - name: Detect docs app changes - if: steps.scope.outputs.skip != 'true' && github.event_name == 'pull_request' - id: filter - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2 - with: - filters: | - docs_app: - - 'apps/docs/**' - + # (e2e/docs, workflow), so wait for a preview only when apps/docs changed. + # # Vercel's GitHub App stopped writing GitHub Deployment objects on # 2026-02-17 (broken app auth), so vercel/wait-for-deployment-action # times out polling that API even though the preview builds fine. @@ -128,7 +140,7 @@ jobs: # those — then resolve the deployment it points to via Vercel's own API # to get the actual preview URL. See scripts/waitForVercelDocsPreview.js. - name: Wait for Vercel docs preview - if: steps.scope.outputs.skip != 'true' && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && steps.filter.outputs.docs_app == 'true' + if: steps.scope.outputs.skip == 'false' && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && steps.changes.outputs.docs_app == 'true' id: deployment run: node scripts/waitForVercelDocsPreview.js env: @@ -138,13 +150,13 @@ jobs: VERCEL_TEAM_ID: ${{ secrets.VERCEL_TEAM_ID }} - name: Resolve base URL - if: steps.scope.outputs.skip != 'true' + if: steps.scope.outputs.skip == 'false' id: base-url env: EVENT_NAME: ${{ github.event_name }} BASE_URL_INPUT: ${{ inputs.base_url }} DEPLOYMENT_URL: ${{ steps.deployment.outputs.deployment-url }} - DOCS_APP_CHANGED: ${{ steps.filter.outputs.docs_app }} + DOCS_APP_CHANGED: ${{ steps.changes.outputs.docs_app }} run: | if [ "$EVENT_NAME" = "workflow_dispatch" ]; then printf 'url=%s\n' "$BASE_URL_INPUT" >> "$GITHUB_OUTPUT" @@ -159,15 +171,15 @@ jobs: fi - name: Install dependencies - if: steps.scope.outputs.skip != 'true' + if: steps.scope.outputs.skip == 'false' run: pnpm install --frozen-lockfile --filter=e2e-docs... - name: Install Playwright Chromium - if: steps.scope.outputs.skip != 'true' + if: steps.scope.outputs.skip == 'false' run: pnpm -C e2e/docs exec playwright install chromium --with-deps --only-shell - name: Run docs E2E - if: steps.scope.outputs.skip != 'true' + if: steps.scope.outputs.skip == 'false' working-directory: e2e/docs run: pnpm run e2e:docs env: @@ -176,7 +188,7 @@ jobs: VERCEL_AUTOMATION_BYPASS_SECRET: ${{ steps.base-url.outputs.use_bypass == 'true' && secrets.VERCEL_AUTOMATION_BYPASS_DOCS || '' }} - name: Upload Playwright report - if: failure() && steps.scope.outputs.skip != 'true' + if: failure() && steps.scope.outputs.skip == 'false' uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 with: name: docs-playwright-report