Configuring Build Triggers in Jenkins: GitHub Webhooks and Schedule-Based Builds

One of the core features of Jenkins is its ability to automatically trigger builds in response to various events, such as code changes, time schedules, or external systems. These automatic triggers help streamline Continuous Integration (CI) workflows, ensuring that code is tested and deployed without requiring manual intervention.

In this guide, we will dive into the most common ways to configure build triggers in Jenkins, focusing on two key mechanisms: GitHub Webhooks and schedule-based (cron-style) builds.

1. What are Build Triggers in Jenkins?

In Jenkins, a build trigger is a mechanism that automatically starts a build process based on certain predefined conditions or events. Build triggers help automate the CI process by reducing manual effort and ensuring that the pipeline runs when necessary. Some common ways to trigger a Jenkins build include:

• Source Code Changes: Automatically triggering builds when new code is pushed to a repository (e.g., via GitHub webhooks).
• Scheduled Builds: Setting up builds to run periodically at specific times or intervals.
• Polling SCM: Jenkins periodically checks for changes in the source code repository and triggers a build if changes are detected.
• Upstream Projects: A build can be triggered when a dependent (upstream) project is built.

In this post, we’ll focus on GitHub webhooks and schedule-based builds, two of the most common build trigger mechanisms in Jenkins.

2. Configuring GitHub Webhooks to Trigger Jenkins Builds

One of the most powerful and efficient ways to trigger Jenkins builds is through GitHub Webhooks. Webhooks allow Jenkins to react instantly when code is pushed to a GitHub repository without the need for polling, making them much more efficient than SCM polling.

2.1 Step 1: Install the GitHub Plugin in Jenkins

Before configuring GitHub webhooks, ensure that the GitHub Integration Plugin is installed in your Jenkins instance. This plugin allows Jenkins to interact with GitHub repositories and listen for webhooks.

Installing the GitHub Plugin:

1. Navigate to Jenkins Dashboard.
2. Click on Manage Jenkins in the left-hand menu.
3. Go to Manage Plugins.
4. Select the Available tab and search for GitHub.
5. Check the GitHub Plugin and click Install without restart.
6. Once the plugin is installed, make sure to restart Jenkins to ensure all changes take effect.

2.2 Step 2: Set Up GitHub Webhooks

To trigger a Jenkins job whenever changes are pushed to a GitHub repository, you need to configure webhooks in your GitHub repository.

Steps to Set Up a GitHub Webhook:

1. Go to your GitHub repository's Settings page.
2. In the left-hand menu, select Webhooks.
3. Click Add webhook.
4. Set the Content type to application/json.
5. In the Which events would you like to trigger this webhook? section, choose Just the push event to trigger the build on code pushes. You can also choose other events based on your needs.
6. Click Add webhook to save the changes.

In the Payload URL field, provide the URL of your Jenkins server followed by /github-webhook/. For example:

http://your-jenkins-url/github-webhook/

2.3 Step 3: Configure the Jenkins Job to Use Webhooks

Now that the webhook is set up, the next step is to configure the Jenkins job to respond to GitHub webhook events.

1. Navigate to the Jenkins Dashboard and open the job you want to configure.
2. Click on Configure in the left-hand menu.
3. Scroll down to the Build Triggers section.
4. Check the option GitHub hook trigger for GITScm polling.This ensures that Jenkins listens for webhook events from GitHub and triggers the build whenever there’s a change in the repository.
5. Save the job configuration.

2.4 Step 4: Testing the Webhook Trigger

To verify that the webhook is functioning as expected, make a change in the GitHub repository (e.g., push a new commit or make a pull request). If everything is configured correctly, Jenkins will automatically trigger a build in response to the change.

3. Scheduling Builds Using Cron Expressions

Another common way to trigger Jenkins builds is through scheduled builds, which run based on a predefined schedule. Jenkins uses cron syntax to define the frequency of these builds.

3.1 Step 1: Configure a Scheduled Build in Jenkins

1. Go to the Jenkins Dashboard and select the job you want to schedule.
2. Click on Configure.
3. Scroll down to the Build Triggers section.
4. Check the Build periodically option.This allows you to define a cron expression to schedule builds.
5. In the Schedule field, enter a cron expression that defines when the build should be triggered.

3.2 Step 2: Writing Cron Expressions for Scheduled Builds

Jenkins uses a cron-like syntax for scheduling builds. A cron expression is a string of five fields separated by spaces, where each field defines a time or date value.

Here’s the format of the cron expression:

MINUTE HOUR DOM MONTH DOW

• MINUTE: The minute of the hour (0-59).
• HOUR: The hour of the day (0-23).
• DOM (Day of Month): The day of the month (1-31).
• MONTH: The month of the year (1-12).
• DOW (Day of Week): The day of the week (0-7), where both 0 and 7 represent Sunday.

3.3 Examples of Common Cron Expressions

Run on the first day of every month at midnight:

0 0 1 * *

Run every Monday at 9 AM:

0 9 * * 1

Run at midnight every day:

0 0 * * *

Run every hour:

H * * * *

The H symbol in Jenkins' cron expressions allows for hash-based scheduling, which distributes the load across available agents instead of triggering builds at exactly the same time.

4. Using Other Build Triggers (Polling SCM, Build on Dependency Change)

In addition to GitHub webhooks and schedule-based triggers, Jenkins offers other methods to trigger builds automatically.

Polling SCM

Polling SCM is an alternative to using webhooks. Jenkins periodically checks the source code repository for changes, and if changes are detected, it triggers a build.

To configure SCM polling:

1. In the Build Triggers section of the job configuration, check Poll SCM.
2. In the Schedule field, enter the frequency at which Jenkins should check for changes (using cron syntax).

{image of Jenkins config}

More about Pulling SCM triggers please check my previous post Triggering Jenkins Jobs on Repository Changes Using Polling.

Build on Dependency Change

You can configure jobs to trigger builds when upstream projects are built successfully. This ensures that changes in related projects are automatically propagated through the pipeline.

1. In the job configuration, scroll down to Build Triggers.
2. Check the option Build after other projects are built.
3. Enter the name(s) of the upstream projects that should trigger this job.

5. Best Practices for Configuring Build Triggers

• Use Webhooks for Efficiency: Webhooks are more efficient than SCM polling because they allow immediate build triggering without the overhead of periodic checks.
• Schedule Regular Builds: For projects that rely on long-running processes (such as nightly testing), use schedule-based builds to automate testing and deployments.
• Balance Polling Intervals: If you must use SCM polling, set reasonable intervals to avoid overloading the server and the SCM system with frequent polling.
• Test Webhooks: Always test webhook configurations after setting them up to ensure they are working as expected.
• Document Build Triggers: For complex projects, document the build trigger configuration so that team members understand how and when builds are initiated.

Conclusion

Setting up build triggers in Jenkins is a key part of automating your CI/CD pipelines. Whether you use GitHub webhooks for instant builds or scheduled builds for periodic tasks, Jenkins provides flexible and powerful tools for automating your workflows.

By following the steps outlined in this post, you can configure Jenkins to automatically trigger builds based on repository changes or time schedules, ensuring that your development and deployment pipelines are always up to date.