@joshuafolkken/kit 1.872.0

package/templates/workflows/ci.yml

@@ -0,0 +1,639 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+
+  pull_request:
+    branches: [main]
+
+# A push run is grouped by the commit it carries, so a later push to the default branch never
+# cancels an earlier one. Without the sha every such push shares one group — `github.ref` is
+# `refs/heads/main` for all of them — and the run that would have reported the commit that changed
+# the version disappears with nothing reported as failed (joshuafolkken/kit#1481).
+# The sha is added for `push` only: added unconditionally it would also stop a new push to a pull
+# request from cancelling that pull request's older runs, which is the saving this block exists for.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}${{ github.event_name == 'push' && format('-{0}', github.sha) || '' }}
+  cancel-in-progress: true
+
+# Which browsers the plain-runner fallback downloads when the MCR image could not be resolved.
+# Declared once here because two jobs install them and the two lists must never disagree.
+# chromium is the default because that is the single project kit scaffolds; a consumer whose
+# config drives more sets the JOSH_PLAYWRIGHT_BROWSERS repository variable to a space-separated
+# list (e.g. `chromium firefox webkit`) instead of editing this file, which josh sync overwrites.
+env:
+  JOSH_PLAYWRIGHT_BROWSERS: ${{ vars.JOSH_PLAYWRIGHT_BROWSERS || 'chromium' }}
+
+jobs:
+  playwright-image:
+    name: Resolve Playwright image
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    permissions:
+      contents: read
+    outputs:
+      # JSON consumed via fromJSON() as the job-level `container` value: an object
+      # when the image exists, the literal `null` when it does not (= no container).
+      container: ${{ steps.resolve.outputs.container }}
+      # 'true' only when Playwright is a dependency but its image is unavailable, i.e.
+      # exactly when a job must download browsers itself.
+      should_install_browsers: ${{ steps.resolve.outputs.should_install_browsers }}
+      # The browser names the jobs below pass to `playwright install`, sanitized here so the
+      # two install steps share one list and one set of rules for what may reach a command line.
+      browsers: ${{ steps.resolve.outputs.browsers }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      # The MCR image lags the npm publish by days, so a version-derived tag is not
+      # guaranteed to exist. Probe it first and fall back to a plain runner instead of
+      # emitting a tag that 404s and kills every dependent job before it starts.
+      - name: Resolve image
+        id: resolve
+        run: |
+          # Both dependency blocks, because `e2e-detect` below enables the E2E job from file
+          # presence alone: a project that declares @playwright/test under `dependencies` would
+          # otherwise be told it has no Playwright, get no container *and* no browser install,
+          # and run its suite on a bare runner. Whitelist the characters too: the value lands in
+          # $GITHUB_OUTPUT as JSON, so a newline or quote smuggled into the manifest could forge
+          # an extra output line.
+          version=$(node -p "const manifest = require('./package.json'); manifest.devDependencies?.['@playwright/test'] ?? manifest.dependencies?.['@playwright/test'] ?? ''" | tr -cd 'A-Za-z0-9.-')
+
+          # Sanitized once, here, for both jobs that install browsers: the value comes from
+          # repository settings and is interpolated into their command line, so only letters,
+          # dashes and the spaces between them survive. Uppercase is kept on purpose — a mistyped
+          # `Chromium` then reaches Playwright as an unknown browser and fails at the install
+          # step, where the mistake is, rather than being silently narrowed to chromium and
+          # resurfacing much later as a missing executable.
+          set -- $(printf '%s' "${JOSH_PLAYWRIGHT_BROWSERS}" | tr -cd 'A-Za-z -')
+          # Never empty: `playwright install` with no browser named fetches chromium *and*
+          # firefox *and* webkit plus ffmpeg, roughly 1 GB, which is the download this knob
+          # exists to avoid and which the 8-minute `checks` budget does not survive.
+          [ "$#" -gt 0 ] || set -- chromium
+          browsers="$*"
+          echo "browsers=${browsers}" >> "$GITHUB_OUTPUT"
+
+          if [ -z "${version}" ]; then
+            echo 'container=null' >> "$GITHUB_OUTPUT"
+            echo 'should_install_browsers=false' >> "$GITHUB_OUTPUT"
+            echo 'Playwright is not a dependency; every job runs on the plain runner.'
+            exit 0
+          fi
+
+          tag="v${version}-noble"
+          image="mcr.microsoft.com/playwright:${tag}"
+          status=$(curl -sS -o /dev/null -w '%{http_code}' --max-time 30 --retry 2 \
+            -H 'Accept: application/vnd.docker.distribution.manifest.list.v2+json' \
+            "https://mcr.microsoft.com/v2/playwright/manifests/${tag}" || true)
+
+          if [ "${status}" = '200' ]; then
+            printf 'container={"image":"%s","options":"--user root"}\n' "${image}" >> "$GITHUB_OUTPUT"
+            echo 'should_install_browsers=false' >> "$GITHUB_OUTPUT"
+            echo "Resolved Playwright container image ${image}."
+          else
+            echo 'container=null' >> "$GITHUB_OUTPUT"
+            echo 'should_install_browsers=true' >> "$GITHUB_OUTPUT"
+            echo "::warning::Playwright image ${image} could not be resolved on MCR (HTTP ${status}). Running on the plain runner and installing ${browsers} instead (set the JOSH_PLAYWRIGHT_BROWSERS repository variable to change the list)."
+          fi
+
+  checks:
+    name: Checks
+    needs: playwright-image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+    container: ${{ fromJSON(needs.playwright-image.outputs.container) }}
+    timeout-minutes: 8
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: '24'
+          registry-url: 'https://npm.pkg.github.com'
+
+      - name: Resolve pnpm version
+        id: pnpm-version
+        run: |
+          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
+          test -n "$version"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Setup pnpm
+        uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+        with:
+          version: ${{ steps.pnpm-version.outputs.version }}
+          install: false
+
+      - name: Resolve pnpm store path
+        run: echo "PNPM_STORE_PATH=$(pnpm store path)" >> "$GITHUB_ENV"
+
+      - name: Setup pnpm store cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ env.PNPM_STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Setup ESLint cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        id: eslint-cache
+        with:
+          path: |
+            .eslintcache
+          # joshuafolkken/kit#1347: the config inputs are `.js`, and the glob used to name `.ts` — which
+          # in `eslint/` is only the test files. So a rule edit left the key unchanged while a test edit
+          # busted it, the exact inverse of what invalidates a cache entry. The fingerprint in
+          # `eslint/config-fingerprint.js` now invalidates the entries themselves; this key has to move
+          # with it, or a rule edit would restore a cache whose every entry is stale, lint cold, and
+          # save nothing back under the key it already hit — a cold lint on every later run.
+          # joshuafolkken/kit#2054: the commit sha makes each run save its warmed cache under a fresh
+          # key, while the sha-less prefix restores the newest entry from an earlier run.
+          key: ${{ runner.os }}-eslint-cache-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-eslint-cache-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-
+            ${{ runner.os }}-eslint-cache-${{ hashFiles('pnpm-lock.yaml') }}-
+            ${{ runner.os }}-eslint-cache-
+
+      - name: Setup cspell cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        id: cspell-cache
+        with:
+          path: |
+            .cspellcache
+          key: ${{ runner.os }}-cspell-cache-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-cspell-cache-${{ hashFiles('pnpm-lock.yaml') }}-
+            ${{ runner.os }}-cspell-cache-
+
+      - name: Setup safe-chain
+        run: pnpm dlx @aikidosec/safe-chain@1.5.1 setup-ci
+
+      - name: Install dependencies
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Run spell check
+        run: pnpm josh cspell:dot
+
+      - name: Prepare
+        run: pnpm prepare
+
+      - name: Run type check
+        run: pnpm exec svelte-kit sync && pnpm exec svelte-check --tsconfig ./tsconfig.json --threshold error
+
+      - name: Run prettier check
+        run: pnpm exec prettier --check .
+
+      # Build before eslint so generated outputs exist for type-aware linting.
+      # The same build output is reused by the size check below.
+      - name: Build
+        run: pnpm build
+
+      - name: Run eslint check
+        run: pnpm exec eslint . --cache --cache-strategy content
+
+      # Vitest browser-mode projects (*.svelte.test.ts) drive a real Playwright browser,
+      # which the container image ships but a plain runner does not. Same guard as e2e.
+      # Named rather than left to the default, which downloads every browser Playwright ships
+      # (~1 GB) on the one path that has the least headroom to spare. Left unquoted below so a
+      # multi-browser list splits into arguments; the resolve job already whitelisted it, so
+      # nothing but browser names can reach the command line.
+      - name: Install Playwright browsers
+        if: needs.playwright-image.outputs.should_install_browsers == 'true'
+        env:
+          PLAYWRIGHT_BROWSERS: ${{ needs.playwright-image.outputs.browsers }}
+        run: ./node_modules/.bin/playwright install --with-deps ${PLAYWRIGHT_BROWSERS}
+
+      - name: Run unit tests
+        run: pnpm josh test:unit
+
+      - name: Check bundle size
+        run: pnpm size-limit
+
+  security:
+    name: Security Audit
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Run security audit
+        uses: google/osv-scanner-action/osv-scanner-action@9a498708959aeaef5ef730655706c5a1df1edbc2 # v2.3.8
+        with:
+          scan-args: --lockfile=pnpm-lock.yaml
+
+  e2e-detect:
+    name: Detect E2E
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    permissions:
+      contents: read
+    outputs:
+      enabled: ${{ steps.check.outputs.enabled }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      # The same rule `scripts/test/test-e2e-guard.ts` applies locally, so a suite that runs under
+      # `pnpm josh test:e2e` is a suite CI runs too. Every `*.e2e.{ts,js}` outside `node_modules`
+      # counts, at any depth; the guard's glob leaves dot-directories out by default, which is what
+      # the second prune term reproduces. The config filename is deliberately not consulted any
+      # more. Playwright accepts `playwright.config.js` as readily as `.ts`, and requiring one
+      # spelling made a project using the other read as "no E2E": the job's `if:` went false,
+      # GitHub recorded it as skipped, the status-check list counted the skip as a pass, and the
+      # merge went through with the suite never run. The same held for a spec kept anywhere but
+      # `tests` or `src/routes` (joshuafolkken/kit#991). The agreement is executed rather than
+      # asserted in prose: `scripts/ci/ci-yml-e2e-detect.test.ts` runs this very script against
+      # fixtures and compares its verdict to the guard's.
+      #
+      # One difference from the guard is deliberate and one-sided. The guard also skips when
+      # `@playwright/test` is not installed, which is what keeps that optional peer optional for
+      # the pre-push hook; here a spec enables the job whatever the manifest says, so a spec that
+      # cannot run ends red instead of silently green. Enabling more than the guard is safe —
+      # enabling less is the defect above, so no condition may be added that narrows this.
+      #
+      # Deliberately not `find ... | grep -q .`: `grep -q` exits on the first match and leaves
+      # `find` to be killed by the closed pipe, which is invisible under the default `bash -e` and
+      # decides the whole question under `bash -eo pipefail` — the shell GitHub selects for a step
+      # that declares `shell: bash`, or for every step once a `defaults: run: shell: bash` block is
+      # added at workflow or job level. The pipeline's status would then be 141, the `else` branch
+      # would be taken, and a repository full of specs would emit `enabled=false`: this defect
+      # again, reintroduced by a shell detail. Command substitution has no pipeline to
+      # fail, and `-print -quit` stops the walk at the first spec instead of enumerating the tree.
+      - name: Detect E2E specs
+        id: check
+        run: |
+          if [ -n "$(find . -mindepth 1 \( -name node_modules -o -name '.*' \) -prune \
+            -o \( -name '*.e2e.ts' -o -name '*.e2e.js' \) -print -quit)" ]; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  e2e:
+    name: E2E
+    needs: [playwright-image, e2e-detect]
+    if: needs.e2e-detect.outputs.enabled == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+    container: ${{ fromJSON(needs.playwright-image.outputs.container) }}
+    # Derived, not guessed: a retried run costs setup + two attempts + the upload of the first
+    # attempt's evidence. The retry repeats the whole `Run E2E tests` step — Playwright's CI
+    # webServer builds the app before serving it, so the second attempt pays for the build again,
+    # not just the specs — while checkout/install/prepare are shared. Any suite that fit the old
+    # 10-minute budget had setup + one attempt <= 10, which bounds a single attempt at 10; the
+    # extra attempt therefore adds at most 10, and the evidence upload (a failed run keeps videos
+    # and traces, so it is not instant) is allowed 5 on top. Running out mid-retry would end the
+    # job as `cancelled`, withholding the release exactly like the crash this retry absorbs and
+    # truncating the uploads that would explain it, so the headroom is the point. The cost is that
+    # a hung preview server holds a runner for 25 minutes rather than 10 before the job is killed.
+    timeout-minutes: 25
+    # Better Auth rejects any origin its BETTER_AUTH_URL does not name, so an unpinned job — one
+    # that reaches the app's production value through a repository variable or the app's own
+    # config — fails every spec. Pinning it to the preview server the suite talks to is the fix,
+    # and it has to be the port that server actually listens on. 4173 is correct here
+    # because `PORT_SEED` — the personal offset `playwright.config.ts` resolves the preview port
+    # from — is not committed (it lives in a gitignored `.env`) and is not set anywhere in this
+    # workflow, so the port resolves to its base, 4173, on every CI run. That is the invariant to
+    # preserve, not a constant in `playwright.config.ts`: the port there is seed-derived, so it is
+    # 4173 in CI and may be anything locally. The one setting that would move the port and leave
+    # this URL behind is an `env` entry for the seed in this file, at workflow or job level. A
+    # repository or organization variable would not: it reaches a step only through an explicit
+    # `vars.PORT_SEED` expression, and nothing here writes one. If a seeded CI job is ever wanted,
+    # derive this URL from `josh port preview` in the same job instead.
+    env:
+      BETTER_AUTH_URL: http://localhost:4173
+      # A crashing preview worker prints nothing but an empty `✘ [ERROR]` to the job log;
+      # the stack trace goes to wrangler's debug log file, which defaults to the global
+      # config dir (/github/home/.config/.wrangler/logs) and dies with the runner. Point it
+      # inside the workspace so the upload below can reach it. Kept relative on purpose:
+      # `${{ github.workspace }}` resolves to the host path in a container job, which is not
+      # where the workspace is mounted. The preview server inherits the workspace as its cwd
+      # and upload-artifact resolves a relative path against the same directory, so a
+      # relative path is the one spelling both sides agree on, container or plain runner.
+      WRANGLER_LOG_PATH: e2e-web-server-logs/
+      # No WRANGLER_LOG bump: that variable gates console output only — the debug file
+      # records every level unconditionally. Sanitization (wrangler's own default) is
+      # pinned here so a repository-level opt-out cannot leak tokens into the artifact.
+      WRANGLER_LOG_SANITIZE: 'true'
+      # Two rules, each declared once. E2E_RETRY_ENABLED says a run may survive its first failure
+      # long enough for the chain below to decide what to do about it; E2E_RETRY_UNCONDITIONAL says
+      # it may retry without having to justify itself. A push to the default branch is both: its
+      # failure withholds a release, and no signature is worth being wrong about there (#783). A
+      # pull request is only the first — it survives its first failure so the check below can read
+      # the preview server's log, and retries solely when that log says the server process died
+      # (#872). Keeping the two apart is what stops a failing suite from being retried until it
+      # passes, which is the masking the original default-branch-only gate was written to prevent.
+      E2E_RETRY_ENABLED:
+        ${{ (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name ==
+        'pull_request' }}
+      E2E_RETRY_UNCONDITIONAL: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: '24'
+          registry-url: 'https://npm.pkg.github.com'
+
+      - name: Resolve pnpm version
+        id: pnpm-version
+        run: |
+          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
+          test -n "$version"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Setup pnpm
+        uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+        with:
+          version: ${{ steps.pnpm-version.outputs.version }}
+          install: false
+
+      - name: Resolve pnpm store path
+        run: echo "PNPM_STORE_PATH=$(pnpm store path)" >> "$GITHUB_ENV"
+
+      - name: Setup pnpm store cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ env.PNPM_STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Setup build cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        id: build-cache
+        with:
+          path: |
+            .svelte-kit
+          key: ${{ runner.os }}-build-cache-e2e-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('svelte.config.js', 'vite.config.ts', 'tsconfig.json', 'src/lib/server/auth.ts') }}
+          restore-keys: |
+            ${{ runner.os }}-build-cache-e2e-${{ hashFiles('pnpm-lock.yaml') }}-
+            ${{ runner.os }}-build-cache-e2e-
+
+      - name: Setup safe-chain
+        run: pnpm dlx @aikidosec/safe-chain@1.5.1 setup-ci
+
+      - name: Install dependencies
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      # --ignore-scripts suppresses the install-time `prepare`, so generated framework
+      # files never appear. Playwright >= 1.62 hard-throws when a tsconfig `extends`
+      # target is missing, and a SvelteKit tsconfig extends the generated
+      # .svelte-kit/tsconfig.json — without this step `playwright test` aborts before
+      # the first test (#689). The `checks` job already runs the same step.
+      - name: Prepare
+        run: pnpm prepare
+
+      # Only needed on the fallback path: the container image already ships browsers
+      # matching its own Playwright version. Invoked through the local bin rather than
+      # `pnpm exec` because Sonar's S6505 misreads `pnpm ... install` as a package
+      # install missing --ignore-scripts (this downloads browser binaries, not packages).
+      # Same named-browsers list as the checks job above, for the same reason.
+      - name: Install Playwright browsers
+        if: needs.playwright-image.outputs.should_install_browsers == 'true'
+        env:
+          PLAYWRIGHT_BROWSERS: ${{ needs.playwright-image.outputs.browsers }}
+        run: ./node_modules/.bin/playwright install --with-deps ${PLAYWRIGHT_BROWSERS}
+
+      # Only a run allowed to retry may continue past a failure: a push to the default branch gates
+      # the auto-tag dispatch below, so one transient crash there withholds the release until a
+      # human notices and re-runs the job by hand (#783). A pull request now continues past its
+      # first failure too — but only as far as the check below, which reports whether there was a
+      # reason. When there was none, `Report the unretried E2E failure` puts the job back to red,
+      # so surviving the failure never turns into shipping it.
+      #
+      # With this workflow's two triggers the flag is constantly true, so the expression currently
+      # decides nothing. It is written this way for the trigger that is not here yet — a schedule or
+      # a manual dispatch has no business surviving its first failure, and would have to remember to
+      # add the term back if it were hard-coded to `true` now.
+      - name: Run E2E tests
+        id: e2e_tests
+        continue-on-error: ${{ env.E2E_RETRY_ENABLED == 'true' }}
+        run: pnpm exec playwright test
+
+      # Did the preview server die? A fact, published once so every step below reads one output
+      # instead of re-deriving it. It is a kit command rather than shell in this file because this
+      # is the one part of the chain that can be wrong without anyone noticing: a signature that
+      # stops matching silently stops retrying. As a script it has unit tests
+      # (`scripts/test/e2e-retry-check.test.ts`) that fail the build when the rule drifts; as a `run:`
+      # block it would have none. The log it reads is wrangler's own debug output, already captured
+      # for the artifact below — not Playwright's reporter output, which is reshaped between
+      # releases and would need re-deriving each time.
+      #
+      # E2E_RETRY_UNCONDITIONAL is applied in the conditions below rather than passed down to this
+      # command, and that placement is load-bearing. continue-on-error means a step that errors
+      # publishes no output at all, so a default-branch push whose rule lived in here would lose the
+      # retry it must never lose — the withheld release of #783, reintroduced by the diagnostic
+      # meant to improve on it. Read as an OR up there, an unreadable log costs a pull request its
+      # retry (the status quo, safe) and costs the default branch nothing.
+      - name: Check whether the preview server crashed
+        id: e2e_retry_check
+        if: ${{ !cancelled() && env.E2E_RETRY_ENABLED == 'true' && steps.e2e_tests.outcome == 'failure' }}
+        continue-on-error: true
+        run: pnpm josh e2e:retry-check
+
+      # The retry overwrites both output directories, so the first attempt's evidence is moved
+      # aside before it starts and uploaded under its own -attempt-1 names. This is what keeps a
+      # green retry honest: the crash it papered over stays fully diagnosable, which is why this
+      # retry could only land after the web server log was being captured at all (#781).
+      # Every step from here to the retry carries the same condition, and each part of it is
+      # load-bearing. !cancelled() rather than the implicit success(): a bare outcome check is
+      # ANDed with success(), so a hiccup in one of these steps would skip the rest — including
+      # the retry, withholding the release over the diagnostics — while a superseded run being
+      # cancelled by the concurrency group above should not start a second suite.
+      # For a pull request, the retry chain starts only when the preview server crashed;
+      # otherwise its report and log stay from the single attempt. A default-branch push
+      # retries regardless of the crash check.
+      #
+      # This step never fails the job: it exists to save evidence, and a move that does not happen
+      # is announced instead, because the retry below will overwrite what was left behind.
+      # continue-on-error is what makes that hold rather than merely intend it. The rename is
+      # already kept from tripping `-e` by the `if !` around it, but the annotations are not: a
+      # write error exits non-zero and ends the step, on a runner that has just filled its disk
+      # with the failed attempt's videos, traces and report. Failing here would withhold the
+      # release even when the retry passes — the outcome #783 was opened to prevent (#789).
+      - name: Preserve first attempt output
+        if: >-
+          ${{ !cancelled() && env.E2E_RETRY_ENABLED == 'true' && steps.e2e_tests.outcome ==
+          'failure' && (env.E2E_RETRY_UNCONDITIONAL == 'true' ||
+          steps.e2e_retry_check.outputs.crashed == 'true') }}
+        continue-on-error: true
+        run: |
+          # Announced, not just archived: a retry that passes leaves a green job, and without an
+          # annotation a test failing half the time would ship release after release with nothing
+          # on the run to read. Worded so it stays true whether or not the attempt got as far as
+          # writing a report — it points at the naming convention, never at a specific artifact.
+          echo "::warning::The first E2E attempt failed and is being retried; whatever output it produced is attached to this run under the -attempt-1 artifact names."
+
+          for dir in playwright-report "${WRANGLER_LOG_PATH%/}"; do
+            if [ -d "${dir}" ] && ! mv "${dir}" "${dir}-attempt-1"; then
+              echo "::warning::Could not set ${dir} aside; the retry will overwrite the first attempt's copy."
+            fi
+          done
+
+      # continue-on-error for the same reason the move above carries it: collecting evidence must
+      # not be what decides the release. Without it a transient artifact-service error here would
+      # end the job red even after the retry passed — withholding the tag exactly as the crash
+      # did. if-no-files-found: ignore covers the directory the move could not rename, and the
+      # consumer whose preview script is not wrangler and writes no log at all.
+      - name: Upload first attempt test results
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: >-
+          ${{ !cancelled() && env.E2E_RETRY_ENABLED == 'true' && steps.e2e_tests.outcome ==
+          'failure' && (env.E2E_RETRY_UNCONDITIONAL == 'true' ||
+          steps.e2e_retry_check.outputs.crashed == 'true') }}
+        continue-on-error: true
+        with:
+          name: playwright-report-attempt-1
+          path: playwright-report-attempt-1/
+          if-no-files-found: ignore
+          retention-days: 30
+
+      - name: Upload first attempt web server log
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: >-
+          ${{ !cancelled() && env.E2E_RETRY_ENABLED == 'true' && steps.e2e_tests.outcome ==
+          'failure' && (env.E2E_RETRY_UNCONDITIONAL == 'true' ||
+          steps.e2e_retry_check.outputs.crashed == 'true') }}
+        continue-on-error: true
+        with:
+          name: e2e-web-server-log-attempt-1
+          path: e2e-web-server-logs-attempt-1/
+          if-no-files-found: ignore
+          retention-days: 30
+
+      # One retry, and only after a failure — a green run never starts this step and pays nothing.
+      # On the default branch it is unconditional: a rule that can stop matching is not something
+      # to put between a merge and its release, so the price is paid there instead — a genuinely
+      # broken suite costs one extra E2E run before it reports red, and a real failure that happens
+      # to pass on the second attempt is reported green, with the -attempt-1 artifacts above the
+      # only thing that makes that case recoverable rather than invisible.
+      #
+      # A pull request pays neither price, because it retries only on the crash signature. Both
+      # ways of being wrong there are cheap, which is what makes the signature acceptable: a false
+      # positive spends one extra run and still reports red, since the second attempt fails too,
+      # and a false negative leaves the status quo of a human pressing re-run. The signature is
+      # read from wrangler's log rather than Playwright's reporter output for the same reason the
+      # default branch does not use it at all — reporter output is reshaped between releases,
+      # while `Error in ProxyController` is the server naming its own death.
+      #
+      # Known limit: nothing frees the preview port between attempts. A first attempt whose server
+      # died releases it, which is the case this retry targets; a server that survived as an
+      # orphan holding the port makes the retry stop at "port already used" instead. That is a
+      # loud, diagnosable failure, and killing by port would need tooling the container image does
+      # not guarantee and a guess at which process a consumer's preview script actually started.
+      - name: Retry E2E tests
+        id: e2e_retry
+        if: >-
+          ${{ !cancelled() && env.E2E_RETRY_ENABLED == 'true' && steps.e2e_tests.outcome ==
+          'failure' && (env.E2E_RETRY_UNCONDITIONAL == 'true' ||
+          steps.e2e_retry_check.outputs.crashed == 'true') }}
+        run: pnpm exec playwright test
+
+      # The first attempt was allowed to fail only so the check above could read the log. When no
+      # retry followed, nothing in the job is red any more, and the suite's failure would ship as a
+      # green check — the one way this change could be worse than the default-branch-only gate it
+      # replaces. This step is what turns a survived failure back into a failure.
+      #
+      # It is keyed to the retry having been skipped rather than to the event name, so every way of
+      # arriving here is covered by one rule: a genuinely failing suite, a log with no signature, a
+      # consumer that writes no log at all, and a check step that errored all reach this point by
+      # the same path, and all four must be red. A default-branch push cannot reach it, because the
+      # flag alone satisfies the retry condition above — and the event is deliberately not named
+      # here even so. A gate that excused the default branch would, on any future path that skipped
+      # the retry there, let a swallowed failure ship green and take the release with it; staying
+      # unconditional costs nothing and cannot fail that way.
+      - name: Report the unretried E2E failure
+        if: >-
+          ${{ !cancelled() && steps.e2e_tests.outcome == 'failure' && steps.e2e_retry.outcome ==
+          'skipped' }}
+        run: |
+          echo "::error::The E2E suite failed and no preview server crash was detected, so it was not retried."
+          exit 1
+
+      # continue-on-error for the same reason the -attempt-1 uploads above carry it, and this is
+      # the step where it matters most: it runs on always(), so it is the one evidence step still
+      # executing after a retry that passed. Without the guard a transient artifact-service error
+      # here would end the job red on a run whose tests are green — skipping the auto-tag dispatch
+      # below and withholding the release exactly as the crash the retry absorbed would have
+      # (#809). The failure is not swallowed: continue-on-error keeps the step's own outcome
+      # `failure`, so it stays marked red on the run and a missing report is never silent.
+      - name: Upload test results
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
+        continue-on-error: true
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+
+      # Separate from playwright-report: that artifact explains which tests failed, this one
+      # explains why the server they talk to went away. Consumers whose preview script is not
+      # wrangler write nothing here, so a missing directory is ignored rather than fatal.
+      # cancelled() is part of the condition because a preview server that hangs instead of
+      # crashing burns the job's timeout, and GitHub cancels a timed-out job rather than
+      # failing it — the one case where a `failure()`-only step would skip the log that
+      # explains the hang.
+      #
+      # continue-on-error completes the rule rather than fixing a live exposure: this step only
+      # runs once the job is already failing or cancelled, so its own failure withholds nothing
+      # that was not already withheld. It carries the guard so the rule holds for every artifact
+      # the job publishes instead of for the ones that need it today — a later condition change
+      # here would otherwise reintroduce #809 in a step nobody re-audits.
+      - name: Upload web server log
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: failure() || cancelled()
+        continue-on-error: true
+        with:
+          name: e2e-web-server-log
+          path: e2e-web-server-logs/
+          if-no-files-found: ignore
+          retention-days: 30
+
+  notify-auto-tag:
+    name: Notify Auto Tag
+    needs: [checks, security, e2e-detect, e2e]
+    if: |
+      always() &&
+      github.event_name == 'push' &&
+      github.ref == 'refs/heads/main' &&
+      needs.checks.result == 'success' &&
+      needs.security.result == 'success' &&
+      needs.e2e-detect.result == 'success' &&
+      (needs.e2e.result == 'success' || needs.e2e.result == 'skipped')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Dispatch auto-tag
+        uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4.0.1
+        with:
+          event-type: ci-passed-on-main
+          client-payload: '{"sha": "${{ github.sha }}"}'