Continuous Integration (CI) with Nx Cloud

Nx Cloud makes CI faster and cheaper in two ways:

Remote caching skips any task that already ran with the same inputs, in CI or on a developer machine. On Nx Cloud, Ultracache records the files each task actually reads, improving both cache correctness and efficiency.
Distributed task execution spreads the remaining tasks across workers, extra CI machines that Nx Cloud starts for the run, and dynamic task packing fills each worker by the CPU and memory its tasks use, so fewer machine-minutes sit idle.

In most workspaces, distribution uses about 50% fewer machine-minutes than remote caching alone. Teams using Nx Cloud report 40% to 90% faster CI.

Run your whole pipeline on Nx Cloud, or keep your CI provider and add Nx Cloud to it.

What you get with Nx Cloud on top of Nx Core

	Nx Core	Nx Cloud
Caching	Local cache, per machine	Adds a remote cache shared across your team and CI
Task inputs	Hashes each task from its declared or inferred `inputs`	Ultracache records what each task reads in CI and hashes from that
Task scheduling	Task graph on one machine, `nx affected` to skip untouched projects	Adds distribution across workers with dynamic task packing
Failing CI	You read the logs and fix it	Self-healing CI proposes a fix on the PR
Visibility	Terminal output for the run in front of you	Run history, task analytics, and CI observability

Connect your workspace to Nx Cloud

Push your workspace to a remote repository, then run:

npx nx@latest connect

Remote caching works as soon as the workspace is connected. To try Nx Cloud CI, join the private beta before you connect, because the beta sets up its own organization.

Connect from your browserSign in to Nx Cloud and connect your repository without the CLI

Run CI on Nx Cloud

Nx Cloud CI runs your whole pipeline on Nx Cloud from a .nx/pipelines/ci.yaml file, so you don't need a separate CI provider. A push or pull request on GitHub starts the jobs in that file, and the results show up on Nx Cloud and as a status on the pull request. Remote caching and self-healing CI work without extra steps, and workers take one line in the file.

Your repository must be on github.com and connected to Nx Cloud through the GitHub App. Personal access tokens, GitHub Enterprise, and other providers aren't supported yet.

Set up a pipeline

Commit this file on a branch and open a pull request into main. The name is up to you, because Nx Cloud CI runs every file in .nx/pipelines that has an on section:

# yaml-language-server: $schema=https://cloud.nx.app/nx-cloud/static/schemas/workflow.schema.json
name: CI

on:
  pull-requests:
    event: PR
    branches: [main]
  main-pushes:
    event: PUSH
    branches: [main]

jobs:
  main:
    runs-on: linux-medium-js
    steps:
      - run: npx nx affected -t lint test build

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

Each file reports one status on the pull request for the whole run, named Nx Cloud: <name>, where <name> is the file's name or, without one, its file name. To also get a check for each job, named <name> / <job>, turn on Show check runs for individual Nx Cloud CI jobs in the VCS integration settings of your workspace. A configuration error in the file shows as its own failed check, <file> / configuration, either way. Nx Cloud CI runs alongside any CI you already have, so CI runs twice until you remove the old workflow. A newer push to a pull request cancels the older run of the same file.

Distribute tasks with workers

A job distributes tasks to its own main-job worker by default. Add workers to the job to run its tasks across more machines:

jobs:
  main:
    runs-on: linux-medium-js
    workers: 3 linux-large-js
    steps:
      - run: npx nx affected -t lint test build

Workers start with the job, so they install dependencies in parallel with it. To scale workers with the size of each run, see scale workers with PR size.

For setups shared across jobs and for task rules such as stop-after, see worker-templates. To turn distribution off for a job that doesn't run Nx tasks, such as a deploy job, set workers: false. See jobs.<job>.workers.

Secrets and environment variables

Add variables on the Environment variables page of your workspace settings. Read the ones marked secret with ${{ secrets.<NAME> }} and the rest with ${{ vars.<NAME> }}. A stored variable only reaches a job where an env maps it:

env:
  NODE_OPTIONS: --max-old-space-size=8192
  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
  NPM_REGISTRY: ${{ vars.NPM_REGISTRY }}

env at the top of the file or on a job also reaches the workers of that job. Pull requests from forks don't get your stored variables. See keep secrets safe. For the variables Nx Cloud CI sets in each step, such as NX_CLOUD_SHA, see variables and files in each step.

Self-healing CI

When self-healing CI is on for your workspace, Nx Cloud adds the Fix CI step at the end of each job in jobs. Don't add nx fix-ci yourself. To limit which tasks it fixes, use the self-healing section.

Coming from GitHub Actions

The file reads like a GitHub Actions workflow, and most step-level syntax carries over. To convert a workflow, see move a GitHub Actions workflow to Nx Cloud CI.

Scheduled runs, GitHub Marketplace actions, and macOS and Windows machines aren't supported yet. For the full list, see Nx Cloud CI limits.

Use your existing CI provider

To keep your pipeline on GitHub Actions, CircleCI, GitLab, or another provider, add Nx Cloud to it. The same CI configuration file sets your workers, and nx-cloud start-workers starts them from your main job:

worker-templates:
  default: 3 linux-large-js

npx nx-cloud start-workers

For the full pipeline on your provider, see setting up CI. If your workspace has a .nx/ci-config.yaml file, migrate it to ci.yaml.

Building blocks of fast CI

Fast CI comes from two things:

Get more out of your machine minutes. Distributed task execution spreads tasks across workers so work runs in parallel. Dynamic task packing runs tasks together when their combined CPU and memory needs fit on a worker, so you get more work out of each machine.
Only run what you have to. nx affected selects tasks whose inputs your changes touch. Remote caching reuses results from tasks that already ran with the same inputs, so they don't run again.

Why task-based CI costs less

Most CI setups use static partitioning (binning and sharding), assigning work to machines up front, such as one job for tests and another for builds, and each machine runs until its slowest task ends.

CI tasks divided into fixed bins

Nx Cloud assigns individual tasks as workers free up, using the task graph and each task's past duration, CPU, and memory use. Workers stay busy, a worker that fails during setup has its work picked up by the others, and adding workers needs no change to how work is split.

CI tasks distributed across three agents

Learn how teams use Nx Cloud to scale their workspaces.

Nx Cloud features

Remote caching

Share cached task results across developer machines and CI with Nx Cloud remote caching, and hash each task from the files it reads with Ultracache, so CI skips work that already ran and costs less.

Distribute task execution (workers)

Nx Cloud workers distribute CI tasks across machines, and dynamic task packing fills each machine by CPU and memory use, so pull requests finish faster on fewer machine-minutes.

Run Only Tasks Affected by a PR

Run only the tasks a pull request affects with nx affected, which selects each task whose inputs your change touches and skips the rest.

AI-Powered Self-Healing CI

Learn how Nx Cloud Self-Healing CI uses AI to automatically detect, analyze, and fix CI failures, eliminating the need to babysit PRs and keeping you focused on building features.

Create custom launch templates Set up jobs and workers with the tools and machine size your tasks need

CI workflow examples Pipelines for CircleCI, GitLab, Azure Pipelines, Jenkins, and Bitbucket

GitHub Actions integration Run affected tasks with remote caching and PR insights on GitHub Actions

Optimize your time to green Find and fix what slows pull requests down

Record non-Nx commands Send logs from any CI command to Nx Cloud

Google identity provider Sign in to Nx Cloud with Google Workspace

Frequently asked questions

Is Nx Cloud free?

Yes. Nx Cloud starts on the free Hobby plan, which includes 50,000 credits per month, 5 contributors, and 10 concurrent CI connections, with no credit card.

Nx itself is free and open source too. Task running, the project graph, local caching, nx affected, generators, and migrations all work without an Nx Cloud account.

What happens when I use up my credits?

On the Hobby plan, Nx Cloud features turn off once the monthly credits are gone and turn back on at the next reset.

The Team plan has no such cap, and usage beyond the $29 of included credit is billed at $5.50 per 10,000 credits. See credit pricing for what each operation costs.

Is Nx Cloud cheaper than running CI on GitHub Actions alone?

With 70% of task time served from cache, pipeline times roughly halve and GitHub spend drops 15% to 40%, depending on how many machine-minutes the pipeline uses today. See GitHub Actions pricing and how to cut your CI bill for the rate tables and the break-even math.

Do unused credits carry over?

No. Your allowance resets at the start of each billing cycle.

Is there a plan for open source projects?

Yes. Nx Cloud is free for qualifying open source organizations. Talk to our engineering team to get set up.

Can I get a shared cache without Nx Cloud?

Yes. Build your own server against the remote cache OpenAPI specification, in any language. You maintain the storage, authentication, and uptime.

When should I consider Enterprise or self-hosted options?

The Enterprise plan adds SSO and SAML, dedicated support with SLAs, conformance rules, code owners, and cross-repo visibility.

On a single-tenant instance or an on-prem install, you choose the region and the infrastructure your cache and run data live on. For what a standard Nx Cloud workspace sends and stores, see the privacy policy.