Schedule GitHub Actions Using CRON Expressions

You can trigger GitHub Actions to run on a number of different events. The most common would be running when you push changes to your repository. Also you may want to trigger an Action to run on pull requests.

When building Actions you may want to run them on a defined schedule. This tutorial shows you how to configure a GitHub Action on a given schedule using CRON expressions.

Can you schedule GitHub Actions?

Yes, yes you can. You have the option to trigger a GitHub Actions on a schedule an example could be:

name: Test Build

on:  
  push:
  pull_request:
  schedule:
    - cron: '00 1 * * 1'  # At 01:00 on Mondays.

What is CRON?

CRON is a command line utility that is used to schedule jobs. You'll hear it referred to CRON jobs or CRON tasks.

The CRON syntax can sometimes be confusing when first encountered. There are five sections that can be configured within the CRON syntax. You can specify day of week, month, day of the month, hour and minute.

This isn't something you need to commit to memory but being able to read the syntax is useful. Below is a great diagram to show you how the syntax is broken down.

# ┌───────────── minute (0 - 59)
# │ ┌───────────── hour (0 - 23)
# │ │ ┌───────────── day of the month (1 - 31)
# │ │ │ ┌───────────── month (1 - 12)
# │ │ │ │ ┌───────────── day of the week (0 - 6)
# │ │ │ │ │                       
# │ │ │ │ │
# │ │ │ │ │
# * * * * * <command to execute>

I love to use the website https://crontab.guru/. You can put the syntax in to the website and it will decipher what that schedule would do, or equally you can use it to build the right syntax for the schedule you want to execute.

What is the GitHub Actions CRON syntax?

I want to show you an example of a GitHub Actions workflow including a CRON schedule.

name: Trigger Action on a CRON Schedule

on:
  schedule:
    # Runs "At 11:00 on every day-of-week from Monday through Friday"
    - cron: '0 11 * * 1-5'

jobs:
  build:
    name: Trigger Code Checkout
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

The above GitHub Actions workflow will open trigger on a schedule. The CRON job I have set will run at 11am on every day-of-week from Monday through Friday.

The workflow then will run the Code Checkout step on a Ubuntu runner.

It's a straight forward workflow, but it triggers using a CRON schedule rather than on a push to GitHub or on a pull request.

Be sure to check out the other blogs I have written on GitHub Action uses and features.