How to Use Nx Cloud Distributed Task Execution in GitHub Actions

Nx Cloud splits a task graph across parallel agents so a large monorepo build finishes in a fraction of the wall time.

Call nx-cloud start-ci-run with an agent count, run nx affected on the main job, and have agent jobs run nx-cloud start-agent. Nx Cloud assigns tasks to whichever agent is free.

Steps

• Set NX_CLOUD_ACCESS_TOKEN as a secret.
• Start the run with npx nx-cloud start-ci-run --distribute-on.
• Run agents in a parallel matrix job.

Workflow

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npm ci
      - run: npx nx-cloud start-ci-run --distribute-on="3 linux-medium"
      - uses: nrwl/nx-set-shas@v4
      - run: npx nx affected -t lint test build
  agents:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        agent: [1, 2, 3]
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx nx-cloud start-agent

Gotchas

• Agents must check out and install the same commit so task hashes match the main job.
• A missing NX_CLOUD_ACCESS_TOKEN disables distribution and the run executes locally.

Related guides