How to trigger a Jenkins build on Git commit

In this page

Overview

Jenkins is a free and open source solution for building, testing, deploying software, and facilitating continuous integration and delivery.

Watch this short tutorial video about configuring Jenkins automations, then follow the step-by-step guides in the next sections:

Starting a Jenkins build after every changeset

This automation starts a Jenkins build when a new changeset is received.

It is the simplest way to integrate Jenkins to your DevOps pipeline. It starts the build once per changeset, after all the commits in the changeset are already in the repository.

Configuration

1. Navigate to your Jenkins user → Configure.
2. Click Add new Token under the API Token section, then click Generate. Copy the generated token, because it cannot be recovered in the future.
3. Click Save.
4. Login to Jira as admin, go to Administration → System → Automation rules.
5. Click Create rule.
6. Select the trigger Changeset accepted (from the DevOps category).
7. Click Save.
8. Click New action.
9. Select the action Send web request.
   1. Enter the Webhook URL as:

      <YOUR_JENKINS_SERVER_BASE_URL>/job/<YOUR_JENKINS_JOB_NAME>/build

      Replace the placeholders with your actual Jenkins base URL and the job name to start.
   2. Add a header with the name "Authorization" and with the value of the Basic Access Authentication credentials. The credentials are generated from your Jenkins username and your API Token (created in step 2) which acts as a password here.
      Notes:
      1. The full header value looks something like "Basic YWRtaW46YWRtaW4=".
      2. Don't forget to put "Basic" to the start!
      3. If you don't know how to generate the second part, use this safe online form. Just enter the username and the password in the format "myusername:mypassword" (separated with ":"), click Base64 Encode, then copy the resulted string back to the action's configuration. (The form runs fully in your browser, it does not store or transmit anything, therefore it is safe to use.)
   3. Choose POST as HTTP method.
   4. Validate your settings in the Validate your webhook configuration section below. It will start a build if the configuration is valid.
      Tip: if the URL contains smart values (variables), replace those with actual values (constants) for the time of the validation, then revert to the smart values after the configuration was successfully validated.
10. Click Save.
11. Name your automation rule intuitively, and click Turn it on.

Usage

1. Create a commit with this commit message:

   Fix the FOO-1 bug.

2. The Jenkins build will be started.

Troubleshooting

If you don't get the expected results:

1. See the general troubleshooting steps.

Starting a Jenkins build with a specific command

This automation starts a Jenkins build when the changeset includes a commit with a commit message that contains a certain command.

It is a more flexible variant of the previous automation, because you can control whether to start the build or not.

Configuration

1. Navigate to your Jenkins user → Configure.
2. Click Add new Token under the API Token section, then click Generate. Copy the generated token, because it cannot be recovered in the future.
3. Click Save.
4. Login to Jira as admin, go to Administration → System → Automation rules.
5. Click Create rule.
6. Select the trigger Genius Commit created (from the DevOps category).
7. Choose the command Build, and click Save.
8. Click New action.
9. Select the action Send web request.
   1. Enter the Webhook URL as:

      <YOUR_JENKINS_SERVER_BASE_URL>/job/<YOUR_JENKINS_JOB_NAME>/build

      Replace the placeholders with your actual Jenkins base URL and the job name to start.
   2. Add a header with the name "Authorization" and with the value of the Basic Access Authentication credentials. The credentials are generated from your Jenkins username and your API Token (created in step 2) which acts as a password here.
      Notes:
      1. The full header value looks something like "Basic YWRtaW46YWRtaW4=".
      2. Don't forget to put "Basic" to the start!
      3. If you don't know how to generate the second part, use this safe online form. Just enter the username and the password in the format "myusername:mypassword" (separated with ":"), click Base64 Encode, then copy the resulted string back to the action's configuration. (The form runs fully in your browser, it does not store or transmit anything, therefore it is safe to use.)
   3. Choose POST as HTTP method.
   4. Validate your settings in the Validate your webhook configuration section below. It will start a build if the configuration is valid.
      Tip: if the URL contains smart values (variables), replace those with actual values (constants) for the time of the validation, then revert to the smart values after the configuration was successfully validated.
10. Click Save.
11. Name your automation rule intuitively, and click Turn it on.

Usage

1. Create a commit with this commit message:

   Fix the FOO-1 bug. @build

2. The Jenkins build will be started.

Troubleshooting

If you don't get the expected results:

1. Check if the @build command is defined in the Genius Commands screen? (It's a default command.)
2. Check if the @build command was included in the commit message?
3. See the general troubleshooting steps.

Starting a Jenkins build with a specific command and job name

This automation starts a Jenkins build by parsing the job name from the VCS commit message:

It is a more flexible variant of the previous automation that allows choosing the job.

Configuration

In this example, the parameter "jobName" will be parsed from the commit message and passed to the build.

For this, first implement the "parameterless" automation using the previous guide. Then, execute these additional steps for the parameter:

1. Login to Jira as admin, go to Commits → Genius Commands.
2. Edit the command named Build.
3. Enter the following regular expression as a parameter pattern: (?<jobName>.*).
4. Click Save.
5. Navigate to Administration → System → Automation rules.
6. Select your rule and edit the Send web request action.
7. Modify the Webhook URL as:

   <YOUR_JENKINS_SERVER_BASE_URL>/job/{{devops.jobName.urlEncode}}/build

   Note that the command parameters should be URL-encoded with .urlEncode. Learn more about customizing the request in the Jenkins REST API documentation.
8. Click Save, then Publish changes.

Usage

1. Create a commit with this commit message:

   Fix the FOO-1 bug. @build LRT

2. The Jenkins job with the name "LRT" will be started.

Troubleshooting

If you don't get the expected results:

1. Check if the @build command is defined in the Genius Commands screen? (It's a default command.)
2. Check if the @build command followed by the parameter was included in the commit message?
3. See the general troubleshooting steps.

Starting a Jenkins build with a specific command and job parameter

This automation starts a Jenkins build by parsing the job parameter from the VCS commit message.

It is a more flexible variant of the previous automation that allows passing a job parameter.

Configuration

In this example, the parameter "jobParameter" will be parsed from the commit message and passed to the build.

For this, first implement the "parameterless" automation using the previous guide. Then, execute these additional steps for the parameter:

1. Login to Jenkins as admin, go to your job → Configure → General.
2. Select the This project is parameterized checkbox.
3. Click Add parameter → String Parameter.
4. Enter "profile" in the Name field and set a default value if need (e.g. "production").
5. Click Save.
6. Login to Jira as admin, go to Commits → Genius Commands.
7. Edit the command named Build.
8. Enter the following regular expression as a parameter pattern: (?<jobParameter>.*).
9. Click Save.
10. Navigate to Administration → System → Automation rules.
11. Select your rule and edit the Send web request action.
12. Modify the Webhook URL as:

    <YOUR_JENKINS_SERVER_BASE_URL>/job/<YOUR_JENKINS_JOB_NAME>/buildWithParameters?profile={{devops.jobParameter.urlEncode}}

    Note that the command parameters shoud be URL-encoded with .urlEncode. Learn more about customizing the request in the Jenkins REST API documentation.
13. Click Save, then Publish changes.

Usage

1. Create a commit with this commit message:

   Fix the FOO-1 bug. @build production

2. The Jenkins build will be started with the "profile" parameter set to "production".

Troubleshooting

If you don't get the expected results:

1. Check if the @build command is defined in the Genius Commands screen? (It's a default command.)
2. Check if the @build command followed by the parameter was included in the commit message?
3. See the general troubleshooting steps.

Questions?

Ask us any time.