A build trigger tells Jenkins when to start a job. Without one, nothing happens until someone clicks "Build Now." With one, Jenkins kicks off builds automatically when code is pushed, when a schedule fires, when another job finishes, or when an external system sends a request.
Most Jenkins tutorials show you how to create a job and run it manually. The triggers are the part that makes Jenkins actually useful for CI/CD, because nobody wants to log into the dashboard and click a button every time someone pushes a commit.
Here are the six trigger types, what each one does, and when to use which.
1. Manual trigger (Build Now)
The default. No configuration needed. You open the Jenkins dashboard, find the job, and click "Build Now." Jenkins runs the job immediately.
This sounds basic, and it is. But manual triggers aren't useless. They make sense for jobs you don't want running automatically: deployment to production (you want a human deciding when), one-off maintenance scripts, or test runs against a specific branch that's still in progress.
In a Jenkinsfile, there's no trigger block for manual. The absence of a trigger IS the manual trigger. The job sits there until someone starts it.
2. SCM polling (Poll SCM)
Jenkins checks your source code repository (GitHub, GitLab, Bitbucket) on a schedule. If there's a new commit since the last check, it triggers a build. If nothing changed, it does nothing.
You configure it with a cron expression in the job settings or in your Jenkinsfile:
triggers {
pollSCM('H/5 * * * *') // check every 5 minutes
}The H is a Jenkins-specific symbol that adds a hash-based offset so all your jobs don't poll at the exact same time. H/5 * * * * means "every 5 minutes, but staggered across different jobs."
When to use it: When webhooks aren't an option. Maybe your Jenkins is behind a firewall and GitHub can't reach it. Maybe your Git server doesn't support webhooks. Polling is the fallback.
When to avoid it: When you have many repositories. Each poll requires Jenkins to connect to the repository and check for changes. With 50 jobs polling every 5 minutes, that's 600 Git requests per hour. Your Git server will notice. Webhooks are better for anything beyond a handful of jobs.
3. Webhooks (GitHub hook trigger)
The opposite of polling. Instead of Jenkins asking Git "anything new?", Git tells Jenkins "I just got a push." When someone pushes a commit, GitHub (or GitLab, or Bitbucket) sends an HTTP POST to your Jenkins URL. Jenkins receives it and triggers the build.
Setup has two sides. On Jenkins, enable "GitHub hook trigger for GITScm polling" in the job configuration (or install the Generic Webhook Trigger plugin for more control). On GitHub, go to your repo's Settings, then Webhooks, and add your Jenkins URL:
https://your-jenkins.com/github-webhook/
Set the content type to application/json and choose which events trigger the webhook (usually "Just the push event" or "Pull requests" depending on your workflow).
The catch: Your Jenkins instance needs to be reachable from the internet (or at least from GitHub's IP ranges). If Jenkins runs on an internal network behind a firewall with no public URL, webhooks won't work. That's when you fall back to polling.
In a Jenkinsfile, the GitHub webhook trigger doesn't have an explicit triggers block. Jenkins automatically listens for webhooks when the job is connected to a GitHub repository and the webhook is configured on the GitHub side.
Webhooks vs polling, plainly: Webhooks are faster (build starts within seconds of a push), use fewer resources (no repeated Git requests), and scale better (100 repos, no problem). Polling is simpler to set up (no firewall configuration needed) but slower and more resource-hungry. Use webhooks if you can. Use polling if you can't.
4. Cron schedule (Build periodically)
Runs the job on a time-based schedule regardless of whether anything changed in the repository. This is a pure cron trigger.
triggers {
cron('H 0 * * *') // once per day around midnight
}
Cron syntax in Jenkins follows the standard five-field format:
MINUTE HOUR DAY_OF_MONTH MONTH DAY_OF_WEEK
Some examples:
- H 0 * * * runs once daily around midnight
- H 3 * * 1 runs once weekly on Monday around 3 AM
- H/15 * * * * runs every 15 minutes
- H 8,20 * * 1-5 runs at 8 AM and 8 PM on weekdays
The H symbol spreads the load. If you have 20 jobs all set to 0 0 * * *, they'll all fire at exactly midnight and overwhelm your Jenkins agents. H 0 * * * picks a different minute within the midnight hour for each job based on the job name hash.
When to use it: Nightly builds, weekly reports, periodic security scans, database backup jobs, or any task that should run on a clock rather than on a code change. Also useful for running your full regression test suite nightly across your device matrix when running it on every commit would be too slow.
When to avoid it: As a substitute for webhooks. If your goal is "build when code changes," use webhooks or SCM polling, not cron. A cron trigger runs even if nothing changed, wasting build resources.
5. Upstream project trigger (Build after other projects are built)
Triggers a job when another job finishes. Job A builds the backend. When Job A succeeds, Job B runs the integration tests. When Job B succeeds, Job C deploys to staging.
In the Jenkins UI, it's under Build Triggers: "Build after other projects are built." You enter the upstream job name and choose whether to trigger on success only, on failure, or on any completion.
In a Jenkinsfile:
triggers {
upstream(
upstreamProjects: 'build-backend',
threshold: hudson.model.Result.SUCCESS
)
}
This is how you chain jobs into a pipeline without using a single Jenkinsfile for everything. It's useful when different teams own different jobs (the backend team owns the build job, the QA team owns the test job, the platform team owns the deploy job) and you want them loosely coupled rather than stuffed into one massive pipeline.
When to use it: Multi-stage pipelines where different teams own different stages. Also useful for triggering a slow job (like a full test suite or a performance test run) only after a fast job (like a build) succeeds, so you don't waste time testing a broken build.
6. Remote trigger (Trigger builds remotely)
Starts a job by hitting a URL with a token. Any system that can make an HTTP request can trigger a Jenkins build: a Slack bot, a monitoring alert, a deploy script, another CI system, or a curl command from your terminal.
Enable it in the job configuration under "Trigger builds remotely" and set an authentication token. Then trigger it with:
curl -X POST "https://your-jenkins.com/job/my-job/build?token=MY_SECRET_TOKEN"For jobs with parameters:
curl -X POST "https://your-jenkins.com/job/my-job/buildWithParameters?token=MY_SECRET_TOKEN&BRANCH=main&ENV=staging"
In a pipeline, you'd typically use the Build Token Trigger plugin or the Generic Webhook Trigger plugin for more sophisticated filtering (triggering only when the incoming JSON payload contains specific fields).
When to use it: Integrating Jenkins with external systems. Your monitoring tool detects a production incident and triggers a rollback job. Your deploy bot in Slack triggers a staging deploy when someone types /deploy staging. A mobile testing platform finishes a test run and triggers the next pipeline stage. These are all remote trigger use cases.
Combining triggers in a Jenkinsfile
Most real-world pipelines use more than one trigger. A common setup:
pipeline {
agent any
triggers {
pollSCM('H/5 * * * *') // fallback polling
cron('H 2 * * *') // nightly full build
upstream(
upstreamProjects: 'build-api',
threshold: hudson.model.Result.SUCCESS
)
}
stages {
stage('Build') {
steps {
sh './gradlew build'
}
}
stage('Test') {
steps {
sh './gradlew test'
}
}
stage('Deploy') {
when { branch 'main' }
steps {
sh './deploy.sh staging'
}
}
}
}
This pipeline triggers three ways: every 5 minutes if there's a new commit (polling), once nightly regardless (cron), and whenever the build-api job succeeds (upstream). In practice, you'd replace the polling with a webhook if your Jenkins is publicly reachable.
Which trigger for which situation
The choice is usually straightforward. Webhooks for code-change builds. Cron for scheduled jobs. Upstream for chaining. Remote for external integration. Manual for anything that needs a human gate.
FAQ
What are build triggers in Jenkins?
Build triggers are the mechanisms that tell Jenkins when to start a job. They include manual (clicking Build Now), SCM polling, webhooks, cron schedules, upstream project completion, and remote API triggers.
What is the difference between Poll SCM and webhooks?
Poll SCM makes Jenkins check the repository on a schedule. Webhooks make the repository notify Jenkins when a change happens. Webhooks are faster and use fewer resources. Polling is simpler when Jenkins can't receive incoming connections.
What does H mean in Jenkins cron syntax?
H is a Jenkins-specific symbol that picks a consistent but job-specific minute within the given range. It prevents all jobs from firing at the same time. H 0 * * * means "sometime during the midnight hour," different for each job.
Can I combine multiple triggers on one job?
Yes. A job can have a webhook for code pushes, a cron schedule for nightly runs, and an upstream trigger from another job, all at the same time. Jenkins fires the build whenever any of the triggers activate.
How do I trigger a Jenkins build from an external system?
Enable "Trigger builds remotely" in the job config, set a token, and send an HTTP POST to https://your-jenkins/job/your-job/build?token=YOUR_TOKEN. Any system that can make HTTP requests (Slack bots, monitoring tools, scripts) can use this.
Is Poll SCM bad practice?
Not inherently, but it's inefficient at scale. Polling 50 repos every 5 minutes generates 600 Git requests per hour. For a few jobs behind a firewall, polling is fine. For larger setups, switch to webhooks.
