Mastering Jenkins Automation: Create, Update, Delete, and Trigger Jobs with API

We use Jenkins in our daily processes for automating builds, integrations, deployments and maintenance. Being an open source tool with strong community support, powerful plugin system Jenkins has edge over other CI tools.

There are multiple ways in which you can use Jenkins pipeline/job to ease your day to day processes or create automations. We use Jenkins for:

• Automated builds in integration with gitlab
• Automated VM deployment in integration with Ansible
• Automated artifacts validation, release and publish on JFrog
• Automated application deployment
• To get daily Server status report
• And list continues.

In most of the cases we need some automation over Jenkins, where multiple actions needs to be triggered via Jenkins. Every time we cannot go and run Jenkins pipeline through UI or create hundreds of pipeline manually, for this we need some mechanism to communicate with Jenkins.

Jenkins provide REST API to communicate with it through remote or external systems. We can use API to create, update, delete, trigger pipeline as well as configure Jenkins instance.

Create API token

Jenkins API uses basic authentication mechanism, it is better to create separate user and use access token for API access. User can obtain API token from personal configuration page which is accessible on $JENKINS_URL/me/configure

Jenkins minimal installation on Kubernetes

We can install Jenkins in different ways but sometimes we just need Jenkins with minimal resources and configuration.

bootvarSuhas Adhav

Create Pipeline using API

Jenkins support creation API for which you need to pass xml file for the job structure which you want to create. You can follow below steps to obtain xml file and create the pipeline:

• Create pipeline manually in Jenkins UI and test it
• Export your pipeline using export import plugin or Jenkins jar to xml file or extract it from ${JENKINS_URL}/job/JOB_NAME/config.xml
• Now use this xml file as a reference and create pipeline through API
• Use below curl request to create pipeline

# JENKINS_USER_API_TOKEN is obtained from $JENKINS_URL/me/configure
BASIC_AUTH=${JENKINS_USER}:$JENKINS_USER_API_TOKEN

# Obtained from URL without any protocol
JENKINS_ADDRESS="<jenkins_host>:<port>"

# Curl will create pipeline with name my_pipeline with config from file config.xml
# config.xml - file needs to be exported from existing job
curl -X POST http://${BASIC_AUTH}@${JENKINS_ADDRESS}/createItem?name=my_pipeline \
    --header "Content-Type:text/xml" \
    --data-binary @config.xml

Curl request will return status 200 if pipeline is successfully created otherwise it will return 400 if pipeline is already created or failed to create due to some error

How to create Jenkins pipeline to run on Kubernetes?

In containerization world we run Jenkins pipeline on Kubernetes platform as a pod instead of running it on legacy nodes.

bootvarSuhas Adhav

Update pipeline using API

Updating pipeline is nothing but updating config.xml for that job.

# Update job config.xml   
curl -X POST http://${BASIC_AUTH}@${JENKINS_ADDRESS}/job/my_pipeline/config.xml \
                  --header "Content-Type:text/xml" \
                  --data-binary @new_config.xml

Above curl request will return 200 if pipeline is updated successfully otherwise it will have status code greater than 400 in case of error.

Note the URL in update request it has config.xml in path.

Delete Pipeline using API

Deletion of pipeline/job is also a POST request with doDelete action specified in the request.

# Delete pipeline using doDelete pipeline
curl -X POST http://${BASIC_AUTH}@${JENKINS_ADDRESS}/job/my_pipeline/doDelete

Above curl request will return 200 if job is deleted successfully in case of failure it should return status code greater than 400.

Trigger Pipeline using API

This is the most common case of using API to automate job trigger with parameters. Use below curl to trigger pipeline/job via curl request.

# Pass parameters with --data option
curl http://${BASIC_AUTH}@${JENKINS_ADDRESS}/job/my_pipeline/buildWithParameters \
  --data param1=123 --data param2="git-repo"

To achieve the same functionality offered by Jenkins' built-in REST API, various wrappers are available in popular programming languages like Python, Ruby, and Java. Among these options, we highly recommend the Python wrapper, python-jenkins. It boasts frequent updates and provides a wealth of user-friendly functions written in Python for seamless Jenkins integration.

More documentation over API can be found here.