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.

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 for small teams.

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@v4
  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 with a single line of code in your CI workflow. No complicated configuration required.

- run: npx nx start-ci-run --distribute-on="3 linux-medium-js"
- run: npx nx affected -t lint test build

It works seamlessly with remote caching and enables task splitting for Playwright, Vitest, etc. across machines.

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.

Resources

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