Jenkins: Schedule – Build Periodically – Parameters

A Job in Jenkins can be scheduled for periodical builds in a declarative pipeline i.e. Jenkinsfile using a string in a cron-style syntax (with minor differences) defined in the triggers directive, for example triggers{cron('0 */3 * * *')}.

This note shows the examples of how to build Jenkins jobs and multi-branch pipelines periodically and how to schedule Jenkins jobs with parameters.

Also it shows the Jenkins cron syntax with examples.

Cool Tip: Define conditional variables in a Jenkins pipeline! Read more →

Jenkins Schedule

Schedule a build in Jenkins:

// Build once a day
CRON_SETTINGS = '''H H * * *'''

// Multi-branch pipeline. Build once a day from a "master" branch only
CRON_SETTINGS = BRANCH_NAME == "master" ? '''H H * * *'''

pipeline {
  agent any
  triggers {
    cron(CRON_SETTINGS)
  }
  stages {
    stage ("Example") {
      steps {
        echo "Hello World"
      }
    }
  }
}

Parameterized Scheduler: To schedule a build in Jenkins with parameters, you should use the parameterized-scheduler plugin (search for it in “Manage Jenkins”“Manage Plugins”“Parameterized Scheduler”).

Build periodically with parameters in Jenkins:

// Build once a day with a parameter
CRON_SETTINGS = '''H H * * * % ENV=DEV''' : ""

// Build with multiple parameters
CRON_SETTINGS = '''H H * * * % ENV=DEV;TARGET=FRONT''' : ""

// Multi-branch pipeline. Build once a day from a "develop" branch only
CRON_SETTINGS = BRANCH_NAME == "develop" ? '''H H * * * % ENV=DEV;TARGET=FRONT
                                              H H * * * % ENV=DEV;TARGET=BACK''' : ""

pipeline {
  agent any
  triggers {
    parametrizedCron(CRON_SETTINGS)
  }
  stages {
    stage ("Example") {
      steps {
        echo "Hello World"
      }
    }
  }
}

Jenkins UI: To schedule the parameterized build through the Jenkins UI, the job should have the parameters already setup because the plugin is visible only for the jobs with parameters.

Jenkins Cron Syntax

Here is a schema for better understanding of the Jenkins cron format:

.---------------- minute (0 - 59)
| .-------------- hour (0 - 23)
| | .------------ day of month (1 - 31)
| | | .---------- month (1 - 12) OR jan,feb,mar ...
| | | | .-------- day of week (0 - 6) (Sunday=0 or 7) OR sun,mon,tue ...
| | | | |
* * * * * command to be executed

Here are the several special predefined values which can be used to substitute the expressions in Jenkins cron:

Entry Description Equiv to
@yearly Run at any time during the year H H H H *
@annually Run at any time during the year H H H H *
@monthly Run at any time during the month H H H * *
@weekly Run at any time during the week H H * * H
@daily Run at any time during the day H H * * *
@midnight Run at some time between 12:00 AM and 2:59 AM
@hourly Run at any time during the hour H * * * *

From the Jenkins code documentation:

To allow periodically scheduled tasks to produce even load on the system, the symbol H (for “hash”) should be used wherever possible. For example, using 0 0 * * * for a dozen daily jobs will cause a large spike at midnight. In contrast, using H H * * * would still execute each job once a day, but not all at the same time, better using limited resources.

The H symbol can be thought of as a random value over a range, but it actually is a hash of the job name, not a random function, so that the value remains stable for any given project.

Here are the most common examples of cron job schedules that can be found in almost any crontab on Linux (use H in the examples below to spread the load evenly in Jenkins):

Schedule Job
* * * * * echo “Run cron job every minute”
*/5 * * * * echo “Run cron job every 5 minutes”
*/30 * * * * echo “Run cron job every 30 minutes”
0 * * * * echo “Run cron job every hour”
0 */3 * * * echo “Run cron job every 3 hours”
0 13 * * * echo “Run cron job every day at 1pm”
30 2 * * * echo “Run cron job every day at 2.30am”
0 0 * * * echo “Run cron job every day at midnight”
0 0 * * 0 echo “Run cron job every Sunday”
0 0 * * 1 echo “Run cron job every Monday”
0 0 1 * * echo “Run cron job every first day of every month”
0 0 1 1 * echo “Run cron job every first of January every year”

Cool Tip: Disable automatic Jenkins job triggering during SCM scanning for the new branches! Read more →