Jenkins
Port's Jenkins integration allows you to model Jenkins resources in your software catalog and ingest data into them.
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.
The prerequisites required for installation are listed below.
-
Go to the Jenkins Connectors page in Port.
-
Under
Select your installation method, chooseHosted by Port. -
Configure the
Installation parametersandAdvanced configurationas you wish (see below for details).
Installation parameters
Each integration requires specific parameters (such as an API token, a URL, etc.), as seen in Port's UI when installing it. Hover over the ⓘ icon next to each parameter to see more details about it.
Advanced configuration
- During the installation process each integration may have additional settings under the
Advanced configurationsection in Port's UI. Additionally, each integration has one or more settings that can be configured after installation. To do so, click on the integration's name in the Connectors page and navigate to theSettingtab. Hover over the ⓘ icon next to each setting to see more details about it.
Port secrets
Some integration settings require sensitive pieces of data, such as tokens. For these settings, Port secrets will be used, ensuring that your sensitive data is encrypted and secure.
When filling in such a setting, its value will be obscured (shown as ••••••••).
For each such setting, Port will automatically create a secret in your organization.
To see all secrets in your organization, follow these steps.
Port source IP addresses
When using this installation method, Port will make outbound calls to your 3rd-party applications from static IP addresses. You may need to add these addresses to your allowlist, in order to allow Port to interact with the integrated service:
- Europe (EU):
54.73.167.226,63.33.143.237,54.76.185.219 - United States (US):
3.234.37.33,54.225.172.136,3.225.234.99
-
Go to the Jenkins Connectors page in your portal.
-
Select the
Self-hostedmethod. -
A
helmcommand will be displayed, with default values already filled out (e.g. your Port client ID, client secret, etc). Copy the command, replace the placeholders with your values, then run it in your terminal to install the integration.
Live event support
Currently, live events are not supported for this integration.
Resyncs will be performed periodically (with a configurable interval), or manually triggered by you via Port's UI.
Therefore, real-time events (including GitOps) will not be ingested into Port immediately.
Live events support for this integration is WIP and will be supported in the near future.
The resync interval can be configured using the scheduledResyncInterval parameter. See the optional parameters section below for more details.
Required parameters:
port.clientId- Your Port client ID.port.clientSecret- Your Port client secret.port.baseUrl- Your Port API URL (https://api.port.iofor EU,https://api.us.port.iofor US).integration.identifier- Change the identifier to describe your integration.integration.type- The integration type.integration.eventListener.type- The event listener type.integration.config.appHost- The host of the Port Ocean app. Used to set up the integration endpoint as the target for webhooks created in Jenkins.integration.secrets.jenkinsUser- The Jenkins username.integration.secrets.jenkinsToken- The Jenkins password or token.integration.config.jenkinsHost- The Jenkins host.
Optional parameters (click to expand)
scheduledResyncInterval- The number of minutes between each resync.initializePortResources- Default true, When set to true the integration will create default blueprints and the port App config Mapping.sendRawDataExamples- Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true.
Recommended resource sizes
To ensure optimal performance and avoid out-of-memory (OOM) errors, we recommend the following resources for this integration:
- CPU Limit:
800m - CPU Request:
100m - Memory Limit:
1Gi - Memory Request:
1Gi
Set resource values
helm install my-integration port-labs/port-ocean \
# ... other parameters
--set resources.limits.cpu=800m \
--set resources.limits.memory=1Gi \
--set resources.requests.cpu=100m \
--set resources.requests.memory=1Gi
- GitHub
- Jenkins
- Azure DevOps
- GitLab
- Go to the Jenkins Connectors page in your portal.
- Under Select your installation method, choose your desired CI/CD platform.
- Copy the workflow and replace the placeholders with your values.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a GitHub Actions secret |
|---|---|---|---|
port_client_id | Your Port client ID (How to get the credentials). | ✓ | ✓ |
port_client_secret | Your Port client secret (How to get the credentials). | ✓ | ✓ |
port_base_url | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
jenkins_host | The Jenkins host. | ✓ | ✓ |
jenkins_user | The Jenkins username. | ✓ | ✓ |
jenkins_token | The Jenkins password or token. | ✓ | ✓ |
initialize_port_resources | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
integration_identifier | The identifier of the integration that will be installed. | ✗ | ✗ |
send_raw_data_examples | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Your Jenkins agent must be able to run Docker commands.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a Jenkins credential (Secret Text) |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | The Jenkins host. | ✓ | ✓ |
OCEAN__ | The Jenkins username. | ✓ | ✓ |
OCEAN__ | The Jenkins password or token. | ✓ | ✓ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Here is an example for a Jenkinsfile pipeline file:Jenkins pipeline (click to expand)
Prerequisites
- Your Azure Devops agent should be able to run docker commands. Learn more about agents here.
- You must have permissions to create and manage Azure DevOps variable groups for storing credentials.
Set up your credentials
- Create a Variable Group: Name it port-ocean-credentials.
- Store the required variables (see the table below).
- Authorize Your Pipeline:
-
Go to "Library" -> "Variable groups."
-
Find port-ocean-credentials and click on it.
-
Select "Pipeline Permissions" and add your pipeline to the authorized list.
-
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as an Azure DevOps pipeline variable |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | The Jenkins host. | ✓ | ✓ |
OCEAN__ | The Jenkins username. | ✓ | ✓ |
OCEAN__ | The Jenkins password or token. | ✓ | ✓ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Here is an example for a azure-pipeline.yml pipeline file:Azure pipeline (click to expand)
- Go to the Jenkins Connectors page in your portal.
- Under Select your installation method, choose your desired CI/CD platform.
- Copy the workflow and replace the placeholders with your values.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a GitLab CI/CD variable |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | The Jenkins host. | ✓ | ✓ |
OCEAN__ | The Jenkins username. | ✓ | ✓ |
OCEAN__ | The Jenkins password or token. | ✓ | ✓ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Create jenkins blueprints
Before configuring the integration, create the following blueprints in your Port organization.
Follow the instructions below to create the blueprints:
-
Go to the Data model page in Port.
-
Click on
+ Blueprint. -
Click on the
{...} Edit JSONbutton. -
Copy and paste the following JSON configuration:
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": {}
}
- Click
Createafter copying each blueprint json to save it and repeat the process for the next 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"
}