Trigger Jenkins Job Remotely using Jenkins API

A Youtube video is also available if you like watching instead of reading

Jenkins is the master of flexibility. It supports a wide range of configurations through its plugins. There are various triggering options supported by Jenkins's job such as ‘Build periodically’, ‘GitHub hook trigger’, ‘trigger build remotely’, etc.

In this story, we are going to learn how to trigger Jenkins's job remotely using Jenkins API.

Why do we need to trigger builds remotely?

“Trigger builds Remotely” feature provides flexibility that allows triggering a job from the script, command line, GitHub hook when somebody has committed a change or triggers a job from one server to another

For Example, Trigger an integration tests job when a developer creates a Pull Request to make sure the new changes are not broken the existing functionality

Let’s Get Started!

There are three main steps required to configure.

1. Create an authentication token
2. Configure a job to trigger from remote
3. Trigger the job from a remote resource

Create an Authentication Token

The authentication token is nothing but token-based credentials that grant authorization to trigger the job. The token can be generated by Jenkins's user. Generating an authentication token is simple and straightforward.

• Click on the username drop-down icon from the top right corner of the Jenkins server page and click on the configuration options.

Configure options for Authentication Token

Tips: ‘Enable Security’ options from Manage Jenkins -> Configure global security if the user login feature isn’t enabled in your jenkins server

• Find the “Add new Token” button and click on it.
• Add the token name and click on the “Generate”
• Copy the token name (We will configure this token in the job)

Add new token

Configure a job to trigger from remote

• Create a new FreeStyle job or use the existing one, Go to configuration -> Build Triggers sections and check the “Trigger builds remotely(e.g., from scripts)” option and type the token name in the Authentication Token text box

Trigger the job from a remote resource

All the settings have been done successfully, Now it's time to trigger the job using CURL, WGET commands. You can also use Postman or Github webhook to trigger the job.

Replace the ‘api_token’ with the real token string in the below command

// Run when the anonymous user has the build permission
$curl http://127.0.0.1:8080/job/Trigger_Remote_Demo/build?token=My-token
//Send request with credentials
$curl -u username:api_token http://127.0.0.1:8080/job/Trigger_Remote_Demo/build?token=My-token
// Build with Parameter
$curl -u username:api_token http://127.0.0.1:8080/job/Trigger_Remote_Demo/buildWithParameters?token=My-token&para1=val1&para2=val2

Trigger the Job using the WGET command

$wget http://127.0.0.1:8080/job/Trigger_Remote_Demo/build?token=My-token
$wget --auth-no-challenge --http-user=username --http-password=api_token http://127.0.0.1:8080/job/Trigger_Remote_Demo/build?token=My-token

Troubleshoot

1. The username is not displayed on the top right corner and also no option for login

Solution: ‘Enable Security’ options from Manage Jenkins -> Configure global security if the user login feature isn’t enabled in your Jenkins server

2. No valid crumb was included in the request

Solution:

1. Disable the “Prevent Cross-Site Request Forgery exploits” option from Configure Global Security → CSRF Protection
2. Add the crumb in the request header

• Get the Crum (HTTP://127.0.0.1:8080/crumbIssuer/api/json)

curl -H "Jenkins-Crumb:670fd068556684829074ac2e1c62ae782899456d64de907********" -u admin:11de80ecdf6e9948**************** http://127.0.0.1:8080/job/Trigger_Remote_Demo/build?token=My-token

Thank you and Good luck