View all connectors

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 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)
  • network access from DX to your Jenkins controller. Allowlist DX IP addresses 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 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

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

Step 2: Generate an API token

Sign in as that user, open your username > Security (/user/<username>/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 <your Jenkins URL>/api/.

Endpoint Documentation
/api/json Jenkins remote access API
/me/api/json Jenkins remote access API
/job/{name}/api/json Jenkins remote access API
/job/{name}/{number}/api/json Jenkins remote access API
/job/{name}/{number}/stages/tree (Pipeline Graph View plugin) Pipeline Graph View plugin
/job/{name}/{number}/wfapi/describe (Pipeline Stage View plugin) 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.