How to build a parameterized jenkins pipeline remotely

Here in this article will see how we can remotely trigger a parameterized jenkins pipeline build. We will be creating a very basic pipeline in jenkins which accepts parameters and try to trigger it using the authentication token and the user credentials who has access to this pipeline job. We will working with a read only access user who can only view the jobs from the jenkins portal.

Table of Contents

Test Environment

Fedora 37 workstation
Jenkins LTS

If you are interested in watching the video. Here is the YouTube video on the same step by step procedure outlined below.

Procedure

Step1: Ensure Docker and Docker Compose installed and running

As a first step ensure that you have docker and docker compose installed and running as shown below. Please follow the offical documentation from Docker to install these components.

[admin@fedser jenkins-docker]$ docker -v
Docker version 23.0.4, build f480fb1

[admin@fedser jenkins-docker]$ docker-compose -v
docker-compose version 1.29.2, build 5becea4c

[admin@fedser jenkins-docker]$ sudo systemctl start docker.service

Step2: Ensure Jenkins Docker service running

Here we are going to use the following docker-compose file with volume mounts for jenkins_home for data persistence.

[admin@fedser jenkins-docker]$ cat docker-compose.yml 
version: "3"
services:

  jenkins:
    image: jenkins/jenkins:lts
    privileged: true
    user: root
    ports:
      - "8082:8080"
      - "2224:2224"
    volumes:
      - /apps/jenkins/user:/var/jenkins_home
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - jenkins2-net

networks:
  jenkins2-net:

Let’s start our jenkins service and access it using the URL provided below. Please change the FQDN of the URL to your Host FQDN or localhost as per your convinence.

[admin@fedser jenkins-docker]$ docker-compose up -d

URL – http://fedser.stack.com:8082/login?from=%2F

Step3: Create User with API token

Go to Manage Jenkins – Manage Users and Create User. Here we will create an user with the following details.

username - dev1
password - dev1

Once the user is created you can go into the user settings and create an API Token for this specific user. API tokens offer a way to make authenticated CLI or REST API calls. The username associated with each token is your Jenkins username.

User API Token
Name - dev1api  
Value: 11749f72f2005bdd2fac11138ebdbc8090

Step4: Configure Global security

Go to Manage Jenkins – Configure Global Security and update the Authorization to be carried out based on “Matrix Based Security”. Use Add user or group to add our user “dev1” and provide him with overall read access and job read access as shown in below screenshot and save the changes.

Now if you login with dev1 user you will only be able to view the jobs, but cannot build them and you also cannot create any new jenkins job using the portal as shown below.

Step5: Create a Jenkins Parameterized build Pipeline

Here let us create a new pipeline from jenkins portal and name it “pytthonpipeline” and in the pipeline definition select Pipeline script and copy the below script.
We need to carry out this step using the admin user who has full privileges on the Jenkins service.

pipeline {
    agent any 
    stages {
        stage('Stop Application') { 
            steps {
                echo "Stop Application : $application"
            }
        }
        stage('Reset Secrets') { 
            steps {
                echo "Reset Secrets" 
            }
        }
        stage('Test Connection') { 
            steps {
                echo "Test Connection" 
            }
        }
        stage('Redeploy Application') { 
            steps {
                echo "Redeploy Application" 
            }
        }
    }
}

Also enable the checkbox “Trigger builds remotely” from Build Triggers section. Once you enable this checkbox it will ask to provide the “Authentication Token”.

Let’s generate a random token of 16 characters as shown below and use it in the Authentication token field and save the pipeline.

>>> import random
>>> ''.join(random.choice('0123456789ABCDEF') for i in range(16))
'70F5D2D156F6314C'

Any user who has read access to this jenkins pipeline and with the valid authentication token would be able to build the pipeline by triggering it remotely.

Step6: Trigger Pipeline remotely using curl

The Jenkins URL that we can use to trigger the parameterized build is as follows “JENKINS_URL/job/pytthonpipeline/buildWithParameters?token=TOKEN_NAME”. Let me update it with my Jenkins instance URL and token value and the actual URL will be as follows in my case.

URL – http://fedser.stack.com:8082/job/pytthonpipeline/buildWithParameters?token=70F5D2D156F6314C

Now let’s try to trigger our parameterized build using curl utility as shown below.

[admin@fedser jenkins-docker]$ curl -u dev1:11749f72f2005bdd2fac11138ebdbc8090 http://fedser.stack.com:8082/job/pytthonpipeline/buildWithParameters?token=70F5D2D156F6314C --data application=nodejs

NOTE: CSRF protection uses a token (called crumb in Jenkins) that is created by Jenkins and sent to the user. Any form submissions or similar action resulting in modifications, like triggering builds or changing configuration, requires that the crumb be provided.

If you authenticate with a username and a user API token then a crumb is not needed from Jenkins 2.96 weekly/2.107 LTS. For more information please refer to CSRF crumb no longer required when authenticating using API token or JENKINS-22474.

Now you can see from the above screenshot that the pipeline has been triggered. You can also check the console log for this pipeline which provides us with the information on the remote host that triggered this pipeline as shown below.

Started by remote host 192.168.29.117
Running in Durability level: MAX_SURVIVABILITY
[Pipeline] Start of Pipeline
[Pipeline] node
Running on Jenkins in /var/jenkins_home/workspace/pytthonpipeline
[Pipeline] {
[Pipeline] stage
[Pipeline] { (Stop Application)
[Pipeline] echo (hide)
Stop Application : nodejs
[Pipeline] }
[Pipeline] // stage
[Pipeline] stage
[Pipeline] { (Reset Secrets)
[Pipeline] echo
Reset Secrets
[Pipeline] }
[Pipeline] // stage
[Pipeline] stage
[Pipeline] { (Test Connection)
[Pipeline] echo
Test Connection
[Pipeline] }
[Pipeline] // stage
[Pipeline] stage
[Pipeline] { (Redeploy Application)
[Pipeline] echo
Redeploy Application
[Pipeline] }
[Pipeline] // stage
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
Finished: SUCCESS

Here we have seen how we can provide a remote jenkins build access a user who does not having the build access to that pipeline with the help of Authorization Token. Any user who has read access to the job and has the Authorization token for that pipeline will be able to trigger that pipeline remotely.

Hope you enjoyed reading this article. Thank you..

How to build a parameterized jenkins pipeline remotely