4.8.7 Nightly Scheduler

This is highly configurable periodic build scheduler, which triggers a build at particular times of day, week, month, or year. The configuration syntax is very similar to the well-known crontab format, in which you provide values for minute, hour, day, and month (some of which can be wildcards), and a build is triggered whenever the current time matches the given constraints. This can run a build every night, every morning, every weekend, alternate Thursdays, on your boss's birthday, etc.

Pass some subset of minute, hour, dayOfMonth, month, and dayOfWeek; each may be a single number or a list of valid values. The builds will be triggered whenever the current time matches these values. Wildcards are represented by a '*' string. All fields default to a wildcard except 'minute', so with no fields this defaults to a build every hour, on the hour. The full list of parameters is:

name

builderNames

properties

fileIsImportant

branch

(required) The branch to build when the time comes. Remember that a value of None here means the default branch, and will not match other branches!

change_filter

see Configuring Schedulers. Note that fileIsImportant and change_filter are only relevant if onlyIfChanged is true.

minute

The minute of the hour on which to start the build. This defaults to 0, meaning an hourly build.

hour

The hour of the day on which to start the build, in 24-hour notation. This defaults to *, meaning every hour.

dayOfMonth

The day of the month to start a build. This defauls to *, meaning every day.

month

The month in which to start the build, with January = 1. This defaults to *, meaning every month.

dayOfWeek

The day of the week to start a build, with Monday = 0. This defauls to *, meaning every day of the week. If dayOfMonth and dayOfWeek are both specified, builds will be started when either parameter matches.

onlyIfChanged

If this is true, then builds will not be scheduled at the designated time unless the specified branch has seen an important change since the previous build.

For example, the following master.cfg clause will cause a build to be started every night at 3:00am:

     from buildbot.schedulers import timed
     s = timed.Nightly(name='nightly',
             branch='master',
             builderNames=['builder1', 'builder2'],
             hour=3,
             minute=0)

This scheduler will perform a build each monday morning at 6:23am and again at 8:23am, but only if someone has committed code in the interim:

     s = timed.Nightly(name='BeforeWork',
              branch='default',
              builderNames=['builder1'],
              dayOfWeek=0,
              hour=[6,8],
              minute=23,
              onlyIfChanged=True)

The following runs a build every two hours, using Python's range function:

     s = timed.Nightly(name='every2hours',
             branch=None, # default branch
             builderNames=['builder1'],
             hour=range(0, 24, 2))

Finally, this example will run only on December 24th:

     s = timed.Nightly(name='SleighPreflightCheck',
             branch=None, # default branch
             builderNames=['flying_circuits', 'radar'],
             month=12,
             dayOfMonth=24,
             hour=12,
             minute=0)