Jenkins Build Trigger using remote access API is a key element when it comes to automating the Deployment process and implementing the CI/CD pipelines with Jenkins.
In this post, we are going to see how to create a Jenkins Job or Project and configure API token and enable REMOTE API and trigger it from remote.
This RemoteAPI can be used as a Webhook in the Source Control Management Product like Bitbucket, GitHub, Beanstalk etc.
This can be added to the OnPush (or) OnCommit event. So whenever there is a new code commit to the repository the Jenkins Job would be triggered automatically so that you would have the Latest Code Deployed in your application server as soon as you make any changes
Steps to configure Jenkins Remote Build Trigger without any Plugin
This methodology is little complicated as we need to create a Jenkin user along with the token for the build trigger to work. It does not allow anonymous users to initiate a build just by using the Token. While it sounds Secure, It has it cons and this is not developer-friendly.
- Create a Build User in Jenkins
- Create an Authentication token for the Build User created in the preceding step
- Configure Global Security and Project-based Matrix ( If you have Project-based Security)
- Create a Job/Project
- Map user permissions on the job-based security configuration ( If you have project-based Security)
- Create an API token for the job created
- Test the Remote API and trigger the build using Chrome
- Test the Remote API and trigger the build using CURL
- Test the Remote API and trigger the build using Postman
Step1: Create a Build User in Jenkins
Login to Jenkins as Admin User -> Manage Jenkins -> Manage Users -> Create User
Step2: Create an Authentication Token for BuildUser
Login to Jenkins as BuildUser -> Click on the user and Configure
In the configuration page, Go to the API Token Section and Add New Token
Enter Name for the Token AuthToken and click on Generate
Once clicked on the Generate buttion you would be presented with the API token as shown below.
Step3: Configure Global Security and Project-Based Matrix
Logout from the BuildUser and Log back in as Admin user.
Manage Jenkins -> Configure Global Security -> Authorization -> Click on Add User or Group
Step4: Create a JOB/Project to test.
Please refer this article on how to create a Maven Job in Jenkins and Build and Deploy a WAR file to Tomcat.
Jenkins Tomcat Deploy – Deploying Application to Tomcat using Jenkins
Once you have created the Job come back here
Step5: Configure Job-based Security for the same Project
If you have configured the Job-based project matrix security in Jenkins.
You might have to do this step as well and give necessary permissions for BuildUser to be able to execute the build as shown in the following picture.
Job -> Configure -> Enable Project-based security -> Add user or group -> Add the BuildUser
Once you have added the BuildUser select necassary permissions as shown in the following snapshot.
Stay on the same Page to configure the API token
Step6: Configure API token
On the same Job Configuration page, Below the Build Triggers section
Select the Trigger builds remotely and Enter some Authentication Token as shown below.
In my case the Authentication Token is SOMESECURITYTOKEN
as given in the helper text, the Remote API build trigger URL has to be formed as JENKINS_URL/job/TomcatMavenApp-Build/build?token=TOKEN_NAME
Step7: Test the Remote API Build Trigger using the Browser
In my case the Remote Build API URL is http://mwiapp01:8080/job/TomcatMavenApp-Build/build?token=SOMESECURETOKEN
Now you can open a new tab and enter this URL and test the same
You will see the blank page which indicates that the build is executed.
If you go to the other tab where the Jenkins UI tab.
How it worked in chrome without Username and API token ?
If you have noticed we did not pass any Username or API token/Password while triggering the build but the build went fine.
The reason being, we opened a new tab on the same browser session where Jenkins was already open and the cookies available in the browser session has been automatically read and we have not been asked for a password. If you try in
incognitomode. You would see the Login page.
If you try the same URL in incognito browser mode, you would see the login page of Jenkins
Step8: Test the Remote API Build Trigger using CURL
Use the same remote build trigger URL you have used in Step7 and invoke the build using CURL
Here is the CURL command with a Fully Qualified Jenkins Build URL. Refer the preceding Snapshot to understand the various parts of this command.
curl -I -u BuildUser:11aa6524a15c315dff4867eea7b69c9ce2 "http://mwiapp01:8080/job/TomcatMavenApp-Build/build?token=SOMESECURETOKEN"
Here -u represents the user name and password to be passed to invoke the build trigger.
Here HTTP 201 represents a SUCCESS
Step9: Test the Remote API Build Trigger using Postman
In postman, it is very simple and all you have to do is enter the URL and enter the Basic Auth credentials (user, auth token).
Refer the following screenshot for further information
Steps to configure Build Trigger with build token root plugin
In this method we use a plugin named build-token-root it offers an alternate URI pattern which is not subject to the usual job permissions, this URI is accessible to anonymous users as well. Anyone can initiate the build as long as the build token is valid. it supports various URI Patterns like buildWithParameters and buildByToken and polling and accept both GET and POST methods
- Install the Build Authorization Token Root Plugin
- Edit the Job Configuration and Set Remote Build Trigger Token
- Test it.!!
It is that simple with this second approach. You just have to edit the job configuration and create a Token.
Step1: Install the Build Authorization Token Root Plugin
Go to Manage Plugins -> Manage Plugins -> Available tab and search for Build Authorization Token Root plugin and install it.
Step2: Edit the Job Configuration and Set Authentication Token
This is the same task we did on Step6 on the method#1 previously. If you have already done it you can skip it.
Step3: Testing time
There are various types of URLs you can form based on your requirement
Remote trigger the build for Simple Jobs with No Parameters
You can simply invoke them using the following URL structure
https://jenkins.example.com/buildByToken/build?token=Secure-Token&job=TestJob
Unlike the previous method, this URI looks generic where you can pass the token and the job name as a search query
You can pass any job name and its token to invoke that particular job
Remote trigger the build for Parameterized Jobs
Let us suppose that your job is expecting a String parameter named Branch and your job name is TestJob Here is the command you should use to invoke the same
https://jenkins.example.com/buildByToken/buildWithParameters?token=Secure-Token&job=TestJob&Branch=Features/SecurityUpdate
How to know if the build is initiated successfully
When you are making a remote request to this URL, there would not be any response message generated except the HTTP status code 201 indicating it is success
So Always look for the HTTP response code to make sure your build is successful or not.
Here is a Snapshot was taken from Postman logs showing the response code and the request and response headers.
How to schedule the build (or) Delay the build when triggering remote
Either you are using the first method or the second one with the plugin, both of them accepts a query string named delay where you can define, how long Jenkins should wait before initiating the build
Let us take the same job we have initiated above and add some strategical delay to it by adding a delay=<number of seconds> on the URL query string
https://jenkins.example.com/buildByToken/buildWithParameters?token=Secure-Token&delay=300sec&job=TestJob&Branch=Features/SecurityUpdate
After invoking this URL and validating the http 201 response code If you go to the Jenkins UI, you would be able to see the build in pending state like this
you can look at the message pending--in the quite period this represents that the build has been scheduled
Conclusion
Hope this article has helped you to understand how Jenkins remote build triggers are working. How to trigger jobs in Jenkins using URL (or) API token.
If you are looking for any further assistance or professional support. you can contact us at [email protected]
Cheers
Sarav AK
Follow me on Linkedin My Profile Follow DevopsJunction onFacebook orTwitter For more practical videos and tutorials. Subscribe to our channel
Signup for Exclusive "Subscriber-only" Content
