Next.js CI/CD on Azure DevOps with a self-hosted agent

The problem this solves

Many organizations in Pakistan and the GCC host applications on servers inside their own data center or a private cloud. Those servers are deliberately unreachable from the internet, which rules out cloud-hosted build agents pushing deployments to them. The usual fallback is manual deployment by copying files, which is slow, inconsistent and causes downtime.

Architecture

The agent only makes outbound HTTPS connections to Azure DevOps. No inbound firewall rules are needed.

Step 1: Standalone build

In next.config.ts, set output: "standalone". The build produces .next/standalone with a server.js and only the required dependencies. Copy public and .next/static alongside it, because they are not included automatically.

Step 2: The CI stage

A typical CI stage:

1. Use a pinned Node.js version.
2. Install dependencies with npm ci and a cache.
3. Run lint, type-check and unit tests.
4. Run next build.
5. Assemble the standalone folder with public and .next/static.
6. Publish it as a pipeline artifact named with the build number.

Pull requests run the same steps without publishing, so broken code never reaches the main branch.

Step 3: The deployment stage

Run the deployment job in the self-hosted agent pool and target an Azure DevOps environment so approvals and history are recorded. The job:

1. Downloads the artifact.
2. Extracts it into /srv/app/releases/<build-number>.
3. Writes environment configuration from a secure variable group.
4. Starts the new release on a spare port with the process manager.
5. Calls a health route, for example one that renders a real page, until it returns success or times out.
6. Switches the reverse proxy upstream or the current symlink and reloads gracefully.
7. Stops the old process after connections drain.
8. Deletes releases older than the last few.

Rollback

Because previous releases remain on disk, rollback is a switch back to the prior directory and a reload, measured in seconds. Expose it as a separate manual pipeline so on-call engineers do not need server access.

Secrets and configuration

• Store secrets in Azure DevOps variable groups linked to Azure Key Vault where possible.
• Mark secret variables so they are masked in logs.
• Give the agent's service account only the permissions it needs on target servers.

Common pitfalls

• Forgetting static assets: without .next/static, pages render but styles and scripts return 404.
• Health checks that only test the process: a running process can still fail to render pages; check a real route.
• Shared caches between releases: keep each release self-contained.
• Agent as a single point of failure: register at least two agents in the pool for production.

Results to measure

Track deployment duration, downtime per release, change failure rate and time to restore. These are standard DevOps delivery metrics and make the value of the pipeline visible.

We applied this pattern in the zero-downtime Next.js deployment case study. Our cloud and DevOps service sets up the same approach for client applications.