Cron Schedules

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

Defining a Cron Schedule

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. It's a semantic description for you to differentiate schedules in the Cloud UI. Additionally, it's used when maintaining which schedules are still running and which schedules need to be updated. The key must be unique within any single run definition.

The schedule is also required and should be defined as a cron expression. In addition to the standard minute hour day-of-month month day-of-week syntax, you can also declare a timezone identifier in the last position like so: 30 9 * * * America/New_York (daily at 09:30 Eastern Time). If you do not declare a timezone identifier, the cron schedule will use UTC as the timezone.

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:
        ## Meta fields about the cron trigger and event

        # The key of this cron trigger
        key: ${{ event.cron.key }}

        # How the cron invocation was triggered ("manual" or "scheduled")
        kind: ${{ event.cron.kind }

        # The run definition path this trigger is defined in
        run-definition-path: ${{ event.cron.run_definition_path }}

        ## Top-level time fields in the timezone of the cron schedule (by default, UTC unless you specify otherwise)

        # 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 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 }}

        ## UTC time fields, normalized to the UTC timezone

        # The year of this invocation of the cron schedule
        utc-year: ${{ event.cron.utc.year }}

        # The month (1-12) of this invocation of the cron schedule
        utc-month: ${{ event.cron.utc.month }}

        # The day of the month (1-31) of this invocation of the cron schedule
        utc-day-of-month: ${{ event.cron.utc.day_of_month }}

        # The day of the week (0-6, starting on sunday) of this invocation of the cron schedule
        utc-day-of-week: ${{ event.cron.utc.day_of_week }}

        # The hour (0-23) of this invocation of the cron schedule
        utc-hour: ${{ event.cron.utc.hour }}

        # The minute (0-59) of this invocation of the cron schedule
        utc-minute: ${{ event.cron.utc.minute }}

        ## VCS fields

        # The git ref (e.g. `refs/heads/your-default-branch`)
        git-ref: ${{ event.git.ref }}

        # The git branch name (e.g. `your-default-branch`)
        git-branch: ${{ event.git.branch }}

        # The git sha at the time the cron schedule triggers (the run definition we use will be from this sha)
        git-sha: ${{ event.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 trigger a new run conditionally 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" }}

If you trigger a cron schedule manually in the Cloud UI, Mint will disregard the if condition and assume that you intend to unconditionally start a run.

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