GitHub Actions Cron: Schedule
Workflows Step by Step

Scheduled workflows are one of the most powerful features of GitHub Actions. They let you run any automation on a time-based trigger — nightly builds, weekly dependency updates, monthly cleanup jobs, daily health checks, and more — without any external cron service or infrastructure.

This guide covers everything you need to know: the syntax, how to read cron expressions, 12 copy-paste examples for common schedules, and the gotchas that trip up almost every developer the first time.

1. Basic syntax: on: schedule

A scheduled GitHub Actions workflow uses the on: schedule: trigger in your workflow YAML file. Here's the minimal complete example:

# .github/workflows/daily-job.yml
name: Daily job

on:
  schedule:
    - cron: '0 9 * * *'  # Every day at 9:00 AM UTC

jobs:
  run-daily:
    runs-on: ubuntu-latest
    steps:
      - name: Run my task
        run: echo "Running daily at 9 AM UTC"

The cron: value is a standard 5-field cron expression in quotes. That's all you need to get a scheduled workflow running.

Multiple schedules

You can specify multiple cron expressions for the same workflow by adding multiple entries under schedule::

on:
  schedule:
    - cron: '0 9 * * 1-5'   # Weekdays at 9 AM UTC
    - cron: '0 12 * * 0,6'  # Weekends at noon UTC

2. Understanding the 5-field cron format

A GitHub Actions cron expression has exactly 5 space-separated fields. Here's the structure:

  ┌──────────── minute (0–59)
  │  ┌─────────── hour (0–23)
  │  │  ┌────────── day of month (1–31)
  │  │  │  ┌──────── month (1–12)
  │  │  │  │  ┌───── day of week (0–6, Sunday=0)
  │  │  │  │  │
  *  *  *  *  *

Special characters

• * — matches any value ("every minute", "every hour", "every day")
• , — separates multiple values: 1,3,5 means 1st, 3rd, and 5th
• - — defines a range: 1-5 means 1 through 5
• / — step values: */15 in the minute field means every 15 minutes; */2 in the hour field means every 2 hours

3. 12 real-world GitHub Actions cron examples

on:
  schedule:
    - cron: '0 0 * * *'

on:
  schedule:
    - cron: '0 9 * * 1-5'

on:
  schedule:
    - cron: '0 8 * * 1'

on:
  schedule:
    - cron: '0 6 1 * *'

on:
  schedule:
    - cron: '0 */6 * * *'

on:
  schedule:
    - cron: '*/30 * * * *'

on:
  schedule:
    - cron: '0 15 * * 1-5'  # 11 AM Eastern, 8 AM Pacific

on:
  schedule:
    - cron: '0 9,17 * * *'  # 9 AM and 5 PM UTC

on:
  schedule:
    - cron: '0 2 * * 0'  # Sunday at 2 AM UTC

on:
  schedule:
    - cron: '0 12 15,28 * *'

on:
  schedule:
    - cron: '0 9 1 1,4,7,10 *'  # Quarterly

on:
  schedule:
    - cron: '30 * * * *'  # Every hour at :30

4. Critical gotchas you must know

5. Combining schedule with other triggers

You can — and often should — combine schedule: with other triggers in the same workflow. The most common patterns:

Schedule + workflow_dispatch (manual override)

Adding workflow_dispatch: lets you run the workflow manually from the GitHub Actions UI when you need to trigger it outside the schedule. This is almost always a good idea for scheduled workflows.

on:
  schedule:
    - cron: '0 2 * * 0'  # Auto: every Sunday at 2 AM UTC
  workflow_dispatch:    # Manual: run anytime from the Actions tab

Schedule + push (also runs on deploy)

Run the workflow on both a schedule and on every push to main:

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * *'  # Nightly, and also on every push to main

Checking how the workflow was triggered

Inside your workflow, use github.event_name to check whether the run was triggered by a schedule or another event:

- name: Check trigger
  run: |
    if [ "${{ github.event_name }}" = "schedule" ]; then
      echo "Running on schedule"
    else
      echo "Triggered manually or by push"
    fi

6. Debugging scheduled workflows

My workflow isn't running — checklist

1. Is the workflow file on the default branch? Check that .github/workflows/your-workflow.yml is merged to main/master. Scheduled workflows on other branches don't run.
2. Is the cron expression valid? A malformed expression (wrong number of fields, invalid values) will cause the workflow to fail silently. Validate it here.
3. Is the repository inactive? Go to Actions → check if the workflow shows as "disabled". Inactive repos have schedules automatically disabled after 60 days.
4. Is it just delayed? GitHub schedules can run 5–30 minutes late. Check if the run appeared eventually.
5. Are there YAML syntax errors? A YAML error anywhere in the file will prevent the workflow from being registered. Check Actions → the workflow name for parse errors.

Viewing scheduled run history

Go to your repository → Actions tab → click on the specific workflow name in the left sidebar. You'll see all runs including scheduled ones, with their trigger source, duration, and status. The "Trigger" column shows "schedule" for cron-triggered runs.

Testing a scheduled workflow without waiting

Add workflow_dispatch: to your triggers (as shown above), then go to Actions → your workflow → Run workflow. This triggers the exact same job steps as the scheduled run, letting you test the logic immediately.

on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:  # Add this to test immediately

7. Frequently asked questions