Scheduled builds

Run a schedule once

You can run a schedule once without waiting for its next scheduled run. From your pipeline, select Settings > Schedules, then select the schedule.

Choose the action that matches the build you need:

• Run now: Run one build using the schedule's saved message, commit, branch, and environment variables. Select Run build now in the confirmation dialog. The build has source schedule, is associated with the schedule, and appears in its Recent Builds. The build identifies you as its creator.
• Run with edits: Open the pre-filled New Build form to customize a one-off build, such as changing environment variables for a test run. Edit the available fields, then submit the form. The build has source ui and is not associated with the schedule. Changes apply only to this build, not to the saved schedule.

Neither action changes the saved schedule or its next scheduled run. You can also run a disabled schedule once without enabling it.

Use Run now to test conditionals or secret access policies that check for source schedule. You can check a build's source using BUILDKITE_SOURCE.

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.

Invalid notification configuration

If the build-level notify configuration is invalid when a schedule runs automatically, Buildkite Pipelines disables the schedule and stores the validation error, rather than silently skipping the build. For example, a Slack ID for a channel, conversation, or user is ambiguous when your organization has more than one Slack Workspace integration enabled. This configuration fails with an error like the following:

To resolve this error while preserving the notification destination, prefix the ID with the workspace slug and @, for example, buildkite-community@U12345678. See Notify a channel in one workspace for the correct syntax.

The disabled schedule's failure notification email contains the same error message. After correcting the notify configuration, re-enable the schedule to resume scheduled builds.

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.

Predefined intervals

Buildkite supports 6 predefined intervals:

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.

Unsupported syntax

The ~ random-value operator (for example, 0 ~ * * *) is not supported in Buildkite Pipelines schedules and will be rejected at validation time.

Examples