Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 40 ยท Source Control and Triggers

Triggers: Webhooks, Polling and Schedules

Choose how Jenkins builds start: GitHub and GitLab webhooks, SCM polling, cron with the H hash, upstream triggers, remote tokens and the quiet period.

A pipeline that only runs when someone clicks "Build Now" is not continuous integration. Jenkins can start builds by itself in several ways: a Git server tells it about a push, it asks the Git server on a timer, a clock fires on a schedule, another job finishes, or a script calls a URL. Choosing the right trigger keeps builds fast, servers calm and results timely.

This lesson explains each trigger type, the cron syntax with its special H symbol, and the quiet period. The real Jenkins cannot run on this site, so the Jenkinsfile and configuration blocks are read-only. The runnable examples are Node stand-ins that model the ideas, including how H spreads load.

Five ways to start a build

Webhook The Git server calls Jenkins on a push.
Polling Jenkins asks Git if anything changed.
Schedule A cron expression fires the job.
Upstream Another job finished first.

Remote URLs with a token are a fifth option for scripts.

1 / 2

Declaring triggers in a Jenkinsfile

In a Declarative Pipeline, time-based and job-based triggers live in a triggers block:

GROOVY
pipeline {
  agent any
  triggers {
    cron('H 2 * * 1-5')                 // weekdays, around 02:xx
    pollSCM('H/15 * * * *')             // safety net: ask Git every ~15 min
    upstream(upstreamProjects: 'shared-lib-build',
             threshold: hudson.model.Result.SUCCESS)
  }
  stages {
    stage('Build') {
      steps { sh './build.sh' }
    }
  }
}

Webhook triggers are not written here. They are a combination of settings on the Jenkins job (for example "GitHub hook trigger for GITScm polling") and a webhook configured on the Git server. A multibranch job usually handles all of this through its branch source (see Multibranch Pipelines and Pull Requests).

An important detail: the triggers block is only read when the pipeline runs. A new schedule takes effect after the first build that contains it, so run the job once manually after adding a trigger.

Webhooks: let Git tell Jenkins

With a webhook, the Git server sends an HTTP request to Jenkins when something happens. The typical shape is:

  1. You install the plugin for your server (GitHub, GitLab, Bitbucket and others each have one).
  2. On the Git server you add a webhook that points to an endpoint on your Jenkins. For GitHub the plugin exposes /github-webhook/; GitLab and others use their own paths, which the plugin documentation lists.
  3. A push or pull request event arrives, Jenkins matches the repository, and the matching jobs are scheduled.

Things that commonly go wrong are all about reachability and trust: the Git server must be able to reach your Jenkins over the network (a Jenkins on a private network needs a reverse proxy or a tunnel), the URL must be exact including the trailing slash, and many setups sign the payload with a shared secret so Jenkins can reject forged requests. When builds do not start, check the delivery log on the Git server first: it shows the response code Jenkins returned.

SCM polling

With polling, Jenkins itself asks the repository whether there are new commits, using a cron-like schedule:

GROOVY
triggers { pollSCM('H/5 * * * *') }

Jenkins runs a light check ("what is the newest commit on this branch?") and starts a build only if the answer changed since the last build. Polling works when the Git server cannot reach Jenkins, but it has costs: a delay of up to the interval, and constant requests even when nobody pushes. With hundreds of jobs, frequent polling can overload the Git server. Use webhooks as the main mechanism, and polling as a slow safety net or as a fallback for servers that cannot send hooks.

Cron syntax and the H symbol

A schedule has five fields separated by spaces:

TEXT
MINUTE  HOUR  DOM  MONTH  DOW
0-59    0-23  1-31 1-12   0-7   (0 and 7 are Sunday)

Besides numbers, ranges (1-5), lists (1,15) and steps (*/10), Jenkins adds H, for "hash". Instead of firing at a fixed number, H picks a value that is derived from the job name and stays the same for that job. Different jobs get different values, so a hundred nightly jobs written as H 2 * * * do not all start at exactly 02:00 and crush the controller.

Examples:

Expression Meaning
H 2 * * * once a day, at some minute of the 02:00 hour
H/15 * * * * every 15 minutes, with a per-job offset
H(0-29)/10 * * * * every 10 minutes, but the offset is chosen in the first half hour
H H(9-16)/2 * * 1-5 every two hours during business hours, on weekdays
0 0 * * * exactly midnight (works, but every job piles up at the same moment)

Use H unless a job truly must run at an exact minute. Times are interpreted in the time zone of the controller unless you set one explicitly (the TZ= first-line syntax exists but is easy to forget; check your controller's zone if schedules seem hours off).

Upstream triggers and remote triggers

An upstream trigger starts a job when another job finishes with a given result. It is a simple way to chain jobs, for example "rebuild the app when the shared library build succeeds". For anything more than a simple chain, prefer one pipeline with several stages, or have a pipeline call another job with the build step, because the relationships are then visible in code.

A remote trigger lets a script start a job by calling a URL, protected by a token you set in the job:

Terminal
curl -X POST "https://jenkins.example.com/job/deploy-docs/build?token=$DOCS_TOKEN"

Treat that token as a secret. Many installations also require an authenticated user or an API token on the request, in addition to or instead of the job token, and CSRF protection may require a crumb for requests from scripts. Parameterized jobs are started through buildWithParameters rather than build. Check how your Jenkins is secured before you rely on a snippet.

The quiet period

A developer pushes three commits in ten seconds. Do you want three builds? Probably not. The quiet period is a short delay between the moment a build is scheduled and the moment it begins. If another trigger arrives for the same job during the delay, the timer restarts and the triggers merge into one build. The default is a few seconds globally. You can raise it for one job:

GROOVY
options { quietPeriod(30) }

A longer period reduces wasted builds but delays feedback, so choose it with care.

A stand-in for H hashing

The code below imitates how H works: it hashes the job name into a number and uses that number to choose the minute or hour. It is not Jenkins' real hash function, so the exact minutes will differ from a real server, but the properties are the same: stable for one job, different across jobs, and always inside the allowed range. It supports H, H/n, H(a-b), H(a-b)/n, */n, ranges, lists and numbers.

Node.js A stand-in H cron expander

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Run it and note that two runs produce the same minutes: the hash depends only on the job name. Different jobs land on different minutes, which is exactly how H protects a controller from a thundering herd at midnight.

A stand-in trigger evaluator

The second stand-in feeds a list of events into a tiny evaluator that applies three rules: a remote trigger needs the right token, pushes within the quiet period merge into one build, and an upstream success schedules the downstream job. Times are in seconds and are made up for the example.

Node.js A stand-in trigger evaluator with a quiet period

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Three quick pushes merged into one build, the wrong token was rejected, and the failed upstream result did not trigger anything because the threshold is SUCCESS.

Do not put a remote-trigger token or any secret in the repository. Store it as a credential and inject it with withCredentials, as shown in Credentials and Secrets.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does H do in a cron expression such as H 2 * * *?

    H hashes the job name to a fixed value inside the allowed range. The same job always gets the same time, and different jobs spread out.
  2. 2. Which trigger starts a build within seconds and does not make repeated requests to the Git server?

    A webhook is pushed by the Git server when an event happens, so there is no waiting for a timer and no empty checks.
  3. 3. What does the quiet period do?

    If more triggers arrive during the quiet period, the timer restarts and they result in a single build.
  4. 4. Why should you run a job once manually after adding a triggers block?

    Pipeline triggers are read from the Jenkinsfile when a build runs, so a new schedule becomes active after that first run.

Summary

  • Builds start from webhooks, SCM polling, cron schedules, upstream jobs or remote URLs with a token.
  • Prefer webhooks for speed and low load; keep a slow poll as a safety net.
  • Cron has five fields; H gives each job a stable, spread-out time. Use H unless an exact minute matters.
  • Upstream triggers chain jobs, but a single pipeline or the build step is usually clearer.
  • Remote trigger tokens are secrets, and your security settings may require more than the token.
  • The quiet period merges bursts of triggers into a single build.
  • A new triggers block applies after the first run of that Jenkinsfile.

Next, learn how Jenkins builds every branch and pull request in Multibranch Pipelines and Pull Requests.