Jenkins

In this example you are going to create a webhook integration between Jenkins and Port, which will ingest job and build entities.

Prerequisites

Create the following blueprint definition and webhook configuration:

Jenkins job blueprint

{
  "identifier": "jenkinsJob",
  "description": "This blueprint represents a job event from Jenkins",
  "title": "Jenkins Job",
  "icon": "Jenkins",
  "schema": {
    "properties": {
      "jobName": {
        "type": "string",
        "title": "Project Name"
      },
      "jobStatus": {
        "type": "string",
        "title": "Job Status",
        "enum": ["created", "updated", "deleted"],
        "enumColors": {
          "created": "green",
          "updated": "yellow",
          "deleted": "red"
        }
      },
      "timestamp": {
        "type": "string",
        "format": "date-time",
        "title": "Timestamp",
        "description": "Last updated timestamp of the job"
      },
      "url": {
        "type": "string",
        "title": "Project URL"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {
    "jobUrl": {
      "title": "Job Full URL",
      "calculation": "'https://your_jenkins_url/' + .properties.url",
      "type": "string",
      "format": "url"
    }
  },
  "relations": {}
}

Jenkins build blueprint (including the jenkinsJob relation)

{
  "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"],
        "enumColors": {
          "SUCCESS": "green",
          "FAILURE": "red",
          "UNSTABLE": "yellow"
        }
      },
      "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": {},
  "calculationProperties": {},
  "relations": {
    "jenkinsJob": {
      "title": "Jenkins Job",
      "target": "jenkinsJob",
      "required": false,
      "many": false
    }
  }
}

Jenkins job and build webhook configuration

{
  "identifier": "jenkinsMapper",
  "title": "Jenkins Mapper",
  "description": "A webhook configuration to map Jenkins builds and jobs to Port",
  "icon": "Jenkins",
  "mappings": [
    {
      "blueprint": "jenkinsJob",
      "filter": ".body.type | startswith(\"item\")",
      "entity": {
        "identifier": ".body.url | sub(\"%20\"; \"-\"; \"g\") | sub(\"/\"; \"-\"; \"g\") | .[:-1]",
        "title": ".body.data.displayName",
        "properties": {
          "jobName": ".body.data.fullName",
          "url": ".body.url",
          "jobStatus": ".body.type | split(\".\") | last",
          "timestamp": ".body.time"
        }
      }
    },
    {
      "blueprint": "jenkinsBuild",
      "filter": ".body.type | startswith(\"run\")",
      "entity": {
        "identifier": ".body.data.fullDisplayName | sub(\" \"; \"-\"; \"g\") | sub(\"#\"; \"\"; \"g\")",
        "title": ".body.data.displayName",
        "properties": {
          "buildStatus": ".body.data.result",
          "buildUrl": ".body.url",
          "buildDuration": ".body.data.duration",
          "timestamp": ".body.data.timestamp"
        },
        "relations": {
          "jenkinsJob": ".body.source | tostring | sub(\"%20\"; \"-\"; \"g\") | sub(\"/\"; \"-\"; \"g\") | .[:-1]"
        }
      }
    }
  ],
  "enabled": true,
  "security": {}
}

Create the Jenkins webhook

1. Go to your Jenkins dashboard;
2. At the sidebar on the left side of the page select Manage Jenkins and click on Manage Plugins;
3. Navigate to the Available Plugins tab and search for Generic Event in the search bar. Install the Generic Event or a suitable plugin that can notify some endpoints about all events that happen in Jenkins;
4. Go back to your Jenkins dashboard and click on Manage Jenkins at the left side menu;
5. Click on the Configure System tab and scroll down to the Event Dispatcher section;
6. Enter the value of the url key you received after creating the webhook configuration in the textbox;
7. Click on Save at the buttom of the page;

tip

In order to view the different payloads and events available in Jenkins webhooks, look here

Done! any changes to a job or build process (queued, started, completed, finalized etc.) will trigger a webhook event to the webhook URL provided by Port. Port will parse the events according to the mapping and update the catalog entities accordingly.