Scheduled builds

Build schedules automatically create builds at specified intervals. For example, you can use scheduled builds to run nightly builds, hourly integration tests, or daily ops tasks.

You can create and manage schedules in the Schedules section of your pipeline's Settings.

Screenshot of the Schedules section of Pipeline Settings with an Hourly Security Checks schedule listed

You can also create and manage schedules using the Buildkite GraphQL API.

Cron job permission consideration

When setting up a cron job in your parent pipeline, it's important to ensure that the same team has been assigned to the corresponding child pipeline. Failure to match the team between the parent and child pipelines may result in an error with the following message:

Error:

Could not find a matching team that includes both pipelines, each having a minimum "Build" access level.

This error is indicative of a mismatch in team assignments and highlights the importance of maintaining consistent team configurations across interconnected pipelines to avoid permission-related issues.

Schedule intervals

The interval defines when the schedule will create builds. Schedules run in UTC time by default, and can be defined using either predefined intervals or standard crontab time syntax.

Interval granularity

Buildkite only guarantees that scheduled builds run within 10 minutes of the scheduled time, and therefore does not support intervals less than 10 minutes.

Predefined intervals

Buildkite supports 6 predefined intervals:

Interval Description Crontab Equivalent
@hourly At the start of every hour 0 * * * *
@daily or @midnight Every day at midnight UTC 0 0 * * *
@weekly Every week at midnight Sunday UTC 0 0 * * 0
@monthly Every month, at midnight UTC on the first day 0 0 1 * *
@yearly Every year, at midnight UTC on the first day 0 0 1 1 *

Crontab time syntax

Intervals can be defined using a variant of the crontab time syntax:

 ┌───────────── minute (0 - 59)
 │ ┌───────────── hour (0 - 23)
 │ │ ┌───────────── day of month (1 - 31)
 │ │ │ ┌───────────── month (1 - 12)
 │ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
 │ │ │ │ │          ┌─── time zone name or offset (optional)
 │ │ │ │ │          │
 * * * * * Australia/Melbourne

A time zone can optionally be specified as the last segment, either as an IANA Time Zone name like Australia/Melbourne or Europe/Berlin, or as an offset from UTC like +09:00 or -05:00. If no time zone is given, the schedule will run in UTC.

Supported extensions

Buildkite supports several extensions to the standard POSIX cron syntax.

The / operator

The slash operator allows you to specify step values within ranges. For example, */10 * * * * would run every ten minutes.

L or last token

Using L or last in the "day of month" field represents the last day. For example, 0 0 L * * represents midnight on the last day of the month, and 0 0 -2-L * * represents the last two days of the month.

Modulo

Using the modulo extension allows you to create schedules for less common sets of weekdays.

Modulo can only be used with the "day of week" field. For example, 0 0 * * 0 represents midnight on every Sunday. Adding a modulo of 3 creates a schedule that runs at midnight on every third Sunday: 0 0 * * 0%3.

You can also use the offset + operator alongside a modulo value. For instance, adding an offset of 1 to our previous example 0 0 * * 0%3+1 will create a schedule to run a build every third Sunday that is an odd calendar number. Modulo is calculated based on the time since 2019-01-01.

For more information on how modulo works, see the official documentation of Fugit, which is used for extending the POSIX cron syntax in Buildkite.

Examples

*/10 * * * * Every 10 minutes
*/30 * * * * Every 30 minutes
30 * * * * Every 30th minute of every hour
0 */4 * * * Every 4 hours
0 */12 * * * Every 12 hours
0 0 */2 * * +01:00 Every other day at midnight UTC+1
0 8 * * * Every day at 8am UTC
0 8 * * * America/Vancouver Every day at 8am in Vancouver
0 16 * * SUN Every Sunday at 4pm UTC
0 0 * * 1-5 Every weekday at midnight UTC
0 0 L * * Midnight UTC on the last day of the month
0 0 1 */2 * Every other month, at midnight UTC on the first day
0 16 L * * The last day of the month at 4pm UTC
0 0 * * 2%2+1 The start of every odd Tuesday