Configure Scheduled Trigger in GitHub Actions using Cron expression

There are many times when scheduled triggers are very useful when configuring GitHub Actions workflows. Luckily, GitHub Actions supports the ability to configure scheduled triggers that includes support for using cron expressions to define the schedule timing. In this article, we’ll look at configuring scheduled triggers on GitHub Actions workflows and a few tips on writing cron expressions.

Add a Scheduled Trigger in GitHub Actions

When configuring the triggers for a GitHub Actions workflow, you can configure the workflow to automatically trigger based on a schedule. Within the on section of the YAML workflow, you can add a schedule: node to the YAML configuration for the GitHub Actions workflow.

Here’s a few things to keep in mind when configuring scheduled triggers in a GitHub Actions workflow:

• The timing specified using a cron expression.
• The UTC time zone is used to run the schedule when interpreting the cron expression.
• Scheduled workflows run on the latest commit on the default or base branch of the GitHub repository.
• The shortest interval a workflow can be scheduled is once every 5 minutes.
• Multiple cron expressions can be specified to setup multiple scheduled triggers.

Here’s an example of adding a scheduled trigger using a cron expression that triggers the workflow every day at 5:15 AM and 5:15 PM UTC:

on:
  schedule:
    # YAML treats * as a special character, so the cron expression must be quoted
    - cron: '15 5,17 * * *'

To configure multiple scheduled triggers, then simply add another - cron: node for each schedule needed. Here’s an example of this:

on:
  schedule:
    # Every day at 5:30 AM and 5:30 PM
    - cron: '15 5,17 * * *'
    # Every 15 minutes
    - cron: '*/15 * * * *'

Cron Expression Syntax

CRON expressions are a widely used syntax for specifying time intervals when configuring scheduled tasks. You may have run across them before, as cron expressions are used for a few other systems outside of GitHub Actions. This reuse of cron expressions in the industry makes it more convenient that GitHub Actions reuses this simple to define syntax.

Cron Expression Format

At the core, con expressions are made up of 5 parts. Here’s a definition of what each part defines:

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

• minute (0-59) – specifies the minute of the hour when the task should run. Valid values range from 0 to 59.
• hour (0 – 23) – specifies the hour of the day when the task should run; using a 24-hour format. Valid values range from 0 to 23.
• day of the month (1 – 31) – specifies the day of the month when the task should run. Valid values range from 1 to 31, depending on the month.
• month (1 – 12) – specifies the month when the task should run. Valid values range from 1 to 12.
• day of the week (0 – 6) – specifies the day of the week when the task should run. Valid values range from 0 to 6, where 0 equals Sunday.

Cron Expression Special Characters

When writing cron expressions, there are a few special characters that can be used as well. Here’s the definition of what each of the special characters are:

• Asterisk (*) – represents all possible values for a field. For example, * in the hour field means “every hour”.
• Comma (,) – enables the ability to specify multiple values within a field. For example, 5,17 in the hour field is used to specify “5 AM and 5 PM”.
• Hyphen (-) – specifies a range of values for a field. For example, 1-5 in the hour field means “from 1 AM to 5 AM”.
• Forward slash (/) – enables specifying increments. For example, */15 in the minute field means “every 15 minutes”.

Common Cron Expression Examples

To make things simpler when writing the cron expressions, here’s a few common cron expressions that can be used:

Conclusion

Scheduled triggers in GitHub Actions are a very useful and often required feature for automating routine tasks and CI/CD workflows. Using this feature, you can ensure timely execution of critical workflows, builds, and deployments. This is something that’s important for developers building and pushing code to Production, as well as both DevOps Engineers and Site Reliability Engineers (SREs) whose job is to automate the CI/CD workflows and other tasks.

Original Article Source: Configure Scheduled Trigger in GitHub Actions using Cron expression written by Chris Pietschmann (If you're reading this somewhere other than Build5Nines.com, it was republished without permission.)