Cron Schedules

Mint can trigger runs on a recurring schedule with cron notation.

Defining a Cron Schedule

Much like event triggers, cron schedules are defined in the on section of your run definition. The on.cron field must be an array. For example, let's take a look at:

on:
  cron:
    - key: ensure-tests-pass-after-midnight-utc
      schedule: '30 0 * * *' # daily at 00:30 UTC

The key is required and is a semantic description for you to differentiate schedules in the Cloud UI. Additionally, we use this when maintaining which schedules are still running and which schedules need updated. The key must be unique within any single run definition.

The schedule is also required and should be defined as a cron expression.

Scheduling Runs on a Different Branch

By default, cron schedules will run on the default branch of your repository. If you'd like a cron schedule to run on a different branch, you can specify the branch like so:

on:
  cron:
    - key: ensure-tests-pass-after-midnight-utc
      schedule: '30 0 * * *' # daily at 00:30 UTC
      branch: release

Cron schedules are created, updated, and destroyed as they are changed on the branch where they run. In other words, if you define a cron schedule that runs on the release branch, the definition must exist on that branch. If you define a schedule that does not specify a branch, it must exist on the default branch of your repository.

The cron "event"

When a cron schedule triggers a run, it also provides a cron event with some useful information that you can map to init parameters via the init field:

on:
  cron:
    - key: ensure-tests-pass-after-midnight-utc
      schedule: '30 0 * * *' # daily at 00:30 UTC
      init:
        # The key of this cron trigger
        key: ${{ event.cron.key }}
        # The run definition path this trigger is defined in
        run-definition-path: ${{ event.cron.run_definition_path }}
        # The year of this invocation of the cron schedule
        year: ${{ event.cron.year }}
        # The month (1-12) of this invocation of the cron schedule
        month: ${{ event.cron.month }}
        # The day of the month (1-31) of this invocation of the cron schedule
        day-of-month: ${{ event.cron.day_of_month }}
        # The day of the week (0-6, starting on sunday) of this invocation of the cron schedule
        day-of-week: ${{ event.cron.day_of_week }}
        # The UTC hour (0-23) of this invocation of the cron schedule
        hour: ${{ event.cron.hour }}
        # The minute (0-59) of this invocation of the cron schedule
        minute: ${{ event.cron.minute }}
        # The git ref (e.g. `refs/heads/your-default-branch`)
        git-ref: ${{ event.cron.git.ref }}
        # The git sha at the time the cron schedule triggers (the run definition we use will be from this sha)
        git-sha: ${{ event.cron.git.sha }}
        # The HTML URL of your GitHub repository (if defined in a GitHub repository)
        github-repository-html-url: ${{ event.cron.github.repository.html_url }}
        # The name of your GitHub repository (if defined in a GitHub repository)
        github-repository-name: ${{ event.cron.github.repository.name }}
        # The owner of your GitHub repository (if defined in a GitHub repository)
        github-repository-owner: ${{ event.cron.github.repository.owner }}

Title

You can override the default title of your run by specifying the title. It accepts an expression and can use the mint, event, and init contexts. For example:

on:
  cron:
    - key: ensure-tests-pass-after-midnight-utc
      schedule: '30 0 * * *' # daily at 00:30 UTC
      title: 'Ensure tests pass at ${{ event.cron.hour }}:${{ event.cron.minute }}'

Target

If you only want to run certain tasks when the cron schedule is invoked, you can specify a target.

on:
  cron:
    - key: ensure-tests-pass-after-midnight-utc
      schedule: '30 0 * * *' # daily at 00:30 UTC
      target: task-key-to-run

If you want to target multiple tasks, pass them as an array.

on:
  cron:
    - key: ensure-tests-pass-after-midnight-utc
      schedule: '30 0 * * *' # daily at 00:30 UTC
      target: [task-key1, task-key2]

Conditional Triggers

Cron triggers can specify if to conditionally trigger a new run in response to the cron schedule being invoked. For example, if you want to skip the 7th hour of an hourly cron schedule (you can write this with a cron expression, but for demonstrative purposes assume you couldn't):

on:
  cron:
    - key: perform-hourly-task
      schedule: '0 * * * *' # hourly at minute 0
      if: ${{ event.cron.hour != 7 }}

Resetting tool caches

Cron jobs that are triggered with reset-tool-cache: true will evict & re-build the tool caches of a run. This is especially useful when paired with the target option.

on:
  cron:
    - key: rebuild-tool-cache
      schedule: '0 0 * * *' # Every day at midnight UTC
      target: [bundle-install]
      reset-tool-cache: true