Skip to content
Nx Cloud CI is in private beta 10.6× faster average CI time with 79% less compute. Join the beta
Let an AI agent set it up for you

Help me set up CI for my Nx workspace with remote caching.

Before touching anything, verify the workspace state:

A. Is Nx installed?

- Check for `nx.json` and `nx` in `package.json` devDeps.

- Confirm `node_modules` exists. If not, install deps using the package manager that matches my lockfile (`pnpm install`, `npm install`, or `yarn`).

- If `nx.json` is missing entirely, ask me before running `npx nx@latest init`.

B. Is there an existing CI workflow?

- Yes, and it already calls `nx run` or `nx run-many`: likely already set up. Confirm with me before changing anything.

- Yes, but it calls raw tooling directly (`jest`, `tsc`, `eslint`, etc.): work with me to update it. Propose minimal edits swapping the raw calls for `nx run-many -t <task>` or `nx run <project>:<task>`. Show me the diff and wait for approval before writing.

- No: run `nx g @nx/workspace:ci-workflow --ci=<provider>`. Detect the provider from `git remote -v` (github.com -> `github`, gitlab.com -> `gitlab`, etc.). Ask me if it's ambiguous.

If `.nx/pipelines/ci.yaml` has `on` and `jobs`, the pipeline runs on Nx Cloud CI, so leave provider workflows alone. If `.nx/ci-config.yaml` exists, tell me it's deprecated and point me to /docs/kb/migrate-from-ci-config.

Then connect to Nx Cloud:

1. Run `npx nx-cloud onboard connect-workspace` and parse the JSON.

2. If the response includes an `actionRequired` payload (typically GitHub authorization), surface the message and any URLs to me and stop. Do not retry blindly.

3. Confirm `nxCloudId` is written to `nx.json`. If it is not, surface the JSON error to me instead of retrying.

Stage the generated or edited files but do not commit on my behalf. Stay on topic: getting remote cache running in CI. For deeper coverage link to https://nx.dev/docs/getting-started/setup-ci.md and to /docs/features/ci-features/remote-cache (/docs/features/ci-features/remote-cache).

Page: https://nx.dev/docs/getting-started/setup-ci.md

Help me set up CI for my Nx workspace with remote caching.

Before touching anything, verify the workspace state:

A. Is Nx installed?

- Check for `nx.json` and `nx` in `package.json` devDeps.

- Confirm `node_modules` exists. If not, install deps using the package manager that matches my lockfile (`pnpm install`, `npm install`, or `yarn`).

- If `nx.json` is missing entirely, ask me before running `npx nx@latest init`.

B. Is there an existing CI workflow?

- Yes, and it already calls `nx run` or `nx run-many`: likely already set up. Confirm with me before changing anything.

- Yes, but it calls raw tooling directly (`jest`, `tsc`, `eslint`, etc.): work with me to update it. Propose minimal edits swapping the raw calls for `nx run-many -t <task>` or `nx run <project>:<task>`. Show me the diff and wait for approval before writing.

- No: run `nx g @nx/workspace:ci-workflow --ci=<provider>`. Detect the provider from `git remote -v` (github.com -> `github`, gitlab.com -> `gitlab`, etc.). Ask me if it's ambiguous.

If `.nx/pipelines/ci.yaml` has `on` and `jobs`, the pipeline runs on Nx Cloud CI, so leave provider workflows alone. If `.nx/ci-config.yaml` exists, tell me it's deprecated and point me to /docs/kb/migrate-from-ci-config.

Then connect to Nx Cloud:

1. Run `npx nx-cloud onboard connect-workspace` and parse the JSON.

2. If the response includes an `actionRequired` payload (typically GitHub authorization), surface the message and any URLs to me and stop. Do not retry blindly.

3. Confirm `nxCloudId` is written to `nx.json`. If it is not, surface the JSON error to me instead of retrying.

Stage the generated or edited files but do not commit on my behalf. Stay on topic: getting remote cache running in CI. For deeper coverage link to https://nx.dev/docs/getting-started/setup-ci.md and to /docs/features/ci-features/remote-cache (/docs/features/ci-features/remote-cache).

Page: https://nx.dev/docs/getting-started/setup-ci.md

Connect your workspace to Nx Cloud for remote caching, run your pipeline on your CI provider or on Nx Cloud, then add workers to split tasks across machines. For a finished pipeline, jump to the complete example.

For existing repos, run the init command and follow the prompts:

Terminal window
npx nx@latest init

Or start fresh with a new repo:

Terminal window
npx create-nx-workspace@latest

With remote caching, a task that already ran with the same inputs, in CI or on a teammate's machine, is restored from the cache instead of running again. A pipeline with many cache hits finishes sooner and uses fewer machine-minutes, which reduces cost. Setup takes under 5 minutes and is free to start.

Nx

Connect your workspaceSetup takes less than 5 minutes

Remote caching needs no configuration file. For read-only and read-write CI tokens, see CI access tokens.

On Nx Cloud, Ultracache configures each task's inputs and outputs automatically from the files it reads and writes, so you don't declare them by hand.

Caching, affected, and distribution only apply to tasks that nx runs. nx test is fine, and so is npm test if it wraps nx test. Direct calls to jest, tsc, or eslint skip Nx.

Use nx affected to run tasks only for projects your change touches. Keep the pipeline on your CI provider, or run it on Nx Cloud CI, which is in private beta for GitHub repositories:

.github/workflows/ci.yml
# ... name and triggers
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
# ... set up Node.js
- run: npm ci
- uses: nrwl/nx-set-shas@v5
- run: npx nx affected -t lint test build

fetch-depth: 0 gives Nx the git history it needs to compare commits. On a pull request, Nx compares the branch with main (or defaultBase in nx.json). On a push to main, nrwl/nx-set-shas sets the base to the last commit that passed CI. For other CI providers, see set the affected base commit in CI.

If you don't have a CI workflow yet, generate one:

Terminal window
nx add @nx/workspace
nx g @nx/workspace:ci-workflow --ci=github

Supported --ci values: github, circleci, gitlab, azure, bitbucket-pipelines. The generated workflow also includes the Nx Cloud steps described below.

Nx runs the affected tasks in parallel on the CI machine, in the order the task graph requires.

With workers, your tasks run across several machines instead of one. With dynamic task packing, Nx Cloud uses what it knows about each task, such as its duration and its CPU and memory use, to keep workers close to capacity, so fewer machine-minutes sit idle. In most workspaces, that adds up to about 50% fewer machine-minutes than remote caching alone.

Set the number of workers in .nx/pipelines/ci.yaml:

.nx/pipelines/ci.yaml
worker-templates:
default: 3 linux-large-js

If the generator created .nx/ci-config.yaml instead, as older Nx versions do, migrate it first, because start-workers keeps reading that file while it exists.

Then start them early in your CI job:

.github/workflows/ci.yml
jobs:
main:
runs-on: ubuntu-latest
steps:
# ... checkout
- run: npx nx-cloud start-workers
# ... set up Node.js, install dependencies, and set SHAs
- run: npx nx affected -t lint test build

These pipelines combine affected, remote caching, and distribution.

.nx/pipelines/ci.yaml
worker-templates:
default:
# Distribute across 3 workers using the linux-large-js launch template
workers: 3 linux-large-js
# Shut idle workers down once every build task has been requested
stop-after:
- build
.github/workflows/ci.yml
name: CI
on:
push:
branches:
- main
pull_request:
permissions:
actions: read
contents: read
jobs:
main:
runs-on: ubuntu-latest
steps:
# fetch-depth: 0 gives Nx the full history it needs to work out what changed
- uses: actions/checkout@v7
with:
fetch-depth: 0
filter: tree:0
# Provisions the workers declared in .nx/pipelines/ci.yaml.
# Run it before installing dependencies so workers boot while this job installs.
- run: npx nx-cloud start-workers
- uses: actions/setup-node@v6
with:
node-version: 24
cache: 'npm'
- run: npm ci
# Sets the base to the last commit that passed CI on main
- uses: nrwl/nx-set-shas@v5
# Runs lint, test, and build only for projects affected by this change.
# Nx Cloud distributes these tasks across the workers started above.
- run: npx nx affected -t lint test build

For CircleCI, GitLab, Azure Pipelines, Jenkins, and Bitbucket Pipelines, see CI workflow examples.