Schedule GitHub Actions Using CRON Expressions

Sarah Lean -

You can trigger GitHub Actions to run on several 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 uses CRON expressions to configure a GitHub Action on a given schedule.

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 as CRON jobs or CRON tasks.  

The CRON syntax can sometimes be confusing when first encountered.  Five sections can be configured within the CRON syntax.  You can specify the day of the 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 into the website, and it will decipher what that schedule would do, or equally, you can use it to build the correct 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 a trigger on a schedule.  The CRON job I have set will run at 11 am on every day of the week from Monday through Friday.

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

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

Check out my other blogs on GitHub Action uses and features.