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."

From the GitHub Actions changelog. This UI no longer exists, but it's still a cool image!

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!

// 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! ⏰

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:

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'

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 ✨

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:

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

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!