Trigger a Jenkins Job Using cURL: A Step-by-Step Guide

Jenkins is one of the most popular tools in DevOps, enabling Continuous Integration and Continuous Deployment (CI/CD) pipelines. In this blog post, we’ll explore how to trigger a Jenkins job remotely using the cURL command. By automating job execution through an API call, teams can seamlessly integrate Jenkins jobs with other tools, scripts, or workflows.

If you’re looking to automate Jenkins job triggers with cURL, you’re in the right place!

You can use “sh” command in the Jenkins declarative Pipeline Stage and get the jobs triggered from that stage

Why Use cURL to Trigger Jenkins Jobs?

Triggering Jenkins jobs via cURL provides several benefits:

1. Automation: Allows you to integrate Jenkins job execution into other scripts or workflows.
2. Simplicity: A single HTTP POST request is all it takes to trigger a build.
3. Flexibility: You can pass parameters (or skip them) depending on your needs.
4. Remote Control: Enables running Jenkins jobs without manually accessing the Jenkins UI.

This approach is especially useful for integrating Jenkins jobs with other tools like Git, CI/CD pipelines, or custom dashboards.

Prerequisites

Before you start, ensure you have the following:

1. Jenkins API Token:
   • Go to your Jenkins profile.
   • Navigate to Configure > API Token.
   • Generate and copy the API token.
2. User Permissions: Ensure the Jenkins user has permissions to trigger jobs.
3. Jenkins URL: The URL where Jenkins is hosted (e.g., http://localhost:8080).
4. Job Token: The token configured for the Jenkins job (used for security).
5. cURL Installed: Verify that cURL is installed by running curl --version.

The cURL Command to Trigger a Jenkins Job

Here’s the cURL command to trigger a Jenkins job without parameters:

sh "curl -v -k --user admin:${JENKINS_API_TOKEN} -X POST \
     -H 'cache-control: no-cache' -H 'content-type: application/x-www-form-urlencoded' \
     'http://localhost:8080/job/DevOpsstatus/buildWithParameters?token=gitops-token'"

Breakdown of the Command:

1. curl -v -k:
   • -v for verbose output to debug.
   • -k allows insecure SSL connections (useful for self-signed certificates).
2. --user admin:${JENKINS_API_TOKEN}:
   • Authenticate using the Jenkins username (admin) and the API token.
3. -X POST:
   • Specifies an HTTP POST request.
4. Headers:
   • cache-control: no-cache prevents cached responses.
   • content-type: application/x-www-form-urlencoded sets the proper content type.
5. URL:
   • Replace http://localhost:8080 with your Jenkins host.
   • Update DevOpsstatus to the name of your Jenkins job which you want to trigger.
   • The query parameter token=gitops-token ensures the job trigger is secure (create a token in the configuration of your pipeline/Job).

Step-by-Step Guide to Triggering the Job

Follow these steps to execute the command:

1. Open a Terminal or Command Line.
2. Replace the placeholders in the command:
   • admin: Your Jenkins username.
   • ${JENKINS_API_TOKEN}: Your Jenkins API token.
   • http://localhost:8080: Your Jenkins URL.
   • DevOpsstatus: The Jenkins job name.
   • gitops-token: The job token configured in Jenkins.
3. Run the Command

curl -v -k --user admin:YOUR_API_TOKEN -X POST \
     'http://localhost:8080/job/DevOpsstatus/buildWithParameters?token=gitops-token'

Check the terminal output for confirmation:

• HTTP 201 Created indicates the job was successfully triggered.
• Any errors will be displayed in the verbose output.

Troubleshooting Common Issues

If the command doesn’t work as expected, check the following:

1. Authentication Failure: Ensure the API token is correct and not expired.
2. Job Token Mismatch: Verify that the gitops-token matches the token configured in the job.
3. Incorrect URL: Confirm the Jenkins host and job name are correct.
4. Permissions Issue: Make sure the user has the necessary permissions to build the job.
5. SSL Error: If you’re using HTTPS with self-signed certificates, add the -k flag.