Vercel Deployment Checks einrichten: Playwright E2E-Tests vor dem Go-Live

Georg Dörgeloh 27. Januar 2026

Stell dir vor: Es ist Freitagnachmittag. Du mergst einen “schnellen Fix” nach Production. Vercel deployt ihn in 47 Sekunden (weil Vercel einfach großartig ist). Du klappst deinen Laptop zu, zufrieden mit dir selbst.

Dann vibriert dein Handy. Und nochmal. Und nochmal.

Der Checkout-Button ist kaputt. In deinem Online-Shop. Zur Hauptgeschäftszeit.

Wenn es nur eine Möglichkeit gäbe, E2E-Tests automatisch auszuführen, bevor das Deployment live geht…

Spoiler: Die gibt es. Sie heißt Deployment Checks, und diese Anleitung zeigt dir, wie du sie einrichtest.

Was wir bauen

Am Ende dieser Anleitung hast du ein Setup, bei dem:

Du Code in deinen Production Branch pushst
Vercel deine App baut (aber noch nicht live schaltet)
GitHub Actions deine Playwright-Tests gegen die Preview-URL ausführt
Vercel das Deployment nur bei bestandenen Tests nach Production promotet
Deine Freitagnachmittage wieder entspannt werden

Wir nutzen Vercels Deployment Checks-Feature, um ein Staging-Gate zu erstellen – einen Checkpoint, der passiert werden muss, bevor Code deine Nutzer erreicht.

Voraussetzungen

Bevor wir loslegen, stelle sicher, dass du Folgendes hast:

Ein Vercel-Projekt, das mit GitHub verbunden ist
Eine Playwright-Test-Suite (auch ein einfacher Smoke-Test reicht)
Zugang zu den Vercel-Projekteinstellungen
Einen Kaffee (optional, aber empfohlen)

Falls du noch auf der Suche bist, wie man Playwright-Tests generell in seinem Projekt einrichtet, findest du eine Anleitung im letzten Blogbeitrag: Playwright Tests ausführen.

Die Architektur

So funktioniert es unter der Haube:

Vercel Deployment Checks Ablauf

Der Kerngedanke: Vercel sendet ein repository_dispatch-Event an GitHub, wenn der Build fertig ist, aber bevor er nach Production promotet wird. Deine GitHub Action führt Tests gegen die Preview-URL aus, meldet das Ergebnis zurück, und Vercel promotet nur, wenn alle Checks bestanden sind.

Schritt 1: Auto-Assign in Vercel aktivieren

Gehe zu Project Settings → Environments → Production → Branch Tracking und stelle sicher, dass “Auto-assign Custom Production Domains” aktiviert ist. Damit kann Vercel Deployments automatisch promoten, sobald alle Checks bestanden sind.

Schritt 2: GitHub Actions Workflow erstellen

Erstelle eine neue Datei unter .github/workflows/deployment-checks.yml:

name: Deployment Checks

on:
  repository_dispatch:
    types:
      - 'vercel.deployment.ready'

jobs:
  e2e-tests:
    # Nur für Production-Deployments ausführen
    if: github.event.client_payload.environment == 'production'
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      # Diese Action meldet den Status an Vercel zurück
      - name: Report Check Status to Vercel
        uses: vercel/repository-dispatch/actions/status@v1
        with:
          name: 'Vercel - my-project: e2e-tests'

      # Vercels Checkout-Action verwenden (nutzt den korrekten Commit-SHA)
      - name: Checkout
        uses: vercel/repository-dispatch/actions/checkout@v1

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install Dependencies
        run: npm ci

      - name: Install Playwright Browsers
        run: npx playwright install chromium --only-shell

      - name: Run Playwright Tests
        run: npx playwright test
        env:
          BASE_URL: ${{ github.event.client_payload.url }}

      - name: Upload Test Report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

Schauen wir uns die wichtigsten Teile dieses Workflows an.

Der Trigger: `repository_dispatch`

on:
  repository_dispatch:
    types:
      - 'vercel.deployment.ready'

Vercel sendet verschiedene Event-Typen an GitHub:

vercel.deployment.ready – Build fertig, noch nicht promotet (diesen verwenden)
vercel.deployment.success – Build fertig und bereits promotet (zu spät!)
vercel.deployment.promoted – Nach manueller oder automatischer Promotion
vercel.deployment.error – Build fehlgeschlagen
vercel.deployment.canceled – Build abgebrochen

Für Deployment Checks musst du vercel.deployment.ready verwenden. Bei vercel.deployment.success laufen deine Tests erst, wenn das Deployment bereits live ist.

Die Status Action

- uses: vercel/repository-dispatch/actions/status@v1
  with:
    name: 'Vercel - my-project: e2e-tests'

Wichtig: Dieser Schritt muss der erste Schritt in deinem Job sein. Er meldet sofort “pending”, wenn der Job startet, und automatisch “success” oder “failure”, wenn der Job endet. Außerdem macht dieser Schritt den Check in Vercels “Add Checks”-Einstellungen sichtbar, nachdem der Workflow einmal gelaufen ist.

Damit Vercel ihn auch wirklich findet, muss der name-Parameter dem vorgegebenen Format entsprechen: Vercel - <PROJECT_NAME>: <CHECK_NAME>.

Am einfachsten nutzt du das von Vercel bereitgestellte Template unter Project Settings → Build and Deployment → Deployment Checks → Add Checks

Add Checks in Vercel

Die Checkout Action

- uses: vercel/repository-dispatch/actions/checkout@v1

Warum nicht den Github Standard actions/checkout@v5 zum Auschecken des Codes nutzen? Bei einem repository_dispatch-Event wird GITHUB_SHA auf den neuesten Commit des Default-Branches gesetzt – nicht auf den Commit, der das Vercel-Deployment ausgelöst hat. Falls jemand einen weiteren Commit pusht, während dein Deployment baut, würdest du den falschen Code testen.

Vercels Checkout-Action extrahiert den korrekten SHA aus dem Event-Payload und checkt genau diesen Commit aus.

Zugriff auf die Preview-URL

env:
  BASE_URL: ${{ github.event.client_payload.url }}

Vercel liefert die Preview-URL im Event-Payload mit. Wir konfigurieren Playwright in Schritt 3 so, dass es diese URL verwendet.

Schritt 3: Playwright konfigurieren

Stelle sicher, dass deine Playwright-Konfiguration die BASE_URL-Umgebungsvariable verwendet:

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: process.env.CI ? 'github' : 'html',
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  projects: [
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
      },
    },
  ],
});

Schritt 4: Deployment Protection handhaben (Optional)

Falls du Deployment Protection aktiviert hast (Passwortschutz, Vercel Authentication etc.), werden deine Tests fehlschlagen, weil sie nicht auf die Preview-URL zugreifen können. Überspringe diesen Schritt, wenn du Deployment Protection nicht nutzt.

Um den Schutz für automatisierte Tests zu umgehen:

Gehe zu Project Settings → Deployment Protection → Protection Bypass for Automation
Aktiviere es und kopiere das Secret
Füge es als VERCEL_AUTOMATION_BYPASS_SECRET zu deinen GitHub Repository Secrets hinzu
Aktualisiere deinen Workflow, um das Secret zu übergeben:

- name: Run Playwright Tests
  run: npx playwright test
  env:
    BASE_URL: ${{ github.event.client_payload.url }}
    VERCEL_AUTOMATION_BYPASS_SECRET: ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}

Aktualisiere deine Playwright-Konfiguration, um den Bypass-Header zu senden:

// playwright.config.ts – zum "use"-Abschnitt hinzufügen
extraHTTPHeaders: process.env.VERCEL_AUTOMATION_BYPASS_SECRET
  ? { 'x-vercel-protection-bypass': process.env.VERCEL_AUTOMATION_BYPASS_SECRET }
  : undefined,

Schritt 5: Den Check in Vercel registrieren

Jetzt, wo der Workflow existiert, müssen wir Vercel mitteilen, dass es darauf warten soll.

Löse ein Deployment aus, indem du in deinen Production Branch pushst
Warte, bis die GitHub Action einmal gelaufen ist (das registriert den Check-Namen bei GitHub)
Gehe zu Project Settings → Build and Deployment → Deployment Checks → Add Checks
Du solltest jetzt deinen Check-Namen sehen: Vercel - my-project: e2e-tests
Aktiviere ihn

Schritt 6: Das Setup testen

Pushe eine Änderung in deinen Production Branch und beobachte die Magie:

Vercel baut deine App
Das Deployment zeigt “Production (Staged)”
Die GitHub Action wird ausgelöst und führt Tests aus
Bei bestandenen Tests: Deployment wird nach Production promotet
Bei fehlgeschlagenen Tests: Deployment bleibt staged

Du kannst auch Force Promote auf der Deployment-Detailseite nutzen, falls du Checks in einem Notfall umgehen musst.

Fazit

Deployment Checks sind ein mächtiges Feature, das Production-Incidents verhindern kann. Das Setup dauert etwa 15 Minuten, und einmal eingerichtet, funktioniert es zuverlässig.

Die wichtigsten Punkte:

Verwende vercel.deployment.ready, um Tests vor der Promotion auszulösen
Nutze Vercels Checkout- und Status-Actions für korrektes SHA-Handling
Achte auf exakte Übereinstimmung der Check-Namen zwischen Workflow und Vercel-Einstellungen

Genieße ab jetzt deine Freitagnachmittage – in dem Wissen, dass kaputter Code nicht ohne bestandene Tests in Production landet.

Referenzen

War das hilfreich? Wir entwickeln kiteto, ein KI-gestütztes Tool, das natürlichsprachliche Beschreibungen in echten Playwright-Code umwandelt. Einfach Test-Code generieren lassen und in Vercel Deployment Checks integrieren.

Jetzt Early Access starten

FAQ

F: Warum nicht einfach Tests bei jedem Push mit einer normalen GitHub Action ausführen?

Reguläre CI-Tests laufen gegen deinen lokalen Build oder eine separate Testumgebung. Deployment Checks laufen gegen das tatsächliche Vercel-Preview-Deployment — exakt derselbe Build, der nach Production gehen wird. Das fängt umgebungsspezifische Probleme ab, die lokale Tests möglicherweise übersehen.

F: Funktionieren Deployment Checks auch mit Preview-Deployments oder nur mit Production?

Sie funktionieren mit beidem. Du kannst Checks für jede Umgebung konfigurieren. Unser Workflow nutzt if: github.event.client_payload.environment == 'production', um es auf Production zu beschränken, aber du kannst diese Bedingung entfernen oder anpassen.

F: Kann ich mehrere Deployment Checks haben?

Ja. Du kannst mehrere Checks in Vercel registrieren, und alle müssen bestanden werden, bevor promotet wird. Verwende einfach verschiedene name-Werte in separaten Jobs oder Workflows.

F: Was passiert, wenn GitHub Actions nicht erreichbar ist?

Das Deployment bleibt im “staged”-Status, bis der Check zurückmeldet. Du kannst bei Bedarf manuell über Force Promote im Vercel-Dashboard promoten.