AI Auto-Fix — automatically create a PR when a build fails

[shenxianpeng]

Summary

explain-error-plugin today is a read-only tool: it analyzes a failed build and explains
why it failed in plain English. That's useful, but the developer still has to open their
editor, apply the fix, commit, and push — all manually.

This feature closes that loop. When autoFix: true is set, the plugin doesn't just explain
the failure — it asks the AI for a structured fix, applies it via the SCM API, and opens
a pull request, all without leaving Jenkins.

  Build fails
      │
      ▼
  explainError() — explains the error  [existing]
      │
      ▼
  AutoFixOrchestrator.attemptAutoFix() — NEW
      │
      ├── 1. Ask AI for a structured fix (JSON: file path + unified diff)
      ├── 2. Validate the diff can cleanly apply to the current file
      ├── 3. Create branch  fix/jenkins-ai-{buildNumber}-{timestamp}
      ├── 4. Commit changes atomically via SCM API (no local checkout)
      ├── 5. Open PR with title, description, and a link back to the Jenkins build
      └── 6. Display the PR URL on the Jenkins build page

Why

Every Jenkins build failure today requires a human to context-switch: read the error,
understand it, open the editor, write the fix, commit, push, wait for CI. For a class of
deterministic errors — a missing dependency in pom.xml, a wrong version in build.gradle,
a misconfigured environment variable — the fix is mechanical and the AI already knows
what it is.

This feature makes the loop automatic for those cases:

• Jenkins becomes an active repair agent, not just a passive reporter
• Zero extra infrastructure — the plugin reuses the Git token already stored in Jenkins
  Credentials; no new secrets or SCM apps to configure
• Full traceability — the PR description links back to the Jenkins build URL, so
  reviewers know exactly which failure prompted the change
• Human stays in control — the PR is never auto-merged; a developer reviews and approves
  it like any other change. Draft PR mode (autoFixDraftPr: true) is also supported to make
  the intent even more explicit

Usage

  post {
    failure {
      explainError(
        autoFix: true,
        autoFixCredentialsId: 'github-token',   // Jenkins Credentials ID
        autoFixScmType: 'github',                // 'github' | 'gitlab' | 'bitbucket'
        autoFixDraftPr: true,                    // optional: open as draft
        autoFixAllowedPaths: ['pom.xml', 'build.gradle', '*.properties']
      )
    }
  }

What gets created

When the AI identifies a fixable error with high or medium confidence, the plugin:

1. Creates a branch named fix/jenkins-ai-{buildNumber}-{timestamp}
2. Commits the file changes atomically (GitHub Trees API / GitLab Commits API)
3. Opens a PR with this description template:

AI Auto-Fix by explain-error-plugin

Jenkins Build: my-job #42
Error Type: dependency
AI Confidence: high

What failed

Could not resolve com.example:missing-lib:1.2.3

What this PR changes

• pom.xml: added missing dependency declaration

If the AI is not confident, or the diff cannot cleanly apply to the current file content,
no branch is created and the plugin logs a clear reason.

Safety boundaries

Scenario	Behavior
confidence: low	No PR created, reason logged
Diff doesn't apply cleanly (file changed	Branch deleted, error logged
since build)
Invalid credentials / no write permission	Clear error message, no branch created
Rate limited (429)	3 retries with exponential backoff, then gives up
Branch name collision	Retries with a random 4-hex suffix
File outside autoFixAllowedPaths	Rejected before any SCM call
Timeout exceeded (autoFixTimeoutSeconds,	Cancelled cleanly
default 60s)

SCM support

• GitHub — Git Trees API for atomic multi-file commits
• GitLab — Commits API with actions[] array (natively atomic)
• Bitbucket Cloud — Files API

GitHub Enterprise and self-hosted GitLab are supported via autoFixGithubEnterpriseUrl /
autoFixGitlabUrl parameters.