CI/CD

Pull requests run the verification and publish a Devtools graph, so a reviewer sees the result before merging. Only a push to main continues to the image and deploy jobs. The scheduled job is independent: it tells you what the next framework upgrade would change.

Nothing in Nest ties you to a CI product: the pipeline is npm ci, npm run lint, npm run test:cov, npm run build. Choose the tool that already hosts your code.

The rest of this page uses GitHub Actions. The shape (install, lint, test, build, package, deploy) carries over to the other tools unchanged; only the YAML differs.

A project generated by nest new already has the scripts a pipeline needs. The official documentation describes npm run lint (oxlint) and npm run format (Prettier) as the headless commands for continuous integration, and the generated package.json of the ESM template also defines the test and build scripts:

Source: NestJS: First steps (linting and formatting); the test and build scripts are the ones the Nest 12 CLI generates (CLI overview).

The CommonJS template uses Jest instead of Vitest, with the same script names, so the workflow below works for both. Two details matter in CI. The linter exits with a non-zero status when it finds an error, which fails the step. And nest build runs the TypeScript compiler (or the builder configured in nest-cli.json), so a type error fails the build even when the tests passed.

The workflows below are files under .github/workflows/ in the repository. The first job runs on every pull request and on every push to main. It checks out the code, installs Node.js with the npm cache enabled, installs dependencies from the lockfile, and runs lint, unit tests with coverage, end-to-end tests and the build, once per Node.js version in the matrix.

Source: actions/checkout, actions/setup-node and GitHub: Running variations of jobs in a workflow.

The pieces, in the order they matter:

If you target the CommonJS template, nothing in the workflow changes; only the test runner does (Jest instead of Vitest). The migration guide notes that Jest can load the ESM-only v12 packages only on Node.js 24.9 or newer, so a Jest project should run on Node.js 24 or move to Vitest.

A workflow needs three kinds of values: the token GitHub gives every run, secrets you create (SSH keys, API keys), and non-secret settings.

The application reads its own configuration from the environment at start-up through ConfigService, and the same rules apply there: no secret is committed to the repository, to the workflow file or to the image. CI injects test-only values; production values live in the platform that runs the container. See Configuration for validating the environment at start so a missing value fails fast. Environments (production, staging) hold secrets and approval rules that apply only to jobs that target them, which is how the deploy job below is protected.

Source: GitHub: Using secrets in GitHub Actions, GitHub: OpenID Connect and GitHub: Secure use reference.

The Nest documentation’s deployment page shows a single-stage Dockerfile; for CI it is worth using two stages so the final image contains only the compiled output and the production dependencies. The build stage installs everything, runs nest build and then removes the development dependencies with npm prune --omit=dev; the final stage copies the result and runs as the unprivileged node user.

Source: NestJS: Deployment - Dockerizing your application. For layer caching, multi-stage builds and image hardening, see Build Cache and Multi-stage Builds and Image Best Practices and Security.

The copied package.json, node_modules and dist are all the application needs to start with node dist/main. For a freshly generated project the production dependency tree is 21 MB, against 161 MB with the development dependencies. The COPY lines have no --chown, so the files stay owned by root and the node user can read but not modify them; Deployment explains the choice.

The image job builds that Dockerfile and pushes it to the GitHub container registry. It runs only after verify succeeded and only for pushes to main:

Source: docker/build-push-action, docker/metadata-action and NestJS: Deployment. The inputs are explained in Docker CI/CD with GitHub Actions.

metadata-action computes the tags (sha- plus the short commit, and latest) and the OCI labels; build-push-action builds, pushes and reports the image digest, which the job exposes as an output. The gha cache keeps layers between runs. The digest matters for the next job: a tag such as latest can be moved, a digest cannot, so the deploy job rolls out exactly the image that this run built and that passed verification.

A deploy job should be separate from the build, depend on it with needs, and target an environment. In the repository settings you create the production environment, add required reviewers and (if wanted) restrict it to the main branch; the job then pauses until a reviewer approves, and its secrets are only exposed after approval.

Nest Devtools (@nestjs/devtools-integration) can publish a snapshot of your application’s dependency graph on every build. The registry keeps a history of the graph and, for a pull request whose target branch already has a snapshot, builds a report of what changed structurally: a provider whose scope changed, a guard that disappeared from a route, a module that became global. The documentation lists the CI/CD integration under the Enterprise plan of the Devtools service; the graph explorer itself works locally (see Debugging & Devtools).

The integration has two parts: a switch in main.ts that publishes instead of listening when CI asks for it, and a workflow that runs the application in that mode. The application options are snapshot: true, which makes Nest collect the graph metadata while it bootstraps, and preview: true, which bootstraps the application without running the constructors and lifecycle hooks of controllers, enhancers and providers, so the publish job needs no database. This is the bootstrap with the publish options read from the environment of GitHub Actions:

Source: NestJS Devtools: CI/CD integration. In your application this body is the bootstrap() function of main.ts; it was extracted into a function that takes the module and the environment only so a test can call it.

The workflow checks out the code, installs dependencies and starts the application with PUBLISH_GRAPH=true. The API key is a secret created on the Devtools settings page, and TARGET_SHA is the base commit of the pull request, which is what the new graph is compared against:

Source: NestJS Devtools: GitHub Actions integration. The official example uses actions/checkout@v4, actions/setup-node@v4 and Node.js 22; the workflow above uses the current majors and Node.js 24, and stores the key in a secret instead of the placeholder the official example shows.

The fields of the publish options are apiKey, owner (organisation or user), repository, sha (the commit being built), target (the commit to compare with, or targetBranch when your CI does not provide it), trigger (push or pull) and branch. The documentation recommends publishing on pushes only for branches that represent a deployment environment (main, staging, production) and always, or at least when the target is such a branch, for pull requests: that keeps a snapshot for every deployable state, so each pull request has something to be compared with. For GitLab and other CI systems the same fields come from their built-in variables; the official page has a GitLab pipeline and notes that Bitbucket Pipelines and CircleCI work the same way.

You can test the publisher without a Devtools account: start the application module with PUBLISH_GRAPH=true against a local HTTP server standing in for the registry (the package reads its target address from a DEVTOOLS_API_URL environment variable when set). Such a test shows that a provider whose constructor throws is never constructed in preview mode, that the request is a POST to /organizations/<owner>/projects/<repository>/builds with an Authorization: ApiKey …​ header and a compressed graph containing the route controller, and that a missing owner throws GraphPublisher: "owner" parameter is required. It also shows a behaviour to plan for: when the registry answers 401, the publisher prints an error and the process still exits normally, so a wrong API key does not turn the step red. If a failed publish must block the pipeline, check the output or the Devtools GitHub application’s status on the pull request.

nest upgrade applies the mechanical parts of a major-version upgrade to an existing project: it bumps every recognised @nestjs/* package to its v12 major, raises TypeScript to v6, migrates nest-cli.json away from the deprecated webpack options, renames the GraphQL playground option to graphiql, switches subscriptions to graphql-ws, and prints notes about behaviour changes it cannot migrate. With --dry-run (alias -d) it reports what it would change and writes nothing, which makes it safe to run in CI. --skip-install skips the package installation and --no-observe skips the prompt that offers to set up @nestjs/observe; --tag next previews against an npm dist-tag instead of the stable ranges.

A scheduled workflow can run the preview once a week and put the report in the run summary, so the team learns about the cost of an upgrade before anyone starts it:

Source: NestJS: CLI usage - nest upgrade and NestJS: Migration guide.

Running the same command locally on a project whose @nestjs/common, @nestjs/core, @nestjs/platform-express and @nestjs/testing were set back to ^11.0.0 and TypeScript to ^5.7.0 printed:

Three facts about the command shape how to use it in CI. The command exits with status 0 in a dry run even when it reports changes, so the job is informational unless you parse the output. On a project that is already on v12, it reports the v12 package ranges and a note that the migrations are idempotent, so the weekly job is only informative on a project that has not yet upgraded, or with --tag pointing at a prerelease. And the command only touches the local @nestjs/cli: a globally installed CLI has to be updated first with npm i -g @nestjs/cli@latest, which is not an issue in CI where the CLI comes from node_modules. The upgrade itself, as opposed to the preview, belongs on a branch: run nest upgrade, review the diff and the printed report, and let the verify workflow above judge the result.