Scheduling a Build

note

Please ensure you've already started a build for your repo before attempting to setup a schedule.

Vela supports the ability to periodically trigger builds for a repo known as a "schedule".

Outside of the Vela ecosystem, this is more commonly known as a cron expression.

Users will be able to manage schedules for a repo via the UI, API and CLI.

Only users with admin access to a repo will be able to manage schedules for that repo.

warning

We make best efforts to support feature parity with cron but we may not support every capability.

Entry

Users will be able to customize the cadence or frequency for how often the schedule should trigger a build via the entry field.

By default, Vela sets a frequency limit of 1h which controls the smallest amount of time a schedule can wait before running.

i.e. A schedule can't trigger a build more often than every hour but this may be different for the Vela installation you use.

Here's a small list of examples to demonstrate valid values for this field:

• 0 * * * * - setup a schedule to run every hour
• 0 0 * * * - setup a schedule to run every day at midnight
• 0 0 * * 0 - setup a schedule to run every week on Sunday at midnight

Vela currently uses github.com/adhocore/gronx to parse and validate this field.

This library also supports a number of "common cron expressions" (a.k.a. "tags") i.e. @hourly, @daily, @weekly etc.

For more information, please see that library's official docs for these tags.

tip

We recommend leveraging an official cron expression generator like Crontab Guru to build the entry for your schedule.

Pipeline

Uses will be able to customize what stages or steps will run in a build for a schedule using a ruleset:

version: "1"

steps:
  - name: unit-test
    ruleset:
      event: [ deployment, schedule ]
      target: [ unit_test, integration_test, nightly ]
    commands:
      - echo "I run when a schedule with the name 'unit_test', 'integration_test' or 'nightly' is executed"

  - name: integration-test
    ruleset:
      event: [ deployment, schedule ]
      target: [ integration_test, nightly ]
    commands:
      - echo "I run when a schedule with the name 'integration_test' or 'nightly' is executed"
      
  - name: publish
    ruleset:
      event: [ deployment, schedule ]
      target: [ nightly ]
    commands:
      - echo "I run when a schedule with the name 'nightly' is executed"
      
  - name: notification
    ruleset:
      event: [ deployment, schedule ]
    commands:
      - echo "I run when any schedule is executed"

tip

We recommend adding the deployment event to your ruleset for processes that you want to run on a schedule.

This will enable you to manually trigger a build that replicates the configuration you want to run on a schedule.

This is especially useful when attempting to initially test and debug your pipeline for a schedule.