How to trigger Jenkins builds remotely and to pass parameters
Categories:
Triggering Jenkins Builds Remotely with Parameters
Learn how to initiate Jenkins builds from external systems and pass custom parameters to automate your CI/CD pipelines effectively.
Jenkins is a powerful automation server widely used for Continuous Integration and Continuous Delivery (CI/CD). A common requirement in complex CI/CD workflows is the ability to trigger Jenkins jobs remotely from other applications, scripts, or version control systems, and to pass specific parameters to customize the build process. This article will guide you through the methods to achieve this, ensuring your automation ecosystem is seamlessly integrated.
Enabling Remote Build Triggers
Before you can trigger a Jenkins job remotely, you need to configure the job to accept remote triggers. This involves enabling a specific option within the job's configuration and optionally setting an authentication token for security. The token acts as a shared secret, ensuring that only authorized requests can initiate a build.
1. Navigate to Job Configuration
Open your Jenkins dashboard, select the job you wish to configure, and click 'Configure' from the left-hand menu.
2. Enable Remote Trigger
In the job configuration page, scroll down to the 'Build Triggers' section. Check the box next to 'Trigger builds remotely (e.g., from scripts)'. A field for an 'Authentication Token' will appear.
3. Set Authentication Token
Enter a strong, unique token in the 'Authentication Token' field. This token will be part of the URL used to trigger the build. Remember this token, as it's crucial for successful remote triggers. Save your changes.
Triggering Builds with cURL
The most common way to trigger a Jenkins build remotely is by sending an HTTP POST request to a specific URL. The curl command-line tool is ideal for this purpose. You can include the authentication token directly in the URL.
curl -X POST JENKINS_URL/job/JOB_NAME/build?token=AUTH_TOKEN
Basic cURL command to trigger a Jenkins build
Passing Parameters to Remote Builds
Many Jenkins jobs are parameterized, meaning they accept input values that influence the build process. To pass parameters when triggering a build remotely, you need to use the /buildWithParameters endpoint instead of /build. Parameters are appended to the URL as query string parameters.
flowchart TD
A[External System] --> B{HTTP POST Request}
B --> C["Jenkins URL/job/JOB_NAME/buildWithParameters?token=AUTH_TOKEN&PARAM1=VALUE1&PARAM2=VALUE2"]
C --> D[Jenkins Job Triggered]
D --> E[Parameters Injected]
E --> F[Build Execution]Flow of triggering a parameterized Jenkins build remotely
curl -X POST JENKINS_URL/job/JOB_NAME/buildWithParameters?token=AUTH_TOKEN&BRANCH=main&ENVIRONMENT=staging
cURL command to trigger a Jenkins build with parameters
BRANCH, ENVIRONMENT) are defined as 'String Parameter' or other suitable parameter types within your Jenkins job configuration. Otherwise, Jenkins will ignore them.Using Jenkins API Token for Authentication
While the job-specific authentication token is simple, a more robust and secure method for remote triggering, especially when dealing with multiple jobs or more complex integrations, is to use a Jenkins user's API token. This token is generated per user and provides authentication for all jobs that the user has permission to trigger.
1. Generate API Token
Log in to Jenkins, click on your username in the top right corner, then click 'Configure'. In the 'API Token' section, click 'Add new Token' and then 'Generate'. Copy the generated token immediately, as it will not be shown again.
2. Trigger with API Token
Use the API token with basic authentication in your cURL request. Replace JENKINS_USER with your Jenkins username and API_TOKEN with the token you generated.
curl -X POST -u JENKINS_USER:API_TOKEN JENKINS_URL/job/JOB_NAME/buildWithParameters?BRANCH=dev
cURL command using Jenkins user API token for authentication
token=AUTH_TOKEN query parameter in the URL, as authentication is handled via the HTTP Basic Auth header.