AI-Powered Self-Healing CI

Nx Cloud Self-Healing CI is an AI-powered system that automatically detects, analyzes, and proposes fixes for CI failures, offering several key advantages:

• Improves Time to Green (TTG): Automatically proposes fixes when tasks fail, significantly reducing the time to get your PR merge-ready. No more babysitting PRs.
• Keeps You in the Flow: Get notified about failed PRs and proposed fixes via PR/MR comments or directly in your editor with Nx Console (VS Code, Cursor, or WebStorm). Review, approve, and keep working while AI handles the rest.
• Leverages Deep Context: AI agents understand your workspace structure, project relationships, and build configurations through Nx's project graph and metadata.
• Non-Invasive Integration: Works with your existing CI provider without overhauling your current setup.

Enable Self-Healing CI

VCS Integration Required

Your Nx Cloud workspace needs to have a VCS integration enabled to use Self-Healing CI. Self-Healing CI supports GitHub, GitLab, Azure DevOps, and Bitbucket.

To enable Self-Healing CI in your workspace, you'll need to connect to Nx Cloud and configure your CI pipeline.

If you haven't already connected to Nx Cloud, run the following command:

npx nx@latest connect

Next, check the Nx Cloud workspace settings in the Nx Cloud web application to ensure that "Self-Healing CI" is enabled.

Configure your CI pipeline

Add a step to your CI configuration's "main" job that runs the fix-ci command. It doesn't matter exactly what this job is called, it is whichever job in your config where you invoke nx-cloud start-ci-run and kick off your nx run-many or nx affected commands.

By default, your CI provider will only run the step if the previous steps succeeded, but by definition we want to run Self-Healing CI even when previous steps fail. Therefore make sure you are using a condition of if: always() or equivalent to ensure it runs even when previous steps fail:

GitHub Actions

.github/workflows/ci.yml

name: CI

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      # Your existing steps which check out the repo, start-ci-run, install
      # dependencies, etc.
      # These are just illustrative examples...
      - 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

      # NEW: Add this step at the end of your job
      - run: npx nx fix-ci
        if: always() # IMPORTANT: Always run

GitLab CI

.gitlab-ci.yml

stages:
  - build

main:
  stage: build
  script:
    # Your existing steps which check out the repo, start-ci-run, install
    # dependencies, etc.
    - npx nx-cloud start-ci-run
    - npm ci
    - npx nx affected -t lint test build
  # NEW: Add this section at the end of your job if you don't
  # already have an after_script section
  after_script:
    # IMPORTANT: after_script runs regardless of job success/failure
    # so it's like if: always() on GitHub
    - npx nx fix-ci

Azure DevOps

azure-pipelines.yml

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  # Your existing steps which check out the repo, start-ci-run, install
  # dependencies, etc.
  # These are just illustrative examples...
  - task: NodeTool@0
    inputs:
      versionSpec: '22.x'
  - script: npx nx-cloud start-ci-run
  - script: npm ci
  - script: npx nx affected -t lint test build

  # NEW: Add this step at the end of your job
  - script: npx nx fix-ci
    condition: always() # IMPORTANT: Always run

NOTE: If all tasks succeed then the fix-ci command becomes a no-op automatically, so that is why "always" is recommended.

Configuring Self-Healing CI

Self-Healing CI configuration is primarily managed through your Nx Cloud workspace settings in the Nx Cloud dashboard. This provides a centralized, auditable way to control the feature's behavior.

General Settings

Setting	Description
Enable Self-Healing CI	Enable Self-Healing CI for PRs in the current workspace
GitHub PR comments	Show Self-Healing CI feedback and actions within GitHub PR comments (in addition to the Nx Cloud UI)
Auto-retry flaky tasks	Automatically re-run tasks that are detected as flaky to improve CI reliability. This works by pushing an empty commit to the PR branch
Allow public link access	Allow anyone with access to the link the ability to apply or reject a suggested change (not recommended unless absolutely necessary)
Draft PR handling	Allow Self-Healing CI to create fixes for draft PRs
Protected branch prefixes	Configure branch prefixes for which fixes should not be generated (e.g., release/ will match release/v1.0). The default branch and branches named main, master, trunk, dev, stable, or canary will never have fixes generated

Eligible Tasks

Control which failing tasks Nx Cloud will actively try and fix for pull request CI pipeline executions.

CLI Override Available

This is analogous to the --fix-tasks flag on nx-cloud start-ci-run. Anything set on the CLI will take precedence over the settings here.

You can choose between two modes:

Mode	Description
Any failing task	Any task that fails during PR CI pipeline executions is eligible (recommended)
Specific patterns	Limit Self-Healing CI to failing PR tasks that match the specified glob patterns

You can also specify Never fix patterns to exclude certain tasks from ever being fixed by Self-Healing CI. For example, *e2e* would exclude all e2e-related tasks.

Auto-Apply Verified Code Changes

Automatically commit code change suggestions to the PR branch when ALL of these are true:

1. The task matches the glob patterns configured below
2. The AI agent is highly confident that the suggested code change will fix the failing task
3. The suggestion has been explicitly verified to fix the failing task

CLI Override Available

This is analogous to the --auto-apply-fixes flag on nx-cloud start-ci-run. Anything set on the CLI will take precedence over the settings here.

Deterministic Nx Checks

A built-in preset that auto-fixes failures from nx format:check, nx sync:check, and nx conformance:check commands. The AI agent has special knowledge of these commands and will invoke the corresponding "writable" version to fix the issue (e.g., nx format). You can safely enable this preset even if you only use a subset of these commands.

Additional Include Patterns

Tasks matching these patterns will also have high-confidence, verified code changes auto-applied. For example: *build*, *test*, lint.

Exclude Patterns

Tasks matching these patterns will never have code changes auto-applied, even if they match the include patterns or presets specified above. For example: *e2e*.

Customization with CLAUDE.md

Create a CLAUDE.md file in your repository root to provide additional context to the AI agent:

Failure Classification Rules

Override how the AI categorizes failures:

## Failure Classification

- Failures in `**/migrations/**` should be classified as `environment_state`
- Test timeouts in e2e tests are usually `flaky_task`

Predefined Fixes

Specify deterministic solutions for common failures:

## Predefined Fixes

- For lint failures, always try running `nx lint --fix` first
- Format failures should use `nx format:write`

Receiving Fix Notifications

In Your Editor

With Nx Console installed, you'll receive notifications directly in VS Code, Cursor, or WebStorm when a fix is available:

On your Pull Request/Merge Request

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

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

Applying and Reverting Fixes

Applying a Fix

You can apply a proposed fix through:

1. Editor notification - Click "Apply" in the Nx Console notification
2. PR/MR comment - Click the "Apply" button
3. Nx Cloud UI - Use the apply button in the diff viewer

Applying Locally for Fine-Tuning

If a fix is 90% correct but needs minor adjustments:

1. Click "Apply Locally" in the GitHub comment or Nx Cloud UI
2. Run the provided command in your terminal
3. Make your adjustments and commit

Reverting a Fix

If you accidentally applied a fix, you can:

1. Manually revert the Git commit
2. Use the "Revert changes" button in the Nx Cloud diff viewer

Advanced: CLI Overrides

Prefer workspace settings

We recommend configuring Self-Healing CI through workspace settings in the Nx Cloud dashboard. CLI overrides should only be used for temporary, branch-specific adjustments.

When to Use CLI Overrides

• Temporarily disable Self-Healing CI on a sensitive branch
• Test configurations before committing to workspace settings

Available Flags

Pass these flags to nx-cloud start-ci-run:

Flag	Description	Example
--fix-tasks	Override which tasks are eligible for fixes	--fix-tasks="*lint*,*test*"
--auto-apply-fixes	Override which tasks can be auto-applied	--auto-apply-fixes="*lint*"

Disabling Features via CLI

Use an empty string to disable a feature for a specific CI run:

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

# Disable auto-apply entirely for this run
npx nx-cloud start-ci-run --auto-apply-fixes=""

Both flags treat empty string consistently as an explicit "disable" override.

Pattern Syntax

Patterns use glob syntax to match task names:

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

# Fix everything except e2e tasks
npx nx-cloud start-ci-run --fix-tasks="!*e2e*"

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

Precedence Rules

When both workspace settings and CLI overrides are present:

1. CLI override (if provided) always takes precedence
2. Falls back to workspace settings if no CLI override
3. Empty string ("") is an explicit "disable", not "use defaults"

Viewing Applied Configuration

After your CI runs, navigate to the CIPE → Configurations tab to see:

• What workspace settings were relevant at the time of the CI pipeline execution
• What CLI overrides were applied, if any
• What the final, effective configuration was

---

Learn More

• Nx AI Documentation
• Nx Console Editor Setup
• Nx Cloud