Using Jenkins With Pipelines

A pipeline in Pipelines can be triggered from a Jenkins build job through the build Jenkins publishes to Artifactory. 

In summary, this is how Jenkins triggers Pipelines:

1. A Jenkins job successfully completes a build and publishes it to Artifactory.
2. The Jenkins job messages Pipelines through a REST API to create a new version of the BuildInfo resource.
3. In Pipelines, the change of the BuildInfo resource triggers execution of the pipeline.

The functioning of this sequence requires that the BuildInfo resource must also specify a Jenkins integration. 

Jenkins Integration

To enable Jenkins to trigger Pipelines, an administrator user must first add a Jenkins Integration The Jenkins integration specifies the Jenkins URL, as well as the username/password credentials for a valid user in JFrog Platform. These user credentials will be used to authenticate messages sent from Jenkins to Pipelines.

Jenkins Build Job

Once the Jenkins integration has been added to Pipelines, the UI view for the integration provides the callback URL and curl command lines. These provide you with the usage format of the command that Jenkins will need in order to message Pipelines. This can be viewed by all users, not just administrators.

In your Jenkins build job, add the curl command to POST using basic authorization to the Pipelines REST API  on completion of the build. You will need to add the -d option to specify the affected BuildInfo.

  post {
        success {
            script {
                sh "curl -XPOST -H \"Authorization: Basic am9obi1kb2U6cGFzc3dvcmQ=\" \"http://pipelines.mycompany.info:8082/pipelines/api/v1/projectIntegrations/627/hook\" -d '{\"buildName\":\"$JOB_NAME\",\"buildNumber\":\"$BUILD_NUMBER\",\"buildInfoResourceName\":\"jenkinsBuildInfo\"}' -H \"Content-Type: application/json\""            
            }    
        }
    }

The buildInfoResourceName parameter must specify the friendly name of the BuildInfo resource in the Pipelines DSL that represents the Jenkins-created build. In the example above, it names the jenkinsBuildInfo  resource declared in the example pipeline in the section that follows.

Pipelines DSL

The BuildInfo resource referenced by Jenkins must be declared in the Pipelines DSL. It must also be connected to the Jenkins integration by specifying it in the resource's externalCI property.

resources:
  - name: jenkinsBuildInfo
    type: BuildInfo
    configuration:
      sourceArtifactory: myArtifactory		# Replace with your Artifactory integration name
      buildName: sample-build				# Replace with your build name
      buildNumber: 1
      externalCI: MyJenkins					# Replace with your Jenkins integration name

When the BuildInfo resource is specified in the step's inputResources, then the update of that build information by the Jenkins build job will trigger the step.

pipelines:
  - name: pipelines_trigger
    steps:
      - name: start_from_jenkins
        type: Bash
        configuration:
          inputResources:
            - name: jenkinsBuildInfo
        execution:
          onExecute:
            - echo 'Jenkins job triggered Pipelines'   

When a pipeline run has been triggered by Jenkins in this manner, the BuildInfo resource will be populated with additional information about the Jenkins agent. These properties can be viewed in the run history:

A pipeline in Pipelines can trigger execution of a Jenkins build job through an outgoing webhook.

In summary, this is how Pipelines triggers Jenkins:

1. Pipelines sends an outgoing webhook message to Jenkins.
2. Jenkins receives the webhook and begins execution.

The functioning of this sequence requires that Jenkins job be configured to receive and act on a webhook. 

Preparing Jenkins

In your Jenkins job that you want Pipelines to trigger, add the  Generic Webhook Plugin. You should configure the webhook plugin with

• a token that will restrict triggering only to requests that reference that token
• if needed, any additional parameters you intend to send from Pipelines

Preparing Pipelines

An administrator user must create an Outgoing Webhook Integration that specifies the Jenkins URL and user credentials.

You should specify the URL to address the Generic Webhook Plugin on your Jenkins installation, with basic  authorization,. You must provide a valid Jenkins username an password.

Pipelines DSL

An OutgoingWebhook resource must be declared in your Pipelines DSL, and specify the Outgoing Webhook integration. It must  also declare the token parameter that the Jenkins plugin is expecting.

resources:
  - name: myJenkinsTrigger
    type: OutgoingWebhook
    configuration:
      webhookName: MyJenkinsWebhook 		# relpace with your Outgoing Webhook integration name
      parameters: token=PIPELINES1          # replace with your token value

When you specify the OutgoingWebHook resource in the step's outputResources property, the step will send the webhook to Jenkins. This will trigger execution of the Jenkins job.

pipelines:
  - name: jenkins_trigger
    steps:
      - name: step_to_jenkins
        type: Bash
        configuration:
          outputResources:
            - name: myJenkinsTrigger         # the outgoing webhook to trigger Jenkins
        execution:
          onExecute:
            - echo 'Triggered Jenkins job'