Chapter 21: Jenkins Pipeline and Jenkinsfile

21.16 Triggers written in the Jenkinsfile

By Ravindra Bagale · Last updated: 25 October 2026

Why: the problem

A pipeline must start by itself at the right time. Think of Swiggy. Every push to main should build in seconds. Every night at 2 a.m. a full test should run. When the shared library job finishes, the app job should build again. Clicking Build Now for all this is not possible. Triggers in the Jenkinsfile handle it. There are three main kinds. cron runs on a schedule. pollSCM checks Git on a schedule and builds only if there is a new commit. upstream starts this job when another job finishes. A webhook from GitLab or Bitbucket is the fastest way and is set on the Git side. In this lesson you add each trigger, see the cause on the build page, and learn why webhooks beat polling.

What we will build

You will add a nightly cron, a pollSCM check, and an upstream trigger to the badge pipeline. You will see Started by timer, Started by an SCM change and Started by upstream project in the logs. You will then add a webhook and remove polling.

What: every term in plain English

• triggers — Declarative block for automatic starts.
• cron — Time schedule in five fields: minute hour day month weekday.
• H — Jenkins hash symbol that spreads start times.
• pollSCM — Checks Git on a schedule, builds only on new commits.
• upstream — Starts this job when another job finishes.
• Webhook — The Git server calls Jenkins on push.
• Build cause — The reason a build started, shown at the top of the log.
• TZ — Time zone setting for cron, like TZ=Asia/Kolkata.

How: step by step

1. Add cron

   triggers { cron("TZ=Asia/Kolkata\nH 2 * * 1-5") }
   

   What it does: Nightly on weekdays, India time.

   Output

   (file saved)
   

2. Run once

   Build Now
   

   What it does: Jenkins registers triggers on first run.

   Output

   Finished: SUCCESS
   

3. Check the job config

   Job > View Configuration > Build Triggers
   

   What it does: Shows the trigger from the file.

   Output

   Build periodically: H 2 * * 1-5
   

4. Add pollSCM

   triggers { pollSCM("H/5 * * * *") }
   

   What it does: Check Git every 5 minutes.

   Output

   Polling Log: No changes
   

5. Add upstream

   triggers { upstream(upstreamProjects: 'badge-lib', threshold: hudson.model.Result.SUCCESS) }
   

   What it does: Build after badge-lib passes.

   Output

   Started by upstream project badge-lib
   

6. Add webhook

   GitLab > Settings > Webhooks > https://jenkins.example.com/project/badge-scm
   

   What it does: Builds start in seconds.

   Output

   Hook executed successfully: HTTP 200
   

Example 1: Nightly cron in India time

Stack. Jenkins cron trigger

Goal. Nightly cron in India time.

Jenkinsfile

pipeline {
  agent any
  triggers {
    cron('TZ=Asia/Kolkata\nH 2 * * 1-5')
  }
  stages {
    stage('Nightly') {
      steps {
        echo "Cause: ${currentBuild.getBuildCauses()[0].shortDescription}"
        sh 'npm ci && npm test'
      }
    }
  }
}

What each line does

• TZ=Asia/Kolkata — Times are India time, not server UTC.
• H 2 * * 1-5 — Some minute in hour 2, Monday to Friday.
• getBuildCauses() — Tells why the build started.
• First run — Needed so Jenkins reads the trigger.

Green output

Started by timer
Cause: Started by timer
Tests: 2 passed, 2 total
Finished: SUCCESS

Expected result. The build ran at night by itself.

Example 2: pollSCM and upstream

Stack. Jenkins triggers

Goal. pollSCM and upstream.

Jenkinsfile

pipeline {
  agent any
  triggers {
    pollSCM('H/5 * * * *')
    upstream(upstreamProjects: 'badge-lib', threshold: hudson.model.Result.SUCCESS)
  }
  stages {
    stage('Build') { steps { sh 'npm ci && npm run build' } }
  }
}

What each line does

• pollSCM('H/5 * * * *') — Every 5 minutes, check for new commits.
• upstreamProjects — Comma list of jobs to watch.
• threshold SUCCESS — Only when the upstream job passed.
• Polling Log — Job page link that shows each check.

Green output

Polling Log
Started on Oct 25, 2026, 11:45:00 AM
Using strategy: Default
 > git ls-remote -h https://git.example.com/team/badge-node.git
Changes found
...
Started by an SCM change
Finished: SUCCESS

Started by upstream project "badge-lib" build number 7
Finished: SUCCESS

Expected result. Two different causes, both automatic.

Example 3: Webhook instead of polling

Stack. GitLab plugin webhook

Goal. Webhook instead of polling.

Jenkinsfile

pipeline {
  agent any
  triggers {
    gitlab(triggerOnPush: true, triggerOnMergeRequest: true, branchFilterType: 'All')
  }
  stages {
    stage('Build') { steps { echo "Pushed by ${env.gitlabUserName} on ${env.gitlabBranch}" } }
  }
}

test the hook

curl -s -o /dev/null -w "%{http_code}" -X POST \
  -H "X-Gitlab-Token: $HOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d @push-sample.json https://jenkins.example.com/project/badge-scm

What each line does

• gitlab(...) — GitLab plugin trigger; it listens for the webhook.
• triggerOnPush — Build on push.
• X-Gitlab-Token — The shared secret, stored as a credential, never in Git.
• No pollSCM — The webhook replaces polling. Keep a slow poll only as backup.

Green output

200
Started by GitLab push by Asha Patil
Pushed by Asha Patil on main
Finished: SUCCESS

Expected result. Build started within seconds of push. No polling load on Git.

Example 4: Trigger another job from a step and pass parameters

Stack. Jenkins build step

Goal. Trigger another job from a step and pass parameters.

Jenkinsfile (parent)

pipeline {
  agent any
  stages {
    stage('Build') { steps { sh 'npm ci && npm run build' } }
    stage('Start smoke test') {
      steps {
        build job: 'badge-smoke',
              wait: true,
              propagate: true,
              parameters: [string(name: 'COMMIT', value: env.GIT_COMMIT ?: 'none'),
                           booleanParam(name: 'FULL', value: false)]
      }
    }
  }
}

Jenkinsfile (badge-smoke)

pipeline {
  agent any
  parameters {
    string(name: 'COMMIT', defaultValue: 'none')
    booleanParam(name: 'FULL', defaultValue: false)
  }
  stages { stage('Smoke') { steps { echo "Smoke test for ${params.COMMIT}, full=${params.FULL}" } } }
}

What each line does

• build job: — Starts another job from a step.
• wait: true — The parent waits for the child to finish.
• propagate: true — If the child fails, the parent fails too.
• parameters — Values passed into the child job form.

Green output

[Pipeline] build (Building badge-smoke)
Scheduling project: badge-smoke
Starting building: badge-smoke #3
Build badge-smoke #3 completed: SUCCESS
...
(in badge-smoke #3)
Started by upstream project "badge-scm" build number 22
Smoke test for 4b2d9e1a7f3c0e55a8b21d9f0c6e7a4b1d2c3e4f, full=false

Expected result. The parent pushes work to a child with exact inputs. upstream triggers pull; build job pushes.

Verify: did it work?

1. See the cause

   Top of Console Output
   

   What it does: Shows why it started.

   Output

   Started by timer / SCM change / upstream / GitLab push
   

2. Check hook deliveries

   GitLab > Webhooks > Edit > Recent events
   

   What it does: Shows each call and status.

   Output

   200 OK
   

When it is red 1

Cron trigger did not run

Cause. The job never ran once after adding triggers.

Fix, step by step

1. Run Build Now once.

When it is red 2

Builds at wrong hour

Cause. Server time is UTC.

Fix, step by step

1. Add TZ=Asia/Kolkata as the first line.

When it is red 3

Hook executed: HTTP 403

Cause. Wrong secret token or CSRF settings.

Fix, step by step

1. Match the secret.
2. Use the plugin project URL.

When it is red 4

Polling every minute is slow

Cause. Too many polls load the Git server.

Fix, step by step

1. Use a webhook and H/15 backup polling.

Cleanup

1. Remove the cron

   Delete triggers and run once
   

   What it does: Stops nightly builds in the lab.

   Output

   (saved)
   

2. Delete the webhook

   GitLab > Webhooks > Delete
   

   What it does: Stops push builds.

   Output

   Webhook deleted
   

Practice tasks

Homework: try at home

Recap

• triggers block starts builds automatically.
• cron for schedules, with TZ.
• pollSCM checks for commits.
• upstream chains jobs.
• Webhooks are fastest; keep slow polling as backup.

FAQ

Do triggers work in Multibranch?

Use webhooks and scan triggers there; cron also works per branch.

Can I trigger another job?

Yes, with build job: name in a step.

What does @midnight mean?

A cron alias for some time between 0:00 and 2:59.

Can a webhook carry secrets?

Use a secret token stored in Jenkins credentials.

Why did a cron build run twice?

Two jobs or two branches have the same trigger.

upstream trigger or build step?

Use build job when the parent must pass values or wait for the result. Use upstream when the child simply follows.

Interview questions

1. How do you schedule a Jenkins pipeline?

   triggers with cron, using H and TZ, then run once to register.

2. pollSCM vs webhook?

   pollSCM asks Git every few minutes; a webhook pushes an event at once. Webhooks are faster and lighter.

3. How do you chain jobs?

   upstream trigger or a build step in the parent job.

4. Builds run at the wrong time. Why?

   Server timezone; add TZ in the cron.

5. How do you see why a build started?

   The build cause at the top of the console.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview card

मराठी cards