Jenkins

Loading version...

Port's Jenkins integration allows you to model Jenkins resources in your software catalog and ingest data into them.

Supported resources JobBuildUserStage

Prerequisites

• Jenkins API token — In Jenkins, click your username and navigate to Configure > API Token to generate a token to use as the JENKINS_TOKEN.

• Required plugins — Install the following via Manage Jenkins > Plugins:

  • People View — Required for user information API (Jenkins 2.452 and above).
  • Pipeline: Stage View — Required for fetching pipeline stage data.

Setup

Choose your preferred installation method below. Not sure which to pick? See the installation methods overview.

Create jenkins blueprints

Before configuring the integration, create the following blueprints in your Port organization.
Follow the instructions below to create the blueprints:

1. Go to your Builder page.

2. Click + Blueprint.

3. Click the {...} Edit JSON button in the top right corner of the form.

4. Copy and paste each blueprint JSON from the sections below. Recommended order: job, then build, then user.

   Jenkins Job blueprint (click to expand)

   {
     "identifier": "jenkinsJob",
     "description": "This blueprint represents a job event from Jenkins",
     "title": "Jenkins Job",
     "icon": "Jenkins",
     "schema": {
       "properties": {
         "jobName": {
           "type": "string",
           "title": "Job Name"
         },
         "jobStatus": {
           "type": "string",
           "title": "Job Status",
           "enum": ["created", "unknown", "passing", "failing"],
           "enumColors": {
             "passing": "green",
             "created": "darkGray",
             "failing": "red",
             "unknown": "orange"
           }
         },
         "timestamp": {
           "type": "string",
           "format": "date-time",
           "title": "Timestamp",
           "description": "Last updated timestamp of the job"
         },
         "url": {
           "type": "string",
           "title": "Project URL"
         },
         "parentJob": {
           "type": "object",
           "title": "Parent Job"
         }
       },
       "required": []
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "relations": {}
   }

   Jenkins Build blueprint (click to expand)

   {
     "identifier": "jenkinsBuild",
     "description": "This blueprint represents a build event from Jenkins",
     "title": "Jenkins Build",
     "icon": "Jenkins",
     "schema": {
       "properties": {
         "buildStatus": {
           "type": "string",
           "title": "Build Status",
           "enum": ["SUCCESS", "FAILURE", "UNSTABLE", "ABORTED"],
           "enumColors": {
             "SUCCESS": "green",
             "FAILURE": "red",
             "UNSTABLE": "yellow",
             "ABORTED": "darkGray"
           }
         },
         "buildUrl": {
           "type": "string",
           "title": "Build URL",
           "description": "URL to the build"
         },
         "timestamp": {
           "type": "string",
           "format": "date-time",
           "title": "Timestamp",
           "description": "Last updated timestamp of the build"
         },
         "buildDuration": {
           "type": "number",
           "title": "Build Duration",
           "description": "Duration of the build"
         }
       },
       "required": []
     },
     "mirrorProperties": {
       "previousBuildStatus": {
         "title": "Previous Build Status",
         "path": "previousBuild.buildStatus"
       }
     },
     "calculationProperties": {},
     "relations": {
       "parentJob": {
         "title": "Jenkins Job",
         "target": "jenkinsJob",
         "required": false,
         "many": false
       },
       "previousBuild": {
         "title": "Previous Build",
         "target": "jenkinsBuild",
         "required": false,
         "many": false
       }
     }
   }

   Jenkins User blueprint (click to expand)

   {
     "identifier": "jenkinsUser",
     "description": "This blueprint represents a jenkins user",
     "title": "Jenkins User",
     "icon": "Jenkins",
     "schema": {
       "properties": {
         "url": {
           "type": "string",
           "title": "URL",
           "format": "url"
         },
         "lastUpdateTime": {
           "type": "string",
           "format": "date-time",
           "title": "Last Update",
           "description": "Last updated timestamp of the user"
         }
       },
       "required": []
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "relations": {}
   }

5. Click Create after copying each blueprint json to save it and repeat the process for the next blueprint.

Stage blueprint

The integration also supports mapping Jenkins pipeline stages, but there is no default jenkinsStage blueprint. If you want to ingest stage data, create a custom blueprint that matches the properties in the Stage mapping configuration below.

Configuration

Port integrations use a YAML mapping block to ingest data from the third-party api into Port.

The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.

Default mapping configuration

This is the default mapping configuration for this integration:

Default mapping configuration (click to expand)

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: job
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .url | split("://")[1] | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") | gsub("/"; "-") | .[:-1]
          title: .fullName
          blueprint: '"jenkinsJob"'
          properties:
            jobName: .name
            url: .url
            jobStatus: '{"notbuilt": "created", "blue": "passing", "red": "failing"}[.color]'
            timestamp: .time
            parentJob: .__parentJob


  - kind: build
    selector:
      query: 'true'
      maxBuildsPerJob: 100
    port:
      entity:
        mappings:
          identifier: >-
            .url | split("://")[1] | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") | gsub("/"; "-") | .[:-1]
          title: .displayName
          blueprint: '"jenkinsBuild"'
          properties:
            buildStatus: .result
            buildUrl: .url
            buildDuration: .duration
            timestamp: .timestamp / 1000 | todate
          relations:
            parentJob: .url | split("://")[1] | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") | gsub("/"; "-") | .[:-1] | gsub("-[0-9]+$"; "")
            previousBuild: >-
              if .previousBuild then (.previousBuild.url | split("://")[1] |
              sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") |
              gsub("/"; "-") | .[:-1]) else null end

  - kind: user
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .user.id
          title: .user.fullName
          blueprint: '"jenkinsUser"'
          properties:
            url: .user.absoluteUrl
            lastUpdateTime: if .lastChange then (.lastChange/1000) else now end | strftime("%Y-%m-%dT%H:%M:%SZ")

Monitoring and sync status

To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.

Mapping & selectors per resource

Use the explorer below to view sample payloads and the resulting Port entities for each resource type.

- kind: job
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .url | split("://")[1] | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") | gsub("/"; "-") | .[:-1]
        title: .fullName
        blueprint: '"jenkinsJob"'
        properties:
          jobName: .name
          url: .url
          jobStatus: '{"notbuilt": "created", "blue": "passing", "red": "failing"}[.color]'
          timestamp: .time
          parentJob: .__parentJob

{
  "_class" : "hudson.model.FreeStyleProject",
  "displayName" : "Hello Job",
  "fullName" : "Hello Job",
  "name" : "Hello Job",
  "url" : "http://localhost:8080/job/Hello%20Job/",
  "buildable" : true,
  "builds" : [
    {
      "_class" : "hudson.model.FreeStyleBuild",
      "displayName" : "#2",
      "duration" : 221,
      "fullDisplayName" : "Hello Job #2",
      "id" : "2",
      "number" : 2,
      "result" : "SUCCESS",
      "timestamp" : 1700569094576,
      "url" : "http://localhost:8080/job/Hello%20Job/2/"
    },
    {
      "_class" : "hudson.model.FreeStyleBuild",
      "displayName" : "#1",
      "duration" : 2214,
      "fullDisplayName" : "Hello Job #1",
      "id" : "1",
      "number" : 1,
      "result" : "SUCCESS",
      "timestamp" : 1700567994163,
      "url" : "http://localhost:8080/job/Hello%20Job/1/"
    }
  ],
  "color" : "blue"
}

{
  "identifier": "hello-job",
  "title": "Hello Job",
  "icon": "Jenkins",
  "blueprint": "jenkinsJob",
  "properties": {
    "jobName": "Hello Job",
    "url": "http://localhost:8080/job/Hello%20Job/",
    "jobStatus": "passing",
    "timestamp": "2023-09-08T14:58:14Z"
  },
  "relations": {},
  "createdAt": "2023-12-18T08:37:21.637Z",
  "createdBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW",
  "updatedAt": "2023-12-18T08:37:21.637Z",
  "updatedBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW"
}

Build Limit

The maxBuildsPerJob selector is an optional parameter that limits the number of builds fetched per job. By default it is set to 100, meaning the last 100 builds of each job will be fetched. You can increase or decrease this value to control how much build history is ingested.

- kind: build
  selector:
    query: 'true'
    maxBuildsPerJob: 100
  port:
    entity:
      mappings:
        identifier: >-
          .url | split("://")[1] | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") | gsub("/"; "-") | .[:-1]
        title: .displayName
        blueprint: '"jenkinsBuild"'
        properties:
          buildStatus: .result
          buildUrl: .url
          buildDuration: .duration
          timestamp: .timestamp / 1000 | todate
        relations:
          parentJob: .url | split("://")[1] | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") | gsub("/"; "-") | .[:-1] | gsub("-[0-9]+$"; "")
          previousBuild: >-
            if .previousBuild then (.previousBuild.url | split("://")[1] |
            sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") |
            gsub("/"; "-") | .[:-1]) else null end

{
  "_class" : "hudson.model.FreeStyleBuild",
  "displayName" : "#2",
  "duration" : 221,
  "fullDisplayName" : "Hello Job #2",
  "id" : "2",
  "number" : 2,
  "result" : "SUCCESS",
  "timestamp" : 1700569094576,
  "url" : "http://localhost:8080/job/Hello%20Job/2/"
}

{
  "identifier": "hello-job-2",
  "title": "Hello Job #2",
  "icon": "Jenkins",
  "blueprint": "jenkinsBuild",
  "properties": {
    "buildStatus": "SUCCESS",
    "buildUrl": "http://localhost:8080/job/Hello%20Job/2/",
    "buildDuration": 221,
    "timestamp": "2023-09-08T14:58:14Z"
  },
  "relations": {
    "parentJob": "hello-job"
  },
  "createdAt": "2023-12-18T08:37:21.637Z",
  "createdBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW",
  "updatedAt": "2023-12-18T08:37:21.637Z",
  "updatedBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW"
}

Below are the supported selectors for this resource. Use them under the selector key in your integration mapping configuration to control which resources are returned from the API.

Selector	Type	Description
exportEnvVariables	array	Environment variable names whose values should be included in lakehouse ingest payloads for DSP processing.
maxBuildsPerJob	integer	Number of builds to fetch. Defaults to 100 Default: 100.

- kind: user
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .user.id
        title: .user.fullName
        blueprint: '"jenkinsUser"'
        properties:
          url: .user.absoluteUrl
          lastUpdateTime: if .lastChange then (.lastChange/1000) else now end | strftime("%Y-%m-%dT%H:%M:%SZ")

{
  "user" : {
    "absoluteUrl" : "http://localhost:8080/user/admin",
    "fullName" : "admin",
    "description" : "System Administrator",
    "id" : "admin"
  },
  "lastChange" : 1700569094576
}

{
  "identifier": "admin",
  "title": "admin",
  "icon": "Jenkins",
  "blueprint": "jenkinsUser",
  "properties": {
    "url": "http://localhost:8080/user/admin",
    "lastUpdateTime": "2023-09-08T14:58:14Z"
  },
  "relations": {},
  "createdAt": "2023-12-18T08:37:21.637Z",
  "createdBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW",
  "updatedAt": "2023-12-18T08:37:21.637Z",
  "updatedBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW"
}

Control Stage Fetching

To prevent overwhelming your Ocean instance with potentially thousands of stages from Jenkins, the integration requires you to specify a specific job. This ensures that Ocean only retrieves stages related to that job, keeping things focused and efficient.

Important: The integration will also fetch stages from all nested jobs within the specified job.

- kind: stage
  selector:
    query: 'true'
    # Example jobUrl - replace with your own Jenkins job URL
    jobUrl: http://your-jenkins-server/job/your-project/job/your-job
  port:
    entity:
      mappings:
        identifier: >-
          ._links.self.href  | sub("^.*?/"; "") | gsub("%20"; "-") |
          gsub("%252F"; "-") | gsub("/"; "-")
        title: .name
        blueprint: '"jenkinsStage"'
        properties:
          status: .status
          startTimeMillis: .startTimeMillis
          durationMillis: .durationMillis
          stageUrl: env.OCEAN__INTEGRATION__CONFIG__JENKINS_HOST  + ._links.self.href
        relations:
          parentBuild: >-
            ._links.self.href | sub("/execution/node/[0-9]+/wfapi/describe$";
            "") | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") |
            gsub("/"; "-")
# Additional stage configurations follow the same pattern.
- kind: stage
  selector:
    query: 'true'
    # Example jobUrl - replace with your own Jenkins job URL
    jobUrl: http://your-jenkins-server/job/your-project/job/another-job
  port:
    entity:
      mappings:
        identifier: >-
          ._links.self.href  | sub("^.*?/"; "") | gsub("%20"; "-") |
          gsub("%252F"; "-") | gsub("/"; "-")
        title: .name
        blueprint: '"jenkinsStage"'
        properties:
          status: .status
          startTimeMillis: .startTimeMillis
          durationMillis: .durationMillis
          stageUrl: env.OCEAN__INTEGRATION__CONFIG__JENKINS_HOST  + ._links.self.href
        relations:
          parentBuild: >-
            ._links.self.href | sub("/execution/node/[0-9]+/wfapi/describe$";
            "") | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") |
            gsub("/"; "-")

- kind: stage
  selector:
    query: 'true'
    # Example jobUrl - replace with your own Jenkins job URL
    jobUrl: http://your-jenkins-server/job/your-project/job/third-job
  port:
    entity:
      mappings:
        identifier: >-
          ._links.self.href  | sub("^.*?/"; "") | gsub("%20"; "-") |
          gsub("%252F"; "-") | gsub("/"; "-")
        title: .name
        blueprint: '"jenkinsStage"'
        properties:
          status: .status
          startTimeMillis: .startTimeMillis
          durationMillis: .durationMillis
          stageUrl: env.OCEAN__INTEGRATION__CONFIG__JENKINS_HOST  + ._links.self.href
        relations:
          parentBuild: >-
            ._links.self.href | sub("/execution/node/[0-9]+/wfapi/describe$";
            "") | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") |
            gsub("/"; "-")

{
  "_links": {
    "self": {
      "href": "/job/Phalbert/job/salesdash/job/master/227/execution/node/17/wfapi/describe"
    }
  },
  "id": "17",
  "name": "Declarative: Post Actions",
  "execNode": "",
  "status": "SUCCESS",
  "startTimeMillis": 1717073271079,
  "durationMillis": 51,
  "pauseDurationMillis": 0
}

{
  "identifier": "job-Phalbert-job-salesdash-job-master-229-execution-node-17-wfapi-describe",
  "title": "Declarative: Post Actions",
  "icon": "Jenkins",
  "blueprint": "jenkinsStage",
  "team": [],
  "properties": {
    "status": "SUCCESS",
    "startTimeMillis": 1717073272012,
    "durationMillis": 26,
    "stageUrl": "http://localhost:8080/job/Phalbert/job/salesdash/job/master/229/execution/node/17/wfapi/describe"
  },
  "relations": {
    "parentBuild": "job-Phalbert-job-salesdash-job-master-229"
  },
  "createdAt": "2024-08-28T10:27:33.549Z",
  "createdBy": "<port-client-id>",
  "updatedAt": "2024-08-28T10:27:30.274Z",
  "updatedBy": "<port-client-id>"
}

Below are the supported selectors for this resource. Use them under the selector key in your integration mapping configuration to control which resources are returned from the API.

Selector	Type	Description
exportEnvVariables	array	Environment variable names whose values should be included in lakehouse ingest payloads for DSP processing.
jobUrl	string	The URL of the Jenkins job to fetch stages for.