[SOLVED] How can I trigger Jenkins builds remotely and pass parameters? - jenkins

[SOLVED] How to Remotely Trigger Jenkins Builds and Pass Parameters Effectively

In this article, we will look at simple ways to trigger Jenkins builds from far away and pass parameters easily. Knowing how to run Jenkins jobs from different places is important for making our Continuous Integration/Continuous Deployment (CI/CD) pipeline better. We will share useful solutions that improve our Jenkins work. This way, we can manage our builds well without doing everything by hand.

Here is a short overview of what we will talk about:

• Part 1 - Using Jenkins Remote Access API: We will learn how to use Jenkins’s built-in API to trigger builds from a distance.
• Part 2 - Configuring Jenkins Job for Parameterized Builds: We will find out how to make our Jenkins jobs accept parameters.
• Part 3 - Triggering Builds with HTTP Requests: We will understand how to use HTTP requests to trigger our Jenkins jobs.
• Part 4 - Using Jenkins CLI for Remote Builds: We will explore the command-line tool for triggering builds from our terminal.
• Part 5 - Integrating with Webhooks for Automated Triggers: We will learn how to set up webhooks to automatically trigger builds when certain events happen.
• Part 6 - Authenticating Remote Build Triggers: We will make sure our remote build triggers are safe by using authentication methods.
• Frequently Asked Questions: We will answer common questions about triggering builds remotely in Jenkins.

By the end of this chapter, we will know how to trigger Jenkins builds from far away and pass parameters. This will make our automation work much better. If we want to improve our Jenkins setup even more, we can check our guides on how to archive artifacts in Jenkins and how to fix Jenkins CI pipeline issues.

Part 1 - Using Jenkins Remote Access API

We can trigger Jenkins builds from remote places using the Jenkins Remote Access API. Here are the steps to do that:

1. Jenkins URL Format: We should use this URL pattern to start a job:

   http://<jenkins-url>/job/<job-name>/buildWithParameters?param1=value1&param2=value2

2. Authentication: If our Jenkins needs a login, we have to add the username and API token in the request. We can use basic authentication or send the token as a parameter:

   • Basic Authentication:

     curl -u <username>:<api-token> "http://<jenkins-url>/job/<job-name>/buildWithParameters?param1=value1"

   • Token as Parameter:

     http://<jenkins-url>/job/<job-name>/buildWithParameters?token=<your-token>&param1=value1

3. Example Request:

   curl -X POST -u admin:your-api-token "http://localhost:8080/job/my-job/buildWithParameters?PARAM1=value1&PARAM2=value2"

4. Enable Remote Access: We need to check that the Jenkins job is set to allow remote access. We do this by turning on the “Trigger builds remotely” option in the job settings. We also need to give a token for login.

5. Access Control: We must make sure that our Jenkins security settings allow remote API access. We can set this up under “Manage Jenkins” > “Configure Global Security”.

6. Further Reading: For more details on using the Jenkins API, we can look at the official Jenkins documentation. This can help us learn more about other API features.

By following these steps, we can use the Jenkins Remote Access API to start our builds with parameters. This can make our CI/CD process better. For more help with Jenkins automation, we can also check how to set up Jenkins CI.

Part 2 - Configuring Jenkins Job for Parameterized Builds

We need to set up our Jenkins job for parameterized builds. This lets us trigger Jenkins builds from outside and send parameters. Here is how we can do it:

1. Open Your Jenkins Job:

   • First, go to the Jenkins dashboard. Then, choose the job we want to set up.

2. Enable Parameterization:

   • Click on “Configure”.
   • Scroll down to the “General” section.
   • Check the box for “This project is parameterized”.

3. Add Parameters:

   • Click on “Add Parameter” and pick the type of parameter we want. Some common types are:
     • String Parameter: For a single line of text.
     • Boolean Parameter: For true or false choices.
     • Choice Parameter: For a list of options.

4. Configure Parameter Details:

   • For a String Parameter, we need to give it a name and a default value.
   • For a Choice Parameter, we list the options and separate them by a newline.

5. Save Configuration:

   • After we add all the needed parameters, we click “Save” at the bottom of the page.

To trigger this parameterized build from outside, we use the Jenkins Remote Access API or send an HTTP request with the needed parameters.

Example of Triggering a Parameterized Build via URL:

We can trigger the build using a URL that looks like this:

http://<JENKINS_URL>/job/<JOB_NAME>/buildWithParameters?PARAM1=value1&PARAM2=value2

We need to replace <JENKINS_URL>, <JOB_NAME>, PARAM1, and PARAM2 with our Jenkins URL, job name, and the names and values of our parameters.

For example:

http://localhost:8080/job/MyJob/buildWithParameters?BRANCH=main&DEPLOY=true

By setting up parameterized builds in Jenkins, we can easily start builds from outside with specific parameters. This makes our CI/CD pipeline better. For more details on Jenkins setup, we can check this guide.

Part 3 - Triggering Builds with HTTP Requests

We can trigger Jenkins builds from far away using HTTP requests. We use Jenkins’ REST API for this. This way, we can start a job and send parameters through a URL.

Triggering a Build

1. HTTP POST Request: We use this format to trigger a Jenkins job:

   POST http://<jenkins-url>/job/<job-name>/buildWithParameters

   Here, we change <jenkins-url> with our Jenkins server URL and <job-name> with our job name.

2. Passing Parameters: If our job needs parameters, we add them to the URL as query parameters. For example:

   POST http://<jenkins-url>/job/<job-name>/buildWithParameters?PARAM1=value1&PARAM2=value2

3. Example Using cURL:

   curl -X POST "http://<jenkins-url>/job/<job-name>/buildWithParameters?PARAM1=value1&PARAM2=value2" \
   --user "username:api_token"

   • username: This is our Jenkins username.
   • api_token: This is our Jenkins API token to log in safely.

Authentication

We must check that our Jenkins instance lets remote access. We need to use an API token for authentication to keep things safe. We can read more in Authenticating Remote Build Triggers.

Additional Tips

• Check that the job we are triggering is set up to take parameters.

• We can also trigger builds without parameters using this URL:

  POST http://<jenkins-url>/job/<job-name>/build

By using HTTP requests to trigger Jenkins builds from far away, we can easily connect Jenkins with many CI/CD tools. This helps us automate our workflows. For more information on Jenkins settings, we can look at Configuring Jenkins Job for Parameterized Builds.

Part 4 - Using Jenkins CLI for Remote Builds

To start Jenkins builds from a distance with the Jenkins Command Line Interface (CLI), we can follow these steps:

1. Install Jenkins CLI: We need to download the jenkins-cli.jar file from our Jenkins server. You can usually find it at:

   http://<your-jenkins-url>/jnlpJars/jenkins-cli.jar

2. Use the CLI Command: Next, we open our terminal and run this command to start a build. Make sure to change <job-name> to your Jenkins job name and <parameters> to your build parameters.

   java -jar jenkins-cli.jar -s http://<your-jenkins-url> build <job-name> -p <parameters>

   For example:

   java -jar jenkins-cli.jar -s http://localhost:8080 build my-job -p param1=value1 -p param2=value2

3. Authentication: If our Jenkins server needs authentication, we can add the -auth flag:

   java -jar jenkins-cli.jar -s http://<your-jenkins-url> -auth <username>:<api-token> build <job-name> -p <parameters>

4. Accessing Jenkins CLI: We should check if our Jenkins server allows CLI access. Sometimes we need to set up the Jenkins CLI in the Jenkins settings.

For more details, we can look at the Jenkins CLI documentation.

By using the Jenkins CLI, we can easily start builds from far away and send needed parameters right from our command line. This helps us manage our CI/CD pipeline better. For more related settings, we can read this article on how to fix Jenkins CI pipeline.

Part 5 - Integrating with Webhooks for Automated Triggers

We can trigger Jenkins builds from far away using webhooks. To do this, we configure our Jenkins job to listen for incoming HTTP POST requests from outside services. These services can be GitHub, Bitbucket, or GitLab. This setup helps us to build automatically when we push changes to our code.

Step 1: Configure Jenkins Job

1. First, we open our Jenkins dashboard. Then we select the job we want to trigger.
2. Next, we click on Configure.
3. We scroll down to Build Triggers.
4. We check the box for Trigger builds remotely (e.g., from scripts).
5. We set an authentication token in the Authentication Token field. For example, we can use my_token.

Step 2: Set Up Webhook in Your Repository

Let’s say we want to set up a webhook in GitHub:

1. We go to our GitHub repository.

2. We click on Settings > Webhooks > Add webhook.

3. We set the Payload URL to:

   http://<your-jenkins-url>/job/<job-name>/build?token=my_token

4. We choose application/json as the content type.

5. We select the events we want to trigger the webhook. For example, we can choose Just the push event.

6. Finally, we click Add webhook.

Step 3: Test the Webhook

To check if everything works:

1. We make a change in our repository and push it.
2. Then, we check the Jenkins job to see if it was triggered.

Example Webhook Payload (for GitHub)

If we want to send parameters using the webhook, we can include them in the URL:

http://<your-jenkins-url>/job/<job-name>/buildWithParameters?token=my_token&param1=value1&param2=value2

This gives us more options for our Jenkins builds. It helps us work better with our CI/CD workflows. For more advanced setups and help, we can look at Jenkins Remote Access API and other articles.

Part 6 - Authenticating Remote Build Triggers

To trigger Jenkins builds from far away and send parameters safely, we need to use authentication. Jenkins has different ways to make sure only the right users can start build jobs. Here are the main ways we can authenticate remote build triggers:

1. Using API Token:

   • Each Jenkins user can make an API token from their user settings page. We use this token instead of a password when we make HTTP requests.

   • To make an API token:

     • Go to your Jenkins user profile.
     • Click on “Configure” and then “Add new token”.

   • Use the token in your HTTP request:

     curl -X POST "http://<jenkins-server>/job/<job-name>/buildWithParameters?param1=value1&param2=value2" \
     --user "<username>:<api-token>"

2. Basic Authentication:

   • We can also use the basic authentication feature built in Jenkins. This needs the username and password of a Jenkins user who is allowed.

   • Example of starting a build using curl:

     curl -X POST "http://<jenkins-server>/job/<job-name>/buildWithParameters?param1=value1&param2=value2" \
     --user "<username>:<password>"

3. Using Jenkins Crumb Issuer:

   • If CSRF protection is on, we have to add a crumb to our requests.

   • First, we get the crumb:

     CRUMB=$(curl -s -u "<username>:<api-token>" "http://<jenkins-server>/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,\":\",//crumb)")

   • Then we use the crumb when we make the request:

     curl -X POST "http://<jenkins-server>/job/<job-name>/buildWithParameters?param1=value1&param2=value2" \
     -H "$CRUMB" \
     --user "<username>:<api-token>"

4. Using SSH for Jenkins CLI:

   • If we like to use the Jenkins CLI, we must make sure our Jenkins server allows SSH access. We can use SSH keys to authenticate.

   • Example command:

     java -jar jenkins-cli.jar -s http://<jenkins-server> -auth <username>:<api-token> build <job-name> -p param1=value1 -p param2=value2

For more help and fixing issues about Jenkins authentication, we can check these links: How to Fix Jenkins Host Key and How to Fix Missing Certificates.

Frequently Asked Questions

1. How do we trigger Jenkins builds remotely?

We can trigger Jenkins builds remotely by using the Jenkins Remote Access API. This helps us send HTTP requests to our Jenkins server. We specify the job and any parameters we want to use. For more details, we can look at our guide on triggering Jenkins builds remotely.

2. What are parameterized builds in Jenkins?

Parameterized builds in Jenkins let us pass parameters to our jobs. This helps us create builds that change based on different input values. We can set up our Jenkins job to accept these parameters and use them during our build process. For more info on this, we can visit our article on configuring Jenkins jobs for parameterized builds.

3. Can we trigger Jenkins builds with webhooks?

Yes, we can connect Jenkins with webhooks to automate build triggers. By setting up a webhook in our version control system, we can trigger Jenkins jobs automatically when we push code. For a detailed guide on this setup, we can check our section on integrating with webhooks for automated triggers.

4. How do we authenticate remote build triggers in Jenkins?

Authenticating remote build triggers in Jenkins is very important for security. We can use API tokens or Jenkins user credentials to confirm our requests. It is important to make sure we have the right permissions for the user. For a full guide on authentication, we can see our article on authenticating remote build triggers.

5. What are common errors when triggering Jenkins builds remotely?

Some common errors when we trigger Jenkins builds remotely are authentication failures, wrong job names, and missing parameters. To fix these issues, we should check if we are using the API correctly and if our Jenkins instance is reachable. For more troubleshooting tips, we can look at our resource on fixing common Jenkins issues.