--- title: "Jenkins" canonical_url: "https://docs.getdx.com/connectors/jenkins/" md_url: "https://docs.getdx.com/connectors/jenkins.md" last_updated: "2026-11-10" --- # Jenkins By integrating Jenkins with DX, you can analyze build and pipeline run data, including status, duration, branch, commit, and pipeline stages. DX reads this data through the standard Jenkins JSON API, so no plugin is required for core data and older Jenkins versions are supported. Please refer to the API documentation below and our [schema explorer](https://docs.getdx.com/schema/) to see what data DX imports. ## Prerequisites To connect Jenkins to DX, you need: - the base URL of your Jenkins controller (for example `https://jenkins.example.com`, including any path prefix such as `/jenkins`) - a Jenkins username and an API token for that user (see [Permissions](#permissions)) - network access from DX to your Jenkins controller. Allowlist [DX IP addresses](https://docs.getdx.com/allowlisting-dx/) if it is behind a firewall, or contact DX support to connect through a secure tunnel if it is not reachable from the internet - (optional) the CA certificate of your Jenkins controller if it uses a private or self-signed certificate ## Permissions Jenkins API tokens do not have scopes: a token has the same permissions as the user it belongs to. DX only makes read-only (`GET`) requests, but because the token carries the user's full permissions, we recommend a **dedicated read-only user** for DX. Grant the user: - **Overall/Read** - **Job/Read** on the jobs and folders DX should import. DX imports every job the user can see, so limit the user's access to limit what is imported. To create the user: 1. In Jenkins, go to **Manage Jenkins > Users > Create User** and create a user such as `dx-readonly`. If you use LDAP or SSO, create a service account in your identity provider instead. 2. Go to **Manage Jenkins > Security**. Under **Authorization**, choose **Matrix-based security** or **Project-based Matrix Authorization Strategy**. This needs the [Matrix Authorization Strategy](https://plugins.jenkins.io/matrix-auth/) plugin. 3. Add the user once and grant only **Overall: Read**, **Job: Read** (which implies **Job: Discover**), and optionally **View: Read**. Leave every other permission unticked. 4. Make sure an administrator keeps **Overall: Administer** in the matrix before you save, or you can lock yourself out. The user's row should look like this: ![Jenkins matrix authorization row for a read-only user with Overall Read, Job Read and View Read](https://docs.getdx.com/assets/images/connectors/jenkins/jenkins-matrix-authorization.png){class="max-w-xl mx-auto"} DX can read pipeline stages only when the **Pipeline Graph View** or **Pipeline Stage View** plugin is installed. Without either plugin, pipeline runs are still imported, but stages are not. ## Setup instructions Follow the steps below to connect Jenkins to DX. #### Step 1: Create a Jenkins user In Jenkins, create a user for DX (or choose an existing one) and give it the [permissions](#permissions) above. #### Step 2: Generate an API token Sign in as that user, open **your username > Security** (`/user//security`), and under **API Token** select **Add new Token**. Copy the token, because Jenkins only shows it once. #### Step 3: Add the connection in DX - Navigate to the connections page in DX and select "+ Connection" in the top right. - Enter the details from the previous steps: - **Jenkins Base URL** (required) - **Username** (required) - **API Token** (required) DX verifies the credentials, that at least one job is visible, and that at least one build exists. Refer to the information below for errors and troubleshooting. ## What DX imports - **Jobs**, including jobs inside folders and multibranch pipelines. Each job is marked as a standalone job, a multibranch branch, or a multibranch pull request. - **Builds** as pipeline runs. `SUCCESS` is imported as success, `FAILURE` and `UNSTABLE` as failed, and builds that are running or queued as unfinished. Branch and commit come from the Git plugin when the job checks out code from Git. - **Stages** for each finished pipeline build, when a stage plugin is available. Recent builds are imported first, then history is imported back to your DX import cutoff date. Jenkins can only return builds that still exist, so history is limited by the build retention settings of each job. ## API reference The table below lists the API endpoints that are used by DX. Jenkins documents its API on each instance at `/api/`. | Endpoint | Documentation | |----------------------------------------------------------|---------------| | /api/json | [Jenkins remote access API](https://www.jenkins.io/doc/book/using/remote-access-api/) | | /me/api/json | [Jenkins remote access API](https://www.jenkins.io/doc/book/using/remote-access-api/) | | /job/{name}/api/json | [Jenkins remote access API](https://www.jenkins.io/doc/book/using/remote-access-api/) | | /job/{name}/{number}/api/json | [Jenkins remote access API](https://www.jenkins.io/doc/book/using/remote-access-api/) | | /job/{name}/{number}/stages/tree (Pipeline Graph View plugin) | [Pipeline Graph View plugin](https://plugins.jenkins.io/pipeline-graph-view/) | | /job/{name}/{number}/wfapi/describe (Pipeline Stage View plugin) | [Pipeline Stage View plugin](https://github.com/jenkinsci/pipeline-stage-view-plugin) | ## Errors The table below lists potential error codes when adding a connection in DX. | Error | Description | |----------------------|------------------------------------------------------------------------------------------------------------------| | `invalid_credentials` | The username or API token is not valid. | | `invalid_permissions` | The user does not have the permissions required by DX. | | `no_resources` | DX cannot see any jobs, or no job has any builds, with the provided credentials. | | "Jenkins returned a web page instead of API data" | The base URL points to a login or SSO page, or is incorrect. Check the base URL, including any path prefix, and that the user can sign in with an API token. | --- ## Sitemap [Overview of all docs pages](/llms.txt)