Jenkins

Setting up Jenkins as a Continuous Integration (CI) system within Spinnaker lets you trigger pipelines with Jenkins, add a Jenkins stage to your pipeline, or add a Script stage to your pipeline.

Prerequisites

To connect Jenkins to Spinnaker, you need:

• A running Jenkins Master at version 1.x - 2.x, reachable at a URL ($BASEURL) from the provider that Spinnaker will be deployed in.
• A username/API key ($USERNAME/$APIKEY) pair able to authenticate against Jenkins using HTTP Basic Auth, if Jenkins is secured. A user’s API key can be found at $BASEURL/user/$USERNAME/configure.

Add your Jenkins master

1. First, make sure that your Jenkins master is enabled:

   hal config ci jenkins enable
   

2. Next, add Jenkins master named my-jenkins-master (an arbitrary, human-readable name), to your list of Jenkins masters:

   echo $APIKEY | hal config ci jenkins master add my-jenkins-master \
       --address $BASEURL \
       --username $USERNAME \
       --password # api key will be read from STDIN to avoid appearing
                  # in your .bash_history
   

   Note: If you use the GitHub OAuth plugin for authentication into Jenkins, you can use the GitHub $USERNAME, and use the OAuth token as the $APIKEY.

3. Re-deploy Spinnaker to apply your changes:

   hal deploy apply
   

Configure Jenkins and Spinnaker for CSRF protection

NOTE: Jenkins CSRF protection in Igor is only supported for Jenkins 2.x.

To enable Spinnaker and Jenkins to share a crumb to protect against CSRF…

1. Configure Halyard to enable the csrf flag:

   hal config ci jenkins master edit MASTER --csrf true
   

   (MASTER is the name of the Jenkins master you’ve previously configured. If you haven’t yet added your master, use hal config ci jenkins master add instead of edit. )

   Here’s what your Jenkins master configuration looks like in your Hal config:

   jenkins:
         enabled: true
         masters:
         - name: <jenkins master name>
           address: http://<jenkins ip>/jenkins
           username: <jenkins admin user>
           password: <admin password>
           csrf: true
   

   Be sure to invoke hal deploy apply to apply your changes.

2. Install Strict Crumb Issuer Plugin in Jenkins:

   a. Under Manage Jenkins > Plugin Manager > Available, search for Strict Crumb Issuer Plugin, select Install

   

3. Enable CSRF protection in Jenkins:

   a. Under Manage Jenkins > Configure Global Security, select Prevent Cross Site Request Forgery exploits.

   b. Under Crumb Algorithm, select Strict Crumb Issuer.

   c. Under Strict Crumb Issuer > Advanced, deselect Check the session ID

   

Enabling Backlinks from Jenkins to Spinnaker

You can configure orca such that it will update the description of a running Jenkins build and generate a suitable backlink.

Add the following to your orca configuration:

spinnaker:
  baseUrl:
    www: https://spinnaker.ui.url

Jenkins backlinks will be generated as follows: This build was triggered by '<a href=...>{Pipeline Name}</a>' in Spinnaker.

Next steps

You can use Jenkins in your pipelines in one of three ways:

• As a pipeline trigger
• Using the built-in Jenkins stage
• Using the Script stage

After you’ve completed the setup above, you’re ready to trigger pipelines with Jenkins or run the Jenkins stage. This is sufficient for most use cases. See Triggering Pipelines with Jenkins for more information.

Using the Script stage requires further configuration. See Configuring the Script Stage to finish setting it up.