Schedule backups in the CloudBees Backup plugin

The CloudBees Backup plugin uses a scheduler similar to the UNIX cron utility.

Line formatting

Each line is made up of five fields, separated by a tab character or whitespace:

MINUTE: The minute within the hour, specified as a whole number between 0 and 59.
HOUR: The hour of the day, specified as a whole number between 0 and 23.
DOM: The day of the month, specified as a whole number between 1 and 31.
MONTH: The month of the year, specified as a whole number between 1 (January) and 12 (December).
DOW: The day of the week, specified as a whole number between 0 (Sunday) and 6 (Sunday).

Each individual field can accommodate multiple values, using the following operators, where * takes precedence over M-N, which takes precedence over M-N/X, and so on:

specifies all valid values for the field. For example, using in the MINUTE field specifies "every minute between minute 0 and minute 59".
_M_-_N_ specifies a range of values between M and N. For example, using 12-14 in the HOUR field specifies "every hour between 1200 and 1400".
_M_-_N_/_X_ or _*_/_X_ steps through the range between M and N in intervals of X, continuing through the specified range (if using M-N) or the whole valid range (if using *).
A,B,…,Z is a list enumerating multiple values. For example, using 15,30,45,00 in the MINUTE field specifies "at 15 minutes after the hour, 30 minutes after the hour, 45 minutes after the hour, and at the top of the hour".

Using H to distribute load

The H ("hash") operator should be used whenever possible to evenly distribute processing load. Conceptually, you can think of the H operator as "a random value over a given range", but it’s actually a hash of the job name: this keeps the value stable for any given project.

For instance, using 0 0 * * * ("at midnight, every day of the week, for every month of the year") on twelve different daily jobs would cause a large processing spike at midnight every day, because all of those dozen jobs would kick off at the same time.

If you instead used H H * * *, those jobs would all still be executed once per day, but spread out over a range of times, distributing the cumulative load.

The H operator can take a range of values. For example, specifying H H(0-7) * * * for the twelve different daily jobs would cause those jobs to be executed "sometime between 00:00 (midnight) and 07:59".

The DOM (Day Of Month) field can be tricky at the end of the month when you’re using short cycles like */3 or H/3, because of the variation in month lengths. For example, */3 runs on the 1st, 4th and 31st days of a month, and then starting again on the 1st day of the following month. Because hashes are always chosen in a range between 1 and 28, H/3 produces a gap between jobs of anywhere from 3 to 6 days at the end of a month.

Comments and aliases

Empty lines and lines starting with # are both treated as comments.

The following aliases, all of which use the hash system for automatic balancing, are supported:

@yearly: equivalent to "once per year, at some time during the year".
@annually
@monthly: equivalent to H H 1 * * or "every month at some time between 00:00 and 02:59 on the first day of the month".
@weekly: equivalent to H H * * H or "some time between 00:00 and 02:59 on a day of the week between Sunday and the following Sunday".
@daily: equivalent to H H * * *, or "every day at some time between 00:00 and 02:59".
@midnight: equivalent to H H * * *, or "every day at some time between 00:00 and 02:59".
@hourly: equivalent to H * * * * or "at any time during the hour".

Examples

H/15 * * * *: Every fifteen minutes, hashed. For example, this scheduler could "fire" at :07, :22, :37, and :52.
H(0-29)/10 * * * *: Every ten minutes, sometime in the first half of every hour (which results in three invocations of the job).
45 9-16/2 * * 1-5: Every weekday, once every two hours at 45 minutes past the top of the hour, starting at 09:45 and concluding by 15:45.
H H(9-16)/2 * * 1-5: Every weekday, once in every two-hour window between 09:00 and 17:00. For example, this scheduler could "fire" at 10:38, 12:38, 14:38, and 16:38.
H H 1,15 1-11 *: Once per day on the 1st and 15th of every month except December.

Specifying a time zone

By default, periodic tasks are fired off at the scheduled time within the timezone of the JVM on the Jenkins controller (Etc/UTC). However, you can modify this behavior by specifying an alternative time zone as the first line of the schedule entry:

TZ=Europe/London
# Run this job at some time during the morning, London time
H 8 * * *
# Run the job again sometime in the first 30 minutes after 1700
H(0-30) 17 * * *▼

The supported time zones depend on the Java runtime upon which Jenkins is running, and will be listed in the help entry for the Schedule field.