CI/CD für Next.js, GitHub Actions von Tests bis Produktion (2026)

Kurzfassung

Für ein Next.js-Projekt auf Node 22, Next 15.5.18 und Build via scripts/build.cjs empfehlen wir eine GitHub-Actions-Pipeline: jeder PR = Qualität (lint + build), Merge auf main = Deploy auf Vercel. In diesem Repository gibt es noch keinen Ordner .github/workflows, der Artikel beschreibt den Zielzustand, den Sie gleich anlegen sollten, statt auf manuelles „bei mir geht’s“ zu vertrauen. Secrets (VERCEL_TOKEN, DATABASE_URL, API-Keys) nur in GitHub Secrets.

Für wen ist das

• Teams mit 1–5 Entwicklern auf Next.js + Vercel
• Projekte mit Prisma (postinstall: prisma generate, Migrate im Build-Skript)
• Firmen, die auditierbare Deploy-Historie und Preview-URL pro PR wollen
• Monorepos oder mehrere Apps in einem Repo (Abschnitt paths:)

Keyword (SEO)

ci cd nextjs github actions, pipeline nextjs 2026, vercel deployment automatisieren, github actions build nextjs, branch protection main, vercel rollback

Ausgangspunkt: ehrlicher Repo-Status

In vielen Produktionsprojekten „existiert“ die Pipeline im Kopf des Teams, nicht im Repo. Hier:

• package.json verlangt Node 22.x (engines.node),
• Next.js 15.5.18, Skripte: build → node scripts/build.cjs, lint → eslint, postinstall → prisma generate,
• Keine Dateien .github/workflows/*.yml, CI muss bewusst ergänzt werden.

Das ist kein Mangel, normaler Reifegrad. Problematisch wird es, wenn Deploy vom Laptop dieselben Schritte wie der PR umgeht. Ziel: ein Artefakt, Commit bestand lint und build in Actions → derselbe Commit landet auf Vercel.

Was scripts/build.cjs macht (und warum CI es braucht)

Rohes next build in CI reicht oft nicht, wenn:

1. Prisma, Skript lädt .env / .env.local (in Actions nicht im Repo), führt prisma generate aus und bei DATABASE_URL auch prisma migrate deploy, am Ende next build.
2. Lokal hat der Entwickler eine DB; in CI kann der Build ohne Migration durchlaufen, wenn kein Secret gesetzt ist, aber generate ist nach npm ci nötig (auch via postinstall).

Pipeline-Folgerung: Build-Job muss npm run build (nicht rohes next build) mit passenden Env-Variablen in GitHub Secrets / Environments aufrufen. Für PR ohne DB reicht oft DATABASE_URL auf Shadow-DB oder Migration weglassen, je nach Team-Policy; Prod braucht volle Secrets im Environment production.

DATABASE_URL-Strategien in CI (Prisma)

Im DevStudio-Style-Build ohne DATABASE_URL schreibt das Skript eine Meldung und überspringt prisma migrate deploy, führt aber prisma generate aus, konsistent mit postinstall, verhindert „Client not generated“.

Empfohlene Aufteilung: PR vs. main

Regel: nichts in main mergen, was nicht denselben build wie Produktion bestanden hat.

Vollständiges Workflow-Beispiel (.github/workflows/ci.yml)

Die folgende Datei ist kopierfertig anpassbar. Nutzt Node 22, npm-Cache, lint, typecheck und build wie in diesem Repo.

name: CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  quality:
    runs-on: ubuntu-latest
    timeout-minutes: 25
    steps:
      - name: Checkout
        uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: ESLint
        run: npm run lint

      - name: TypeScript (no emit)
        run: npx tsc --noEmit

      - name: Build (Prisma + Next via scripts/build.cjs)
        run: npm run build
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          NEXT_PUBLIC_SITE_URL: ${{ vars.NEXT_PUBLIC_SITE_URL || 'https://example.com' }}

  deploy-preview:
    if: github.event_name == 'pull_request'
    needs: quality
    runs-on: ubuntu-latest
    environment: preview
    steps:
      - uses: actions/checkout@v4
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          scope: ${{ secrets.VERCEL_ORG_ID }}

  deploy-production:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: quality
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'
          github-token: ${{ secrets.GITHUB_TOKEN }}
          scope: ${{ secrets.VERCEL_ORG_ID }}

Einfachere Alternative: Vercel Git Integration aktivieren, Vercel baut Preview pro PR, Job quality in Actions bleibt Merge-Gate. Viele Teams kombinieren: Actions = lint/tsc/build, Vercel = Hosting + URL.

Secrets und Variablen, wo was liegt

Im Repo: Settings → Secrets and variables → Actions. Für Produktion Environment production mit optional Required reviewers (1–2 Personen).

Branch Protection auf main

Minimum ab Tag eins:

• Require pull request before merging
• Require status check quality (Job-Name aus Workflow)
• Require branch to be up to date
• Do not allow bypassing (auch Admin, wenn das Team diszipliniert ist)
• Optional: require signed commits

So landet kein Build in Prod, der npm run lint und npm run build auf Node 22 nicht bestanden hat.

Preview-URL pro PR

Vercel Git Integration (empfohlen zum Start):

• automatische URL wie projekt-git-branch-xyz.vercel.app,
• Bot-Kommentar im PR mit Link,
• QA und Kunde prüfen vor Merge.

GitHub Actions + vercel-action (wie im YAML oben):

• volle Kontrolle, derselbe Token wie Prod-Deploy,
• sinnvoll bei einem Pipeline-YAML statt Vercel-Panel.

In beiden Fällen: NEXT_PUBLIC_* auf Preview nicht leer, sonst grüner PR-Build, aber anderes UI auf Preview als Prod.

Env-Sync: in Vercel Variablen von Production nach Preview kopieren (oder Vercel CLI vercel env pull). In GitHub dieselben NEXT_PUBLIC_* als Variables, dann baut Job quality denselben Code wie Preview. Secrets (DATABASE_URL, STRIPE_SECRET_KEY) nur in Secrets.

Monorepo: nicht alles bei jedem PR bauen

Bei apps/web und packages/ui im selben Repo separate Workflows mit Pfadfilter:

on:
  pull_request:
    paths:
      - 'apps/web/**'
      - 'packages/ui/**'
      - 'package-lock.json'

Oder paths-ignore für Doku (docs/**, content/blog/**), um keinen 8-Minuten-Build bei Blog-Tippfehler zu starten, sofern der Blog nicht Teil desselben Next.js-Pakets ist (bei monolithischer Marketing-Site oft trotzdem Full-Build).

Rollback auf Vercel in ~60 Sekunden

Prod-Deploy auf Vercel ist ein neues Deployment; alte Builds bleiben.

Notfallprozedur:

1. Vercel Dashboard → Deployments
2. Letztes funktionierendes Deployment finden (vorheriger Commit)
3. ⋯ → Promote to Production

Oft unter einer Minute. Pipeline ersetzt Rollback nicht, sie stellt sicher, dass der promotierte Build einmal grün im PR war. Deploy vom Laptop „schnell“ neben CI vermeiden, sonst kann Rollback im Panel eine andere Version wiederherstellen als erwartet.

Bei eigenem Server (Docker): Image-Tag = Commit-SHA; Rollback = vorheriger Tag im Orchestrator. Gleiche Regel: ein Artefakt aus CI.

Sicherheit in CI/CD

• permissions: contents: read standardmäßig, minimale GITHUB_TOKEN-Rechte
• separates Environment production mit Approval
• Dependabot / npm audit in wöchentlichem Workflow
• Secrets und volle .env nie in Logs echoen, Actions maskiert secrets.*, eigene Skripte müssen sauber sein
• Rotation von VERCEL_TOKEN und API-Keys quartalsweise oder nach Team-Austritt

Häufige Fehler (und Vermeidung)

FAQ

Ersetzen GitHub Actions Vercel?

Nein. Actions = Qualitätskontrolle und optional CLI-Deploy; Vercel = Hosting, CDN, Preview, Rollback. Meist: Actions für lint/build, Vercel für App-Ausführung.

prisma migrate deploy in CI?

In diesem Projekt macht das scripts/build.cjs, wenn DATABASE_URL gesetzt ist. Im PR Test-DB oder Migration weglassen, Schema muss trotzdem passen (generate nötig). Auf main/prod muss DATABASE_URL vollständig sein.

Was ohne Tests?

Mit lint + tsc + build starten. Tests hinzufügen bei kritischen Pfaden (Zahlung, Vertrags-API). Pipeline liefert schon ~80 % Wert.

Monorepo mit drei Apps?

Drei Workflows mit paths: oder ein Workflow mit strategy.matrix, kein globaler Build ohne Filter.

Node-Version mit Vercel synchronisieren?

In Vercel Project Settings Node.js 22.x, passend zu engines in package.json.

Troubleshooting: roter Build in Actions

• prisma generate failed, Node (22), ob npm ci fertig, Schema im Repo korrekt.
• migrate deploy failed, DB von GitHub aus unreachable (Firewall), falsche Migration, Konflikt mit manuellen DB-Änderungen.
• next build OOM, Runner upgraden (selten) oder schwere Imports prüfen.
• Lint fail im PR, lokal npm run lint auf Node 22; nicht mit --no-verify mergen.
• Preview OK, Prod nicht, Vercel Production vs. Preview Environment Variables vergleichen; oft fehlt ein NEXT_PUBLIC_*.

Actions-Logs sind der Audit vor Produktion, genau einen Schritt lesen, der rot ist.

Cache und parallele PRs

Mit concurrency: cancel-in-progress: true bricht ein neuer Push auf demselben Branch den laufenden CI-Lauf ab, spart Minuten bei schnellen Fix-Commits. Ergänzen Sie npm- und .next/cache-Caching in Actions, wenn Builds regelmäßig über sechs Minuten dauern. Bei Prisma-Projekten: prisma generate läuft ohnehin über postinstall, teure Schritte sind meist next build und Typecheck; dort lohnt sich stabile Node-22-Version und identische Lockfile-Disziplin (npm ci, nie npm install in CI).

Plan, Implementierung an einem Tag

1. .github/workflows/ci.yml hinzufügen (Fragment oben).
2. Secrets + Variables (DATABASE_URL, Vercel, NEXT_PUBLIC_*).
3. Branch Protection auf main.
4. Repo mit Vercel verbinden (falls noch nicht).
5. Test-PR, grüner quality + Preview-URL.
6. Mergen, Production-Deployment prüfen, Rollback-Prozedur ins Team-README.

Zusammenfassung

CI/CD für Next.js 15 auf Node 22 ist kein Hexenwerk, wiederholbar: npm ci → lint → typecheck → npm run build (Prisma + Next) pro PR, Deploy auf Vercel nach Merge, Secrets außerhalb des Repos, Preview zur Abnahme, Rollback via Promote im Panel. Fehlende Workflows im Repository sind das Signal, das jetzt zu ergänzen, bevor manueller Deploy mehr kostet als ein Tag Produktions-Reparatur.

Pipeline für Ihr Projekt?

• Kontakt aufnehmen, package.json, Vercel und Prisma für Ihren Fall prüfen
• Web-Apps, Next.js, Hosting und DevOps aus einer Hand