> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nrwl/nx/llms.txt
> Use this file to discover all available pages before exploring further.

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

<CardGroup cols={2}>
  <Card title="Faster time to green" icon="clock">
    AI proposes fixes when tasks fail, reducing the time from a failing PR to a merge-ready one.
  </Card>

  <Card title="Stay in flow" icon="zap">
    Get fix notifications in your editor via Nx Console (VS Code, Cursor, WebStorm) or directly on the PR comment thread.
  </Card>

  <Card title="Deep workspace context" icon="graph">
    The AI agent understands your project graph, module boundaries, and build configurations — not just the error message.
  </Card>

  <Card title="Non-invasive" icon="plug">
    Works with your existing CI provider and pipeline configuration without requiring a full overhaul.
  </Card>
</CardGroup>

## Enable self-healing CI

<Note>
  A [VCS integration](/concepts/how-caching-works) (GitHub, GitLab, Azure DevOps, or Bitbucket) must be configured in your Nx Cloud workspace before enabling Self-Healing CI.
</Note>

<Steps>
  <Step title="Connect to Nx Cloud">
    ```bash theme={null}
    npx nx@latest connect
    ```
  </Step>

  <Step title="Enable in Nx Cloud workspace settings">
    Go to your [Nx Cloud workspace settings](https://cloud.nx.app/go/workspace/settings/self-healing-ci) and enable **Self-Healing CI**.
  </Step>

  <Step title="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.

    <Tabs>
      <Tab title="GitHub Actions">
        ```yaml theme={null}
        # .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
        ```
      </Tab>

      <Tab title="GitLab CI">
        ```yaml theme={null}
        # .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
        ```
      </Tab>

      <Tab title="Azure DevOps">
        ```yaml theme={null}
        # 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
        ```
      </Tab>

      <Tab title="Bitbucket Pipelines">
        ```yaml theme={null}
        # 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
        ```
      </Tab>
    </Tabs>

    <Note>
      If all tasks succeed, `nx fix-ci` becomes a no-op automatically. Using `if: always()` is safe and recommended.
    </Note>
  </Step>
</Steps>

## Receive fix notifications

### In your editor

With Nx Console installed (available from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console)), 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](https://cloud.nx.app/go/workspace/settings/self-healing-ci):

| 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:

```bash theme={null}
# 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:

```markdown theme={null}
# 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.