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'

electron/unreleased

Every Monday, this brand new Action pings a team in the Electron Slack workspace with information about the commits that have been merged to a release branch but are not in a published release yet.

This will help them keep track of new features & bug fixes that folks are waiting for, but have yet to be released in a new version of Electron. I forget about merged work all the time with projects way, way smaller - this kind of automation is super exciting ✨

JasonEtco/create-an-issue

An Action made by one brilliant blog author, create-an-issue, does what it says on the box. When I first made it many moons ago, I had a feeling that scheduled Actions would be a thing one day, so I built in support for dates. This lets us create an issue on a schedule, with helpful date stamps. Here's a workflow that I made for my team's weekly meeting notes:

name: Create our Weekly Meeting notes issue
on:
schedule:
- cron: '0 14 * * 1'
jobs:
issue:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- uses: JasonEtco/create-an-issue@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
filename: .github/ISSUE_TEMPLATE/meeting-notes.md

And the meeting-notes.md issue template:

---
name: Weekly Meeting Notes
about: Used for taking notes in our daily standups, with a new issue every week.
title: "Weekly Meeting Notes: {{ date | date('MMMM Do') }} - {{ date | date('add', 5, 'days') | date('Do') }}"
labels:
- "Meeting 💬"

---

### Monday, {{ date | date('MMM Do') }}

I've done some real fanciness with the title by having the dates at the start and end of the week - here's what the generated issue looks like:

image

This is a small but helpful piece of automation that takes one task off of my todo list 🎉

Thinking ahead

So the schedule trigger is awesome, but it doesn't need to stop here. Actions already works with a list of webhook event types, and schedule isn't on that list - that means that GitHub Actions has the ability to register and act upon custom events. Going even further, the event isn't static - it's parsed with granular information about the event:

schedule:
- cron: "* * * * *"

This opens up a whole new world of possibilities for more granular events (these are imaginary):

# Matches @-mentions in an issue comment
mention:
- user: JasonEtco
- team: github/cool-people

# Matches slash commands, like `/deploy` in an issue comment
command: deploy

Who knows if any of those will be implemented, or if they're even a good idea! The point here is that schedule proves that Actions has an opportunity to do even more than the already huge list of webhook events allows for!


So go forth and make scheduled workflows ✌️ Let me know how it goes!