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
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.
Make sure you have Nx
Section titled “Make sure you have Nx”For existing repos, run the init command and follow the prompts:
npx nx@latest initOr start fresh with a new repo:
npx create-nx-workspace@latestAdd remote caching
Section titled “Add remote caching”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.
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.
Run CI with Nx
Section titled “Run CI with Nx”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:
# ... name and triggersjobs: 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 buildfetch-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:
nx add @nx/workspacenx g @nx/workspace:ci-workflow --ci=githubSupported --ci values: github, circleci, gitlab, azure, bitbucket-pipelines. The generated workflow also includes the Nx Cloud steps described below.
# ... name and triggersjobs: main: runs-on: linux-medium-js steps: - run: npx nx affected -t lint test buildlinux-medium-js is a pre-built launch template that checks out your repository and installs its dependencies. Before your first step, Nx Cloud sets NX_BASE and NX_HEAD, so nx affected needs no extra setup. For the triggers, see the complete example. To turn it on, see Nx Cloud CI.
Nx runs the affected tasks in parallel on the CI machine, in the order the task graph requires.
Distribute tasks with workers
Section titled “Distribute tasks with workers”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:
worker-templates: default: 3 linux-large-jsIf 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:
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 buildThe job distributes tasks to its own main-job worker. To run them across more machines, add workers to the job:
jobs: main: runs-on: linux-medium-js workers: 3 linux-large-js steps: - run: npx nx affected -t lint test buildComplete example
Section titled “Complete example”These pipelines combine affected, remote caching, and distribution.
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: - buildname: 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 buildFor CircleCI, GitLab, Azure Pipelines, Jenkins, and Bitbucket Pipelines, see CI workflow examples.
name: CI
on: pull-requests: event: PR branches: [main] main-pushes: event: PUSH branches: [main]
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
jobs: main: # Checks out the repository and installs dependencies runs-on: linux-medium-js workers: default steps: # 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