Skip to content
Nx Docs

Setting Up CI

Tutorial 8/8: Set up CI with Nx Cloud

Help me set up CI for my Nx workspace.

Connect to Nx Cloud with , generate a CI workflow with , and walk me through remote caching, affected commands, and self-healing CI.

Stay on-topic: only teach what's covered on this page. Do not introduce concepts from later tutorials.

Tutorial: https://master.nx.dev/docs/getting-started/tutorials/self-healing-ci-tutorial.md

Help me set up CI for my Nx workspace.

Connect to Nx Cloud with , generate a CI workflow with , and walk me through remote caching, affected commands, and self-healing CI.

Stay on-topic: only teach what's covered on this page. Do not introduce concepts from later tutorials.

Tutorial: https://master.nx.dev/docs/getting-started/tutorials/self-healing-ci-tutorial.md

Connect your workspace to Nx Cloud, generate a CI workflow, and enable remote caching, affected commands, distributed task execution, and self-healing to keep your pipeline fast and reliable.

Connect to Nx Cloud

Section titled “Connect to Nx Cloud”

Connect your workspace to Nx Cloud to enable remote caching and CI features:

Terminal window
nx connect

This creates an Nx Cloud account (if you don't have one) and connects your workspace. Once connected, you can see your workspace in your Nx Cloud organization.

The access token is stored in nx.json and should be committed to your repository. It only grants cache read/write access, not admin access to your Nx Cloud organization.

Generate a CI workflow

Section titled “Generate a CI workflow”

Generate a CI workflow configuration for GitHub Actions:

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

The @nx/workspace package provides the CI workflow generator. Once installed, the generator creates a .github/workflows/ci.yml file. It also supports CircleCI, GitLab CI, Azure Pipelines, and Bitbucket Pipelines. Pass a different --ci value or run nx g @nx/workspace:ci-workflow --help to see all options.

.github/workflows/ci.yml
name: CI


on:
  push:
    branches:
      - main
  pull_request:


permissions:
  actions: read
  contents: read


jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          filter: tree:0
          fetch-depth: 0


      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'


      - run: npm ci


      - run: npx nx affected -t lint test build


      - run: npx nx fix-ci
        if: always()

This workflow includes several Nx CI features out of the box. The sections below explain each one.

Remote caching

Section titled “Remote caching”

When Nx Cloud is connected, task results are cached remotely. If a task has already run with the same inputs (on any machine or CI run), the result is replayed instantly instead of running again.

This means:

  • The second CI run on a PR is faster because unchanged tasks hit the cache
  • Developers pulling the latest main get cached results from CI
  • Build artifacts like dist/ and test coverage are restored from cache, not recomputed

For more details, see remote cache (Nx Replay).

Running only affected tasks

Section titled “Running only affected tasks”

The generated workflow uses nx affected instead of nx run-many. This compares the PR's changes against the base branch and only runs tasks for projects that could be impacted:

Terminal window
nx affected -t lint test build

Nx determines the base and head commits using NX_BASE and NX_HEAD environment variables. The generated CI workflow configures these automatically through the fetch-depth: 0 checkout, which gives Nx access to the full git history for comparison.

On a PR, Nx compares the PR branch against main (or whatever defaultBase is set to in nx.json). On a push to main, it compares against the previous commit.

For more details, see affected.

Distributing tasks across machines

Section titled “Distributing tasks across machines”

For larger workspaces, you can distribute task execution across multiple machines using Nx Agents. Instead of running all tasks on a single CI runner, Nx Cloud coordinates the work across a fleet of agents:

# Add to your CI workflow
- run: npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js"

Nx Agents automatically split tasks across the available agents, respecting task dependencies and maximizing parallelism. No configuration changes to your tasks are needed.

For more details, see distribute task execution (Nx Agents).

Self-healing CI

Section titled “Self-healing CI”

The npx nx fix-ci command at the end of the workflow enables self-healing CI. When a task fails, Nx Cloud analyzes the failure and suggests a fix that you can apply directly from your editor (via Nx Console).

This is useful for catching flaky tests, configuration drift, and other issues that can be auto-remediated without manual debugging.

For more details, see self-healing CI.

Next steps

Section titled “Next steps”

Previous: Reducing Configuration Boilerplate

Automate task configuration with plugins