Skip to main content

Jenkins Integration

Connect Jenkins to give Autoheal visibility into CI/CD pipeline state — answering "did a bad build deploy?", "what was the last successful build?", and "show me the pipeline logs" during incident response.

Capabilities​

Once connected, Autoheal can:

CapabilityDescription
List JobsBrowse Jenkins jobs at root level or within folders, including multibranch pipelines
Get Job DetailsView job health, last build status, recent build history, and success/failure trends
Get Build DetailsInspect build result, duration, SCM changes (commits), parameters, and trigger cause
Get Build LogRead console output with smart truncation (tail mode for errors at the end)
Get Build QueueSee what's queued, why it's waiting, and whether builds are stuck
Get Pipeline RunView pipeline stages, their status, and duration (requires Pipeline REST API plugin)

Prerequisites​

  • A Jenkins instance (self-hosted)
  • A Jenkins user account with an API token
  • Overall/Read and Job/Read permissions for the jobs you want to monitor

Setup​

1
Generate a Jenkins API Token
  1. Log in to your Jenkins instance
  2. Click your username in the top-right corner
  3. Click Security (or go to /user/<username>/security)
  4. Under API Token, click Add new Token
  5. Give it a name (e.g., "Autoheal Integration") and click Generate
  6. Copy the generated token immediately — it won't be shown again
2
Add Integration in Autoheal
  1. Go to Integrations in Autoheal
  2. Click Jenkins
  3. Enter a name (e.g., "Production Jenkins")
3
Configure Credentials

Enter the following:

  • Jenkins URL: Full URL of your Jenkins instance (e.g., https://jenkins.company.com or https://ci.company.com:8443/jenkins)
  • Username: Your Jenkins username
  • API Token: The token generated in step 1
4
Test and Save

Click Test Connection to verify, then Save.

Required Permissions​

The integration only needs read access. The following Jenkins permissions are sufficient:

PermissionWhy It's Needed
Overall/ReadAccess the Jenkins API
Job/ReadView job configuration and build history
Job/Workspace (optional)Access build artifacts
info

We recommend creating a dedicated Jenkins user for the integration rather than using a personal account. This ensures the integration isn't affected by password changes or account deactivation.

Self-Hosted Notes​

Jenkins is always self-hosted. Keep the following in mind:

  • Port and context path: Include the full URL with port and context path if applicable (e.g., https://ci.company.com:8443/jenkins)
  • Self-signed certificates: If your Jenkins uses a self-signed TLS certificate, contact your Autoheal administrator to enable TLS verification bypass
  • Firewall access: If your Jenkins is behind a firewall, use Private Access to establish a secure tunnel

Pipeline Plugin​

The Get Pipeline Run capability requires the Pipeline REST API plugin to be installed on your Jenkins instance. This plugin is included by default in most Jenkins installations with Pipeline support. If the plugin is not installed, the other six capabilities will still work normally.

Example Queries​

Once connected, you can ask Autoheal:

What's the status of the last build for the deploy-production job?
Show me the build log for the last failed build of api-server
What code changes were in build #142 of the backend-service job?
Are there any builds stuck in the queue right now?
Show me the pipeline stages for the latest run of the release-pipeline job

Troubleshooting​

401 Unauthorized
  • Verify the username and API token are correct
  • Ensure the API token hasn't been revoked in Jenkins user settings
  • Check that the Jenkins URL is correct and accessible
403 Forbidden
  • Verify the user has Overall/Read and Job/Read permissions
  • Check Jenkins authorization strategy (Matrix-based or Role-based)
  • Ensure the user isn't restricted by project-based security
Connection Timeout
  • Verify the Jenkins URL is reachable from the Autoheal network
  • Check for firewall rules blocking access
  • Consider using Private Access for firewalled instances
503 Service Unavailable
  • Jenkins may be starting up or shutting down
  • Check if Jenkins is in "Quiet Down" mode (preparing for restart)
  • Wait a few minutes and retry
Pipeline Run Not Found (404)
  • Verify the Pipeline REST API plugin is installed on your Jenkins instance
  • Check that the job is a Pipeline job (not a Freestyle job)
  • Confirm the run ID (build number) exists