Self-Healing CI

Nx Cloud Self-Healing CI automatically detects CI failures, analyzes the root cause using AI, and proposes or applies fixes — keeping you focused on building features.

Nx Cloud Self-Healing CI is an AI-powered system that automatically detects, analyzes, and proposes fixes for CI failures. Instead of babysitting PRs, you get notified when a fix is ready to review or has already been applied.

Faster time to green

AI proposes fixes when tasks fail, reducing the time from a failing PR to a merge-ready one.

Stay in flow

Get fix notifications in your editor via Nx Console (VS Code, Cursor, WebStorm) or directly on the PR comment thread.

Deep workspace context

The AI agent understands your project graph, module boundaries, and build configurations — not just the error message.

Non-invasive

Works with your existing CI provider and pipeline configuration without requiring a full overhaul.

Enable self-healing CI

A VCS integration (GitHub, GitLab, Azure DevOps, or Bitbucket) must be configured in your Nx Cloud workspace before enabling Self-Healing CI.

1. Connect to Nx Cloud

   npx nx@latest connect
   
2. Enable in Nx Cloud workspace settings

   Go to your Nx Cloud workspace settings and enable Self-Healing CI.

3. Add nx fix-ci to your CI pipeline

   Add the nx fix-ci step at the end of your main CI job, configured to always run even when previous steps fail.

   GitHub Actions

   # .github/workflows/ci.yml
   jobs:
     main:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v6
         - uses: actions/setup-node@v6
         - run: npx nx-cloud start-ci-run
         - run: npm ci
         - run: npx nx affected -t lint test build
   
         # Add this step at the end
         - run: npx nx fix-ci
           if: always() # IMPORTANT: must always run
   

   GitLab CI

   # .gitlab-ci.yml
   main:
     stage: build
     script:
       - npx nx-cloud start-ci-run
       - npm ci
       - npx nx affected -t lint test build
     after_script:
       # after_script runs regardless of job success/failure
       - npx nx fix-ci
   

   Azure DevOps

   # azure-pipelines.yml
   steps:
     - script: npx nx-cloud start-ci-run
     - script: npm ci
     - script: npx nx affected -t lint test build
   
     # Add this step at the end
     - script: npx nx fix-ci
       condition: always() # IMPORTANT: must always run
   

   Bitbucket Pipelines

   # bitbucket-pipelines.yml
   pipelines:
     pull-requests:
       '**':
         - step:
             script:
               - npx nx-cloud start-ci-run
               - npm ci
               - npx nx affected -t lint test build
             after-script:
               # after-script runs regardless of step success/failure
               - npx nx fix-ci
   

   If all tasks succeed, nx fix-ci becomes a no-op automatically. Using if: always() is safe and recommended.

Receive fix notifications

In your editor

With Nx Console installed (available from the VS Code Marketplace), you’ll receive a notification in VS Code, Cursor, or WebStorm when a fix is available. Click Apply to commit the fix to the PR branch.

On your pull request

Self-Healing CI posts a comment on the PR with:

• A summary of the reasoning behind the proposed fix
• A diff showing the exact changes
• Buttons to apply or reject the fix

Apply and revert fixes

You can apply a proposed fix through:

• The editor notification (Nx Console)
• The PR/MR comment button
• The Nx Cloud UI diff viewer

If a fix needs minor adjustments before applying, click Apply Locally to pull the changes to your local machine, tweak them, and push.

To revert an applied fix, use the Revert changes button in the Nx Cloud diff viewer or manually revert the Git commit.

Configure self-healing behavior

Workspace settings

Configure Self-Healing CI through the Nx Cloud workspace settings:

Setting	Description
Enable Self-Healing CI	Enable or disable the feature for the workspace
GitHub PR comments	Show fix feedback in PR comments in addition to the Nx Cloud UI
Auto-retry flaky tasks	Automatically re-run tasks identified as flaky
Draft PR handling	Allow fixes to be generated for draft PRs
Protected branch prefixes	Branch prefixes for which fixes should never be generated (e.g. release/)

Auto-apply verified changes

Self-Healing CI can automatically commit fixes to the PR branch when all of the following are true:

1. The task matches the configured include patterns
2. The AI agent is highly confident the fix is correct
3. The fix has been verified to resolve the failure

A built-in preset handles deterministic Nx checks — nx format:check, nx sync:check, and nx conformance:check — automatically, running the writable counterpart (e.g. nx format) to fix the issue.

CLI overrides

Pass flags to nx-cloud start-ci-run to override workspace settings for a specific run:

# Only fix lint and test tasks
npx nx-cloud start-ci-run --fix-tasks="*lint*,*test*"

# Auto-apply only lint fixes
npx nx-cloud start-ci-run --auto-apply-fixes="lint"

# Disable fix generation entirely for this run
npx nx-cloud start-ci-run --fix-tasks=""

Customize agent behavior with SELF_HEALING.md

Create a .nx/SELF_HEALING.md file in your repository to provide project-specific instructions to the Self-Healing CI agent:

# Self-Healing Configuration

## Confidence Rules
- Fixes involving "test" targets should require high confidence
- Formatting fixes can be applied with medium confidence

## Off-Limits Areas
- `/src/generated/` - auto-generated, do not modify
- `/legacy/` - requires manual review

## Fix Preferences
- Prefer updating ESLint rules over adding disable comments
- For type errors, prefer explicit types over `any`

## Context
See ARCHITECTURE.md for module boundaries.

If a CLAUDE.md file exists at the repository root, the agent reads it for additional context. SELF_HEALING.md takes precedence over CLAUDE.md for any conflicting instructions.