Setting Up CI

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>`, and add a final `npx nx fix-ci` step. 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.

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.

- 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.

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.

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

Connect your workspace to Nx Cloud and run your CI tasks through nx. That turns on remote caching, affected, distribution, and self-healing CI. Each section below covers one of those in isolation. If you would rather start from a working pipeline, jump to the complete example.

Tour an Nx Cloud workspaceSee distributed task execution, caching, and run analytics on a live workspace before you wire up your own CI.

Make sure you have Nx

If you don't have Nx in your repo yet, add it first.

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

npx nx@latest init

Or, start fresh with a new repo:

npx create-nx-workspace@latest

Make sure CI invokes Nx CLI

Remote caching, affected, distribution, and self-healing only kick in when nx runs your tasks. nx test is fine, and so is npm test if it wraps nx test. Direct calls to jest, tsc, or eslint bypass Nx Cloud.

If you have a workflow file, swap raw tool invocations for nx run-many or nx affected:

- run: npx nx run-many -t lint test build

Use nx run-many -t <task> for multiple projects or nx run <project>:<task> for a single project.

Generate one:

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

Supported --ci values: github, circleci, gitlab, azure, bitbucket-pipelines. The generator wires up the CI task runner, remote caching, and nx fix-ci.

Remote caching

Remote cache allows your CI runs to benefit from previous runs. It takes less than 5 minutes to set up and is free to start.

Connect your workspaceSetup takes less than 5 minutes

See Remote Caching for details on the security model and eviction. For more granular control in CI, with separate read-only and read-write tokens and branch-scoped permissions, see CI access tokens.

Running only affected tasks

Use nx affected to run tasks only for projects impacted by the PR's changes:

- uses: actions/checkout@v7
  with:
    fetch-depth: 0
- run: npx nx affected -t lint test build

Nx uses NX_BASE and NX_HEAD to determine the comparison range. fetch-depth: 0 gives Nx access to the full git history. On a PR, Nx compares the branch against main (or whatever defaultBase is set to in nx.json). On a push to main, it compares against the previous commit.

See Affected for more information.

Distributing tasks across machines

With Nx Agents, you can distribute tasks across multiple machines. Add a .nx/ci-config.yaml file that says how many agents to use, then start the run with start-nx-agents.

dte:
  distribute-on: 3 linux-medium-js

- run: npx nx-cloud start-nx-agents
- run: npx nx affected -t lint test build

Distribution works with remote caching and enables task splitting for Playwright, Vitest, and other tools across machines. For every configuration option, see the CI configuration file reference. For the same setup on CircleCI, GitLab, Azure Pipelines, Jenkins, or Bitbucket, see Setting up CI for Nx Cloud.

Self-healing CI

Add npx nx fix-ci as the final step in your workflow. When a task fails, Nx Cloud analyzes the failure and proposes a fix you can apply from GitHub or the Nx Cloud UI.

- run: npx nx affected -t lint test build
- run: npx nx fix-ci
  if: always()

The if: always() ensures fix-ci runs even when prior steps fail. It catches flaky tests, configuration drift, and other issues Nx Cloud can fix without manual debugging.

See Self-healing CI for the trigger model.

Complete example

The sections above each show one piece. Here they are together as a single GitHub Actions pipeline with remote caching, affected, distribution, and self-healing all enabled.

dte:
  # Distribute across 3 agents using the linux-medium-js launch template
  distribute-on: 3 linux-medium-js
lifecycle:
  # Shut idle agents down once every build task has been requested
  stop-after:
    - build

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 agents declared in .nx/ci-config.yaml.
      # Run it before installing dependencies so agents boot while this job installs.
      - run: npx nx-cloud start-nx-agents

      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: 'npm'

      - run: npm ci

      # Runs lint, test, and build only for projects affected by this change.
      # Nx Cloud distributes these tasks across the agents started above.
      - run: npx nx affected -t lint test build

      # Analyzes any failure above and proposes a fix.
      # if: always() so it still runs when a task fails, which is the case it exists for.
      - run: npx nx fix-ci
        if: always()

For the same pipeline on another CI provider, and for provider-specific details such as shallow-clone handling and branch variables, see Setting up CI for Nx Cloud.

Resources

Remote caching: share cached task results across machines
Affected: how Nx determines what changed
Distribute task execution (Nx Agents): run tasks across multiple machines
Self-healing CI: automatic failure detection and fixes