Configuring Jenkins for Ossum DevOps

Requirements

You do not need any specific Jenkins version or plugins installed other than the standard Jenkins Git client plugin and whatever plugins you need for your build.

In order to use the DevOps feature your Jenkins server must be accessible via URL from the Internet, either directly or via a tunnel that you manage and configure such as ngrok. This requirements exist because the Ossum DevOps feature will trigger the builds in your Jenkins server as well as pull back information on the success/failure of the build. You will need to provide Ossum with the URL it needs to access this server, as well as a username and password or API token if one is required.

Configure Jenkins

The Ossum DevOps feature will initiate jobs on your Jenkins server when commits happen or when merge requests are created or modified. It is up to you to create the jobs in Jenkins as well as configure Jenkins for what you want the job to do. Ossum will take care of initiating your job at the appropriate time.

Add Ossum Credentials to Jenkins

A good place to begin is to add your Ossum credentials in Jenkins. These will be needed by Jenkins to clone/checkout your code. Jenkins offers secure storage of credentials, go ahead and add a Username with password credentials and enter your Ossum username and password.  We recommend giving the credentials an "ID" of "Ossum" as we will be referring to the credentials by their ID later on in a Jenkins pipeline script. You can use any ID you prefer, just note you will need to modify the script.

Credentials

The next step is to create your job(s).  We will show two ways to do this:

  1. The "classic" or "legacy" style Jenkins job where everything is configured via the Jenkins web forms.

  2. The newer declarative pipeline style Jenkins job where your job is configured via source code. Specifically a file named Jenkinsfile that is stored in the root of your repository.

Either approach will work fine, which is why we are showing you both ways to do it.

Setup Jenkins Classic Build Job

Click on New Item to create a new job. We chose Freestyle project, but Maven project would be another valid choice here if appropriate. Give it a name and click OK

New Classic Job

There are a lot of "details" in the Jenkins form that will be relevant to your job and what you want it to do. For this document, we are just going to focus on the parts that are relevant to connecting your job to Ossum. There are two:

Create Job Parameters

Ossum passes parameters to the build. You do not have to use or even define all of the parameters, but they are available to be used by the build to decide what it should checkout and build, decide what the build should do, or as information the build sends out in its notifications. You MUST define at least one parameter in your build even if you do not intend to use them. This is because the Jenkins API that Ossum uses to start the build will fail if the build does not define any parameters.

Here are the parameters that Ossum will send to Jenkins, along with a recommended default value and description of each.

Name Type Recommend Default Description
ossum_merge_request Boolean false 'true' if this is a merge request to be verified, 'false' for a normal commit
ossum_revision String */master git sha of the change
ossum_refspec String refs/heads/master git refspec of the change
ossum_before_revision String previous git sha (could be used with git log to get changelog of commits)
ossum_url String URL to view commit or merge request in Ossum

And this is what it looks like in Jenkins UI (for just two of these parameters):

Parameters

In this example we only intend to use these two parameters so they are the only ones we need to add.

TIP

Remember you MUST add at least one parameter to your job .. but it could be ANY parameter of any name/type. You only need to add the Ossum parameters if you want to use them in your job.

Jenkins Git Client

Git

In this example we are using the parameters passed to the job to tell the Git plugin what to checkout. The Refspec is available under the "Advanced" option in the Git plugin. Ossum will pass the branch/ref and revision information to Jenkins and these paramters allow you to configure the Git client so that it checks out that specific branch and revision so that you are building the right change and not whatever happens to be the HEAD revision of the master branch. Likewise, if you are using the job to validate a merge request these parameters will cause Jenkins to checkout the code for the merge request.

Of course the other important information here is the Git clone URL for the repository, which you can obtain from the Ossum UI, and then we also selected the credentials that we added back in the earlier step.  That is it, everything else that you configure the job to do is really up to you and what you want the job to do. With the above configuration in place, Jenkins will checkout the specific change that Ossum tells it to, so you will know that is the change that is processed by your job. You can use this single job to handle both commits and merge request verifications, however if you want your job to do different things depending on the type of request, then you can just setup two jobs. Later in this document we will show how you connect these jobs to your repository.

The next example will show how to configure a Jenkins pipeline job.

Setup Jenkins Pipeline Build Job

As noted earlier, a Jenkins pipeline means you have a file that is typically named "Jenkinsfile" and stored in the root of your repository. This file contains all of the configuration and rules for what you want the job to do. Here is a skeleton Jenkinsfile you can use to start with.  You need to add this file to your repository before you continue. Of course if already have a Jenkinsfile then you probably just want to look at this file, how it defines the necessary Ossum parameters as well as how it uses them with the Git checkout step of the file. The rest of the file is really just to provide an example.

Example Jenkinsfile

pipeline {
  agent any

  options {
      buildDiscarder(logRotator(numToKeepStr: '10'))
      skipDefaultCheckout()
      timestamps()
      timeout(time: 20, unit: 'MINUTES')
      durabilityHint 'PERFORMANCE_OPTIMIZED'
  }

  parameters {
      booleanParam(name: 'ossum_merge_request', defaultValue: false, description: 'Change is a Merge Request')
      string(name: 'ossum_revision', defaultValue: '*/master', description: 'Revision to build', trim: true)
      string(name: 'ossum_refspec', defaultValue: 'refs/heads/master', description: 'Refspec', trim: true)
      string(name: 'ossum_before_revision', description: 'Before revision', trim: true)
      string(name: 'ossum_url', description: 'Browser URL', trim: true)
  }

  stages {

    stage('Build') {
      steps {
          echo 'Running the build step'
      }
    }

    stage('Test') {
      steps {
          echo 'Running the test step'
      }
    }

    stage('Publish') {
      when { not { expression { return params.ossum_merge_request } } }
      steps {
          echo 'Running the publish step'
      }
    }

  }

}

Once you have a Jenkinsfile in your repository we are ready to create the job. The process is the same as before, click on New Item, but this time you choose Pipeline and give your job a name.

New Pipeline Job

In this example, our "pipeline" or Jenkinsfile, will going to control what the job actually does. So all we need to do is create the job, define some parameters and connect it to our repository.

As a reminder, here are the parameters that Ossum will send to Jenkins, along with a recommended default value and description of each.

Name Type Recommend Default Description
ossum_merge_request Boolean false 'true' if this is a merge request to be verified, 'false' for a normal commit
ossum_revision String */master git sha of the change
ossum_refspec String refs/heads/master git refspec of the change
ossum_before_revision String previous git sha (could be used with git log to get changelog of commits)
ossum_url String URL to view commit or merge request in Ossum

And this is what it looks like in Jenkins UI (for the two parameters we need to define now):

Parameters

With the parameters configured we now can connect the job to our repository and the Jenkinsfile:

Git

The configuration provides Jenkins just enough information to connect to your repository and find the Jenkinsfile. Using the approach demonstrated here of defining the paramters to use for the checkout, this job can be used for all branches as well as your merge requests should you choose to do so.  When the jobs run, Jenkins will update the job configuration with the parameters and other settings from the file.

After it runs once you should see the pipeline stages in the Jenkins UI:

New Classic Job

The example Jenkinsfile illustrates how to condition some of the pipeline stages based on whether or not the job is verifying a merge request or performing post commit CI. So it ought to be possible to handle both types of events from a single job. However, as noted previously, you can also just create two jobs if you want to configure them differently in some other way, or have other reasons for wanting them separated. Likewise, if you did not want your jobs to execute on certain branch names, you could condition steps based on the value of the ossum_refspec parameter which would contain a value like "refs/heads/branchname".

Regardless of whether you configured a Classic job or a Pipeline job, the next step is to configure Ossum so that it knows how to talk to your Jenkins server as well as the name of the job(s) you want it run.

Last Updated: 10/8/2019, 9:11:16 PM