← Back

Run your GitHub Actions workflow on a schedule

When I first heard about Actions in its current form, I was excited about the possibilities - well, now there’s a whole new feature of Actions and I am pumped.

The schedule event lets you define a schedule for your workflow to run on. Using the cron syntax, you basically tell GitHub “run this workflow, independent of any activity on the repo - just run it on my schedule.”

Screenshot of the GitHub Actions UI while adding a scheduled workflow From the GitHub Actions changelog. This UI no longer exists, but it's still a cool image!

The cron syntax

It’s spooky. If you’ve never used it before (I haven’t) it looks different from other things. Let’s dive in!

name: Do things every 5 minutes
on:
  schedule:    - cron: "*/5 * * * *"

This says to run the workflow every five minutes. Cron syntax is separated into five pieces; from the GitHub Docs:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of the week (0 - 6)
│ │ │ │ │                                   
│ │ │ │ │
│ │ │ │ │
* * * * *

An asterisk (*) means that the field is considered “any time” - so * * * * * means every minute of every day. Note that, at least on GitHub, times are based in UTC so you may have to do some timezone conversion!

Some helpful patterns

// Every Monday at 1PM UTC (9AM EST)
0 13 * * 1

// At the end of every day
0 0 * * *

// Every 10 minutes
*/10 * * * *

You can read up on the cron syntax for all the ins-and-outs (goodness knows I’m no expert). I’ve found crontab.guru to be a really helpful resource for visualizing an expression as I write it! ⏰

What you can use it for

Who cares about how it works, what can we do with it? It’s still brand new, but there are already a few really cool Actions designed to work on a schedule:

probot/stale-action

You may already know about probot/stale, a popular Probot App that comments on and closes issues that have become inactive. Well, we designed a hack for it to run on a timer, because we didn’t have anything better. There’s now an Actions equivalent, actions/stale-action.

We can leverage the schedule event to properly run it whenever we want:

name: "Close stale issues"
on:
  schedule:
  - cron: "0 0 * * *"

jobs:
  stale:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/stale@v1.1.0
      with:
        repo-token: ${{ secrets.GITHUB_TOKEN }}
        stale-issue-message: 'Message to comment on stale issues. If none provided, will not mark issues stale'
        stale-pr-message: 'Message to comment on stale PRs. If none provided, will not mark PRs stale'