Kicking off a Jenkins pipeline with Actions

Through the Jenkins integration, you can use Actions to kick off your pipeline directly through Cortex, rather than switching to Jenkins to launch a build.

Jenkins makes it super easy to submit jobs without parameters — you just need to perform an HTTP POST on JENKINS_URL/job/JOBNAME/build. If your Jenkins instance is secure, you'll have to pass a user token to call the URL.

Jenkins's docs have more info on submitting parameterized jobs, but you might pass something like this:

curl JENKINS_URL/job/JOB_NAME/buildWithParameters \
--user USER:TOKEN \
--data id=123 --data verbosity=high

In this example, we're working from a parameterized instance called app-direct. These parameters will come into play later when we construct the Action.

While in Jenkins, we can generate an API token to use later when building the Action. Go to the API Token section under the Configure tab in your user settings.

Next, copy the token and use a command line tool or a basic authentication tool like Mixed Analytics to generate an authentication header. You'll need to encode your token to base 64 if you're using the latter method using the format cortex:token. Enter the Jenkins token you just generated after cortex: to generate your user token.

caution

If you're using an authentication tool to generate an auth header, only copy the encoded token up to the equal sign. Including the equal sign at the end can cause issues when included in your secret.

Once you've generated the token, go to Secrets in Authentication and access settings in Cortex.

Select Add secret and fill out the fields in the modal.

Cortex recommends including "Jenkins" in the secret’s name to easily distinguish it from other secrets.

In the Secrets value field, paste the token you copied when you generated the authentication header.

Once you've created a secret, go to Actions in the main nav and click Create Action.

Enter a name and description for the Action; again, it's recommended that you include Jenkins in either field so users can easily identify what the Action will do.

In Action inputs, you’ll define the inputs that map to the parameters defined in Jenkins. The inputs/parameters will appear when performing an Action later on.

In the Action definition section, you'll follow the information in Jenkins’s Remote Access API documentation. Since Jenkins specifies POST as the HTTP method, we'll select that as the HTTP method in Cortex.

Under URL, we'll add a version of curl JENKINS_URL/job/JOB_NAME/buildWithParameters - copy and paste the URL for your Jenkins instance, followed by {{context.entity.tag}}/buildWithParameters. (For example, https://jenkinsinstance.example/job/{{context.entity.tag}}/buildWithParameters)

Adding {{context.entity.tag}} makes sure that entities' tags in Cortex matches the jobs in Jenkins. With this dynamic URL, we can more effectively template the Action, so we don't have to create a unique Action for each entity.

Because your secret is already stored in Cortex, you can use templating in Headers to reference your Jenkins secret: Basic {{contex.secrets.jenkins}}.

You'll use the Payload field to pass the parameters themselves.

In the Response Template field you can pass a blank response body or use Mustache templating to create messages depending on what the user entered in each field.

The last step is to map your Action to entities in the Filters section and set permissions for the users who can run the action.

Once the Action is saved, users with appropriate permissions will be able to run it from the Actions page or directly from an entity's page (if it applies under the filters).