--- title: 'AI-Powered Self-Healing CI' description: '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.' keywords: [self-healing CI, AI, CI automation] sidebar: order: 10 filter: 'type:Features' --- {% youtube src="https://youtu.be/aQUlsilNSQ8" title="How Nx Self-Healing CI Works" /%} 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 the Nx [project graph](/docs/features/explore-graph) and metadata. - **Non-Invasive Integration:** Works with your existing CI provider without overhauling your current setup. ## Enable self-healing CI {% aside title="VCS Integration Required" type="note" %} Your Nx Cloud workspace needs to have a [VCS integration enabled](/docs/guides/nx-cloud/source-control-integration) to use Self-Healing CI. Self-Healing CI supports GitHub, GitLab, Azure DevOps, and Bitbucket. {% /aside %} 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: ```shell npx nx@latest connect ``` Next, check the [Nx Cloud workspace settings](https://cloud.nx.app/go/workspace/settings/self-healing-ci) 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 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: {% tabs %} {% tabitem label="GitHub Actions" %} ```yaml # .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 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 ``` {% /tabitem %} {% tabitem label="GitLab CI" %} ```yaml # .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 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 ``` {% /tabitem %} {% tabitem label="Azure DevOps" %} ```yaml # 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 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 ``` {% /tabitem %} {% tabitem label="Bitbucket Pipelines" %} ```yaml # bitbucket-pipelines.yml image: node:22 pipelines: pull-requests: '**': - step: name: CI script: # Your existing steps which start-ci-run, install # dependencies, etc. # These are just illustrative examples... - npx nx start-ci-run - npm ci - npx nx affected -t lint test build after-script: # NEW: Add this section at the end of your step # IMPORTANT: after-script runs regardless of step success/failure # so it's like if: always() on GitHub - npx nx fix-ci ``` {% /tabitem %} {% /tabs %} > NOTE: If all tasks succeed then the `fix-ci` command becomes a no-op automatically, so that is why "always" is recommended. {% aside type="note" title="Bringing your own compute?" %} Bringing your own compute requires the [Nx Enterprise plan](https://nx.dev/enterprise?utm_source=nx.dev&utm_medium=callout&utm_campaign=bring-your-own-compute). When you run the agents on your own CI, Self-Healing CI works the same way. Add `nx fix-ci` to both the **main job** (the orchestrator) and each **agent job** with the appropriate "always run" condition. See the [bring your own compute guide](/docs/guides/nx-cloud/bring-your-own-compute) for complete examples. {% /aside %} ## Configuring self-healing CI Self-Healing CI configuration is primarily managed through your [Nx Cloud workspace settings](https://cloud.nx.app/go/workspace/settings/self-healing-ci) 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. {% aside type="note" title="CLI Override Available" %} This is analogous to the `--fix-tasks` flag on `nx start-ci-run`. Anything set on the CLI will take precedence over the settings here. {% /aside %} 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 {% youtube src="https://youtu.be/30qh5W8zXTY" title="Self-Healing CI Auto-Apply Suggestions" /%} 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 {% aside type="note" title="CLI Override Available" %} This is analogous to the `--auto-apply-fixes` flag on `nx start-ci-run`. Anything set on the CLI will take precedence over the settings here. {% /aside %} #### 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*`. ## Configuration 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. This file contains freeform markdown that the AI agent reads and interprets naturally. {% aside title="Why a dedicated file?" type="note" %} Using `.nx/SELF_HEALING.md` instead of `AGENTS.md` (or equivalent) separates CI-specific instructions from local development context. The file lives in the `.nx` directory alongside other Nx Cloud configuration. {% /aside %} ### Example SELF_HEALING.md ```markdown # 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. ``` ### What to include | Section | Purpose | Example | | -------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- | | **Confidence Rules** | Override how the AI categorizes failure severity | "Failures in `**/migrations/**` should be classified as `environment_state`" | | **Off-Limits Areas** | Directories or files the agent should never modify | "`/src/generated/` - auto-generated code" | | **Fix Preferences** | Guide the agent's approach to common issues | "Prefer updating ESLint rules over adding disable comments" | | **Predefined Fixes** | Specify deterministic solutions for known failures | "For lint failures, always try running `nx lint --fix` first" | | **Context** | Reference other documentation the agent should read | "See ARCHITECTURE.md for module boundaries" | ### Using CLAUDE.md If your repository already has a `CLAUDE.md` file at the root, the Self-Healing CI agent will read it for additional context. When both files exist: - **SELF_HEALING.md takes precedence** for any conflicting instructions - Both files are read, so general context in `CLAUDE.md` is still available - CI-specific instructions should go in `SELF_HEALING.md` This allows teams to maintain `CLAUDE.md` for local development workflows while using `SELF_HEALING.md` for CI-specific behavior. ### Viewing configuration status After a CI run, navigate to the pipeline execution in Nx Cloud and check the **Configurations** tab to see whether `SELF_HEALING.md` was detected and applied. ## Receiving fix notifications ### In your editor With [Nx Console](/docs/getting-started/editor-setup) installed, you'll receive notifications directly in VS Code, Cursor, or WebStorm when a fix is available: ![Notification in your editor about an AI fix](../../../../assets/features/notification-self-healing-ci.avif) ### 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 ![Self-Healing CI GitHub Comment](../../../../assets/features/self-healing-fix-gh-comment.avif) ## 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 ![Apply Self-Healing Fixes Locally](../../../../assets/features/self-healing-apply-locally.avif) ### 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 {% aside type="caution" title="Prefer workspace settings" %} We recommend configuring Self-Healing CI through **[workspace settings](https://cloud.nx.app/go/workspace/settings/self-healing-ci)** in the Nx Cloud dashboard. CLI overrides should only be used for temporary, branch-specific adjustments. {% /aside %} {% youtube src="https://youtu.be/KSb48zHbaHg" title="Specify Which Tasks to Fix" /%} ### 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 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: ```shell # Disable fix generation entirely for this run npx nx start-ci-run --fix-tasks="" # Disable auto-apply entirely for this run npx nx 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: ```shell # Only fix lint and test tasks npx nx start-ci-run --fix-tasks="*lint*,*test*" # Fix everything except e2e tasks npx nx start-ci-run --fix-tasks="!*e2e*" # Auto-apply only lint fixes npx nx 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](/docs/features/enhance-ai) - [Nx Console Editor Setup](/docs/getting-started/editor-setup) - [Nx Cloud](/docs/features/ci-features)