CI/CD for Next.js — GitHub Actions from tests to production (2026)

TL;DR

For a Next.js project on Node 22, Next 15.5.18, and build via scripts/build.cjs, we recommend one GitHub Actions pipeline: every PR = quality (lint + build), merge to main = deploy to Vercel. This repository does not yet have a .github/workflows directory — this article describes the target state to add now instead of relying on manual "works on my machine." Keep secrets (VERCEL_TOKEN, DATABASE_URL, API keys) only in GitHub Secrets.

Who this is for

• Teams of 1–5 developers on Next.js + Vercel
• Projects with Prisma (postinstall: prisma generate, migrate in build script)
• Companies wanting auditable deployment history and preview URL on every PR
• Monorepos or multiple apps in one repo (paths: section)

Keywords (SEO)

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

Starting point: honest repo state

In many production projects the pipeline "exists in the team's heads," not in the repo. Here:

• package.json requires Node 22.x (engines.node),
• Next.js 15.5.18, scripts: build → node scripts/build.cjs, lint → eslint, postinstall → prisma generate,
• No .github/workflows/*.yml files — CI must be added deliberately.

That is not a flaw — it is a normal stage. The flaw appears when laptop deploy skips the same steps as PR. The goal is one artifact: commit passed lint and build in Actions → same commit lands on Vercel.

What scripts/build.cjs does (and why CI must use it)

Plain next build in CI often is not enough when:

1. Prisma — script loads .env / .env.local (not in repo in Actions), runs prisma generate, and with DATABASE_URL also prisma migrate deploy, then next build.
2. Locally the developer has a database; CI build may pass without migrations if you do not set the secret — but generate is still needed after npm ci (also supported by postinstall).

Pipeline conclusion: build job must call npm run build (not raw next build), with environment variables in GitHub Secrets / Environments. For PRs without a database you may use shadow DB URL or skip migrations — per team policy; production must have full secrets in production environment.

DATABASE_URL strategies in CI (Prisma)

In a DevStudio-style build, without DATABASE_URL the script logs a message and skips prisma migrate deploy, but still runs prisma generate — aligned with postinstall and prevents "Client not generated" errors.

Recommended split: PR vs main

Rule: merge nothing to main that did not pass the same build as production.

Full workflow example (.github/workflows/ci.yml)

The file below is ready to copy and adapt. Uses Node 22, npm cache, lint, typecheck, and build matching this 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:
          # Required for full build — set in GitHub Secrets / Environment
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          NEXT_PUBLIC_SITE_URL: ${{ vars.NEXT_PUBLIC_SITE_URL || 'https://example.com' }}
          # Add remaining NEXT_PUBLIC_* and API keys as in Vercel Production

  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 }}

Simpler alternative: enable Vercel Git Integration — Vercel builds preview on PR, Actions quality job stays the merge gate. Many teams use both: Actions = lint/tsc/build, Vercel = hosting + URL.

Secrets and variables — where to put what

In repo settings: Settings → Secrets and variables → Actions. For production use Environment production with optional Required reviewers (1–2 people).

Branch protection on main

Minimum worth enabling from day one:

• Require pull request before merging
• Require status check quality (job name from workflow)
• Require branch to be up to date
• Do not allow bypassing (even admin, if the team has discipline)
• Optional: require signed commits

Then nobody merges a build that did not pass npm run lint and npm run build on Node 22.

Preview URL on every PR

Vercel Git Integration (recommended to start):

• automatic URL like project-git-branch-xyz.vercel.app,
• bot comment on PR with link,
• QA and client verify before merge.

GitHub Actions + vercel-action (as in yaml above):

• full control, same token as prod deploy,
• useful when you want one pipeline in YAML instead of Vercel panel.

In both cases ensure NEXT_PUBLIC_* on preview is not empty — otherwise PR build "passes" but preview UI differs from production.

Env sync: in Vercel copy variable set from Production to Preview (or vercel env pull). In GitHub add the same NEXT_PUBLIC_* as Variables (visible in logs, not secret) — then quality builds the same code as preview. Keep secrets (DATABASE_URL, STRIPE_SECRET_KEY) only in Secrets.

Monorepo: do not build everything on every PR

When one repo has e.g. apps/web and packages/ui, add separate workflows with path filters:

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

You can use paths-ignore for docs (docs/**, content/blog/**) to skip an 8-minute build for a typo in an article — unless the blog is part of the same Next.js package (in a marketing monolith you often still build everything).

Rollback on Vercel in ~60 seconds

Prod deploy on Vercel is a new deployment; previous builds remain.

Emergency procedure:

1. Vercel Dashboard → Deployments
2. Find last working deployment (previous commit)
3. ⋯ → Promote to Production

Often under one minute. Pipeline does not replace rollback — it ensures the promoted build was once green on PR. Avoid laptop deploy "quick fix" beside CI — then panel rollback may restore a different version than you think.

On self-hosted (Docker): image tag = commit SHA; rollback = previous tag in orchestrator. Same rule: one artifact from CI.

Security in CI/CD

• permissions: contents: read by default (as in example) — minimal GITHUB_TOKEN rights
• Separate environment production with approval
• Dependabot / npm audit in a weekly workflow
• Never echo secrets or full .env in logs — Actions masks secrets.*, but custom scripts must stay clean
• Rotate VERCEL_TOKEN and API keys quarterly or when a member leaves

Most common mistakes (and fixes)

FAQ

Does GitHub Actions replace Vercel?

No. Actions = quality control and optional CLI deploy; Vercel = hosting, CDN, preview, rollback. Most often: Actions for lint/build, Vercel for running the app.

Must I run prisma migrate deploy in CI?

In this project scripts/build.cjs does it when DATABASE_URL is set. On PR you may use a test database or skip migrations — but ensure Prisma schema is consistent (generate is still required). On main/prod DATABASE_URL must be complete.

What if there are no tests?

Start with lint + tsc + build. Add tests when you have critical paths (payments, contract APIs). Pipeline still delivers ~80% of value.

Monorepo with three apps?

Three workflows with paths: or one workflow with strategy.matrix — not one global build without filters.

How to sync Node version with Vercel?

In Vercel Project Settings set Node.js 22.x, matching engines in package.json.

Troubleshooting: red build in Actions

• prisma generate failed — check Node (22), whether npm ci finished, schema in repo valid.
• migrate deploy failed — DB URL unreachable from GitHub (IP firewall), bad migration, conflict with manual DB changes.
• next build OOM — larger runner (rare) or drop heavy analysis; check heavy library imports.
• Lint fail on PR — run npm run lint locally on Node 22; do not merge with --no-verify.
• Preview works, prod does not — compare Vercel Production vs Preview Environment Variables; often one missing NEXT_PUBLIC_*.

Action logs show the exact step — treat them as the only audit before touching production.

One-day rollout plan

1. Add .github/workflows/ci.yml (fragment above).
2. Configure Secrets + Variables (DATABASE_URL, Vercel, NEXT_PUBLIC_*).
3. Enable branch protection on main.
4. Connect repo to Vercel (if not yet).
5. Open a test PR — verify green quality + preview URL.
6. Merge — verify production deployment and save rollback procedure in team README.

Summary

CI/CD for Next.js 15 on Node 22 is not magic — it is a repeatable set: npm ci → lint → typecheck → npm run build (Prisma + Next) on every PR, deploy to Vercel after merge, secrets outside repo, preview for acceptance, rollback via Promote in the panel. No workflow in the repository is a signal to add it now — before a manual deploy costs more than one day of production repair.

Want a pipeline for your project?

• Contact us — we review package.json, Vercel, and Prisma for your case
• Web applications — Next.js, hosting, and DevOps in one package