GitHub Actions Workflow Syntax: on: schedule with Examples

Introduction

GitHub Actions is a powerful CI/CD tool that allows developers to automate tasks within their software development lifecycle directly from their GitHub repositories. The core of this automation lies in the workflow files, which are defined using a specific syntax. In this blog post, we will explore the on: schedule event in the GitHub Actions Workflow Syntax, its usage, and provide examples.

Understanding the `on: schedule` Event

In GitHub Actions, workflows are triggered by specific events. The on: schedule event allows you to trigger a workflow at specified times. This is done using POSIX cron syntax, and can be particularly useful when you want to automate tasks on a regular schedule, such as nightly builds, periodic cleanups, or regular data updates.

Usage of the `on: schedule` Event

The on: schedule event is defined in the workflow file right after the on keyword. Here’s a basic example of how to use the on: schedule event:

name: Scheduled Workflow
on: 
  schedule:
    - cron:  '0 0 * * *'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Run a one-line script
        run: echo This workflow runs every day at midnight!

name: Scheduled Workflow

on:

schedule:

- cron: '0 0 * * *'

jobs:

build:

runs-on: ubuntu-latest

steps:

- name: Checkout code

uses: actions/checkout@v2

- name: Run a one-line script

run: echo This workflow runs every day at midnight!

In this example, the workflow is named “Scheduled Workflow”. This workflow is triggered every day at midnight. The workflow has one job named build that runs on the latest version of Ubuntu. This job has two steps:

Checkout code: This step uses the actions/checkout@v2 action to checkout the repository’s code onto the runner.
Run a one-line script: This step runs a script that simply echoes a message indicating that the workflow runs every day at midnight.

Understanding POSIX cron syntax

The POSIX cron syntax is a powerful and flexible way to schedule tasks. It uses five fields separated by spaces, representing different units of time. Here’s what each field represents:

Minute: The minute field can have values from 0 to 59.
Hour: The hour field can have values from 0 to 23.
Day of the month: This field can have values from 1 to 31.
Month: This field can have values from 1 (January) to 12 (December).
Day of the week: This field can have values from 0 (Sunday) to 6 (Saturday).

For example, the cron schedule 0 0 * * * runs a workflow every day at midnight.

Common Questions and Answers

Q: How do I specify the schedule for the on: schedule event?

A: The schedule is specified using POSIX cron syntax. The syntax is as follows: cron: 'm h d m w', where m is minute (0 – 59), h is hour (0 – 23), d is day of the month (1 – 31), m is month (1 – 12), and w is day of the week (0 – 6, where 0 is Sunday).

Q: Can I use the on: schedule event in conjunction with other events?

A: Yes, you can specify multiple events to trigger the workflow. For example, you could have a workflow that runs on both push and schedule events.

Conclusion

The on: schedule event in GitHub Actions Workflow Syntax is a powerful tool that allows you to automate tasks on a regular schedule. By understanding and effectively using this event, you can greatly enhance your automation capabilities.