A Next.js CI/CD Pipeline: Stages, Checks and Deploy Gates

Order stages by speed and by how cheaply they fail:

1. Install: a clean install from the lockfile, with the dependency cache restored.
2. Lint and format check: seconds to run, catches the most trivial problems.
3. Type check: run the TypeScript compiler without emitting output.
4. Unit and component tests: run in parallel with the type check if your runner has capacity.
5. Build: the production build. Failures here often reveal server and client boundary mistakes that dev mode hides.
6. Preview deploy: publish the build to a unique preview URL for the pull request.
7. End-to-end smoke test: run a few critical flows against the preview URL, such as sign-in and the main page render.
8. Promote: on merge to the main branch, deploy to production, then run a post-deploy check.

Steps 2 to 4 can run at the same time. Don't start preview deployments until the cheap checks pass, or you'll waste build minutes on commits that were already broken.

Slow pipelines get bypassed, so treat speed as a feature. The main levers:

• Cache the package manager's download cache, keyed on the lockfile hash.
• Cache the Next.js build cache between runs, so unchanged pages don't rebuild.
• Run independent jobs in parallel and fail fast on the first error.
• Cancel superseded runs on the same branch when a new commit arrives.
• Quarantine flaky tests: move a test that fails intermittently out of the blocking path, file a ticket and fix it within days, since one flaky test teaches everyone to re-run instead of investigate.
• Split slow end-to-end tests into a smaller pull request suite and a fuller nightly one.

Say your pipeline takes 14 minutes and engineers batch changes to avoid waiting. Cutting it to 6 minutes changes how often people integrate, which matters more than the minutes saved. DORA's 2024 report puts its highest-performing cluster on demand for deploy frequency, meaning no more than 1 day between deploys¹.

Next.js treats variables prefixed for the browser differently from server-only ones, and that difference is a common leak. Follow these rules:

• Anything in a browser-exposed variable is public. Never put a secret key there.
• Store secrets in the CI platform's encrypted secret store, scoped to the environments that need them.
• Use separate values for preview and production, and never let a preview build talk to the production database.
• Fail the build if a required variable is missing, using a small validation module at startup.
• Give forks and untrusted pull requests no access to secrets.

Also decide which variables are read at build time and which at run time, since a value baked into a build can't change without a rebuild.

Set branch protection so the main branch requires passing checks and at least one review, and disallow direct pushes. For production, choose an approach that matches your risk. A small team with good tests can deploy every merge automatically. A team with regulated changes may add a manual approval on the production job.

Whatever you pick, add a post-deploy smoke check and an automatic alert on error rate. Keep the previous build available for a one-step rollback, and rehearse it once. Change failure rate is the number to watch: in DORA's 2024 clusters, the highest-performing group reported a change failure rate of about 5%². Pair the pipeline with a written release checklist covering what to verify around each deploy.

Use whichever platform already hosts your code. The stages, caching and secret handling above are identical. Choose GitHub Actions if you're on GitHub and want its marketplace of reusable steps, and GitLab CI if you're on GitLab and want pipelines, environments and the container registry in one place. Don't migrate your source host just for CI. If you're weighing the two anyway, the CI platform comparison goes through the tradeoffs.