Schedule Syntax

This reference documents the complete schedule syntax supported by GitHub Agentic Workflows, including fuzzy schedules (recommended), time constraints, and standard cron expressions.

Overview

GitHub Agentic Workflows supports human-friendly schedule expressions that are automatically converted to cron format. The system includes two types of schedules:

• Fuzzy schedules (recommended) - Automatically scatter execution times across workflows to prevent load spikes
• Fixed schedules - Run at specific times, but create server load when many workflows use the same time

Tip

Use Fuzzy Schedules Fuzzy schedules distribute workflow execution times deterministically across all workflows in your repository. Each workflow gets a unique, consistent execution time that never changes across recompiles, preventing server load spikes.

Quick Reference

Pattern	Example	Result	Type
Daily	daily	Scattered time	Fuzzy
	daily around 14:00	13:00-15:00 window	Fuzzy
	daily between 9:00 and 17:00	9am-5pm window	Fuzzy
Hourly	hourly	Scattered minute	Fuzzy
	every 2h	Every 2 hours	Fuzzy
Weekly	weekly	Scattered day/time	Fuzzy
	weekly on monday	Monday, scattered time	Fuzzy
	weekly on friday around 5pm	Friday 4pm-6pm	Fuzzy
Bi-weekly	bi-weekly	Scattered across 2 weeks	Fuzzy
Tri-weekly	tri-weekly	Scattered across 3 weeks	Fuzzy
Intervals	every 10 minutes	Every 10 minutes	Fixed
	every 2 days	Every 2 days	Fixed
Cron	0 9 * * 1	Standard cron	Fixed

Fuzzy Schedules (Recommended)

Fuzzy schedules automatically distribute workflow execution times to prevent server load spikes. The scattering is deterministic based on the workflow file path, so each workflow consistently gets the same execution time.

Daily Schedules

Run once per day at a scattered time:

on:
  schedule: daily

Each workflow gets a unique time like 43 5 * * * (5:43 AM).

Daily with Time Constraints

Use around for a ±1 hour window or between for custom ranges:

on:
  schedule: daily around 14:00     # 13:00-15:00
  schedule: daily around 3pm       # 2pm-4pm
  schedule: daily around noon      # 11am-1pm
  schedule: daily between 9:00 and 17:00    # Business hours (9am-5pm)
  schedule: daily between 22:00 and 02:00   # Crossing midnight (10pm-2am)

Special time keywords: midnight (00:00), noon (12:00)

Hourly Schedules

on:
  schedule: hourly    # Runs every hour with scattered minute (e.g., 58 */1 * * *)

Each workflow gets a consistent minute offset (0-59) to prevent simultaneous execution.

Interval Schedules

on:
  schedule: every 2h    # Every 2 hours at scattered minute (e.g., 53 */2 * * *)
  schedule: every 6h    # Every 6 hours at scattered minute (e.g., 12 */6 * * *)

Supported intervals: 1h, 2h, 3h, 4h, 6h, 8h, 12h

Weekly Schedules

on:
  schedule: weekly              # Scattered day/time (e.g., 43 5 * * 1)
  schedule: weekly on monday    # Monday at scattered time (e.g., 43 5 * * 1)
  schedule: weekly on friday    # Friday at scattered time (e.g., 18 14 * * 5)

Supported weekdays: sunday, monday, tuesday, wednesday, thursday, friday, saturday

Weekly with Time Constraints

on:
  schedule: weekly on monday around 09:00   # Monday 8am-10am
  schedule: weekly on friday around 5pm     # Friday 4pm-6pm

Bi-weekly and Tri-weekly Schedules

on:
  schedule: bi-weekly     # Every 14 days at scattered time (e.g., 43 5 */14 * *)
  schedule: tri-weekly    # Every 21 days at scattered time (e.g., 18 14 */21 * *)

Each workflow gets a deterministic time that repeats every 14 or 21 days, scattered across the full period to distribute load.

UTC Offset Support

Use utc+N or utc-N (or utc+HH:MM) to convert local times to UTC:

on:
  schedule: daily around 14:00 utc+9                  # 2:00 PM JST
  schedule: daily around 9am utc-5                    # 9:00 AM EST
  schedule: daily between 9am utc-5 and 5pm utc-5     # Business hours EST
  schedule: weekly on monday around 08:00 utc+05:30   # Monday 8:00 AM IST

Common offsets: PT/PST/PDT (utc-8/utc-7), EST/EDT (utc-5/utc-4), JST (utc+9), IST (utc+05:30)

Fixed Schedules

For fixed-time schedules, use standard cron syntax:

on:
  schedule:
    - cron: "0 2 * * *"    # Daily at 2:00 AM UTC
    - cron: "30 6 * * 1"   # Monday at 6:30 AM UTC
    - cron: "0 9 15 * *"   # 15th of month at 9:00 AM UTC

Tip

Fixed schedules create load spikes. Use fuzzy schedules like daily or daily around 14:00 to distribute execution times.

Interval Schedules

Use every N [unit] syntax for various intervals:

on:
  # Minutes (minimum 5 minutes, fixed time)
  schedule: every 5 minutes    # */5 * * * *
  schedule: every 10m          # */10 * * * * (short format)

  # Hours (fuzzy - scattered minute)
  schedule: every 1h           # 58 */1 * * * (minute 58)
  schedule: every 2 hours      # 53 */2 * * * (minute 53)

  # Days (fixed time)
  schedule: every 1d           # 0 0 * * * (midnight UTC)
  schedule: every 2 days       # 0 0 */2 * *

  # Weeks (fixed time)
  schedule: every 1w           # 0 0 * * 0 (Sunday midnight)
  schedule: every 2w           # 0 0 */14 * *

  # Months (fixed time)
  schedule: every 1mo          # 0 0 1 * * (1st of month)
  schedule: every 2mo          # 0 0 1 */2 *

Valid minute intervals: 5m, 10m, 15m, 20m, 30m Valid hour intervals: 1h, 2h, 3h, 4h, 6h, 8h, 12h

Note

GitHub Actions enforces a minimum schedule interval of 5 minutes.

Time Formats

Supports 24-hour (HH:MM), 12-hour (Ham, Hpm), and keywords (midnight, noon):

Examples:
  00:00, 09:30, 14:00    # 24-hour format
  1am, 3pm, 11pm         # 12-hour format
  midnight, noon         # Keywords

With UTC offset:
  14:00 utc+9            # JST to UTC
  3pm utc-5              # EST to UTC
  9am utc+05:30          # IST to UTC

Standard Cron Expressions

Format: minute hour day-of-month month day-of-week

on:
  schedule:
    - cron: "0 9 * * 1"       # Monday at 9:00 AM
    - cron: "*/15 * * * *"    # Every 15 minutes
    - cron: "0 0 * * *"       # Daily at midnight
    - cron: "0 14 * * 1-5"    # Weekdays at 2:00 PM

See GitHub’s cron syntax documentation.

Multiple Schedules

on:
  schedule:
    - cron: daily
    - cron: weekly on monday
    - cron: "0 0 15 * *"      # Monthly on 15th

Shorthand Format

Use on: daily as shorthand, which automatically expands to include both schedule and workflow_dispatch:

on: daily

# Expands to:
on:
  schedule:
    - cron: "FUZZY:DAILY * * *"
  workflow_dispatch:

Best Practices

Recommended: Use fuzzy schedules to prevent load spikes

on: daily                                   # ✅ Scattered time
on: daily between 9:00 and 17:00            # ✅ Business hours
on: daily between 9am utc-5 and 5pm utc-5   # ✅ Regional times
on: weekly on monday                        # ✅ Scattered time
on: every 2h                                # ✅ Scattered minute

Avoid: Fixed times that create load spikes

on:
  schedule:
    - cron: "0 0 * * *"     # ❌ All workflows run at same time
    - cron: "0 */2 * * *"   # ❌ All workflows run at minute 0

How Scattering Works

Fuzzy schedules use a deterministic FNV-1a hash of the workflow identifier (repository slug + file path) to assign unique execution times. The same workflow always gets the same time across recompiles.

# Example: on: daily
Workflow A: 43 5 * * *   (5:43 AM)
Workflow B: 17 14 * * *  (2:17 PM)
Workflow C: 8 20 * * *   (8:08 PM)

The algorithm includes the repository slug, so workflows with the same name in different repositories get different execution times, distributing load across an entire organization.

Validation & Warnings

The compiler warns about patterns that create load spikes:

⚠ Schedule uses fixed daily time (0:0 UTC). Consider using fuzzy
  schedule 'daily' instead to distribute workflow execution times.

⚠ Schedule uses hourly interval with fixed minute offset (0).
  Consider using fuzzy schedule 'every 2h' instead.

⚠ Schedule uses fixed weekly time (Monday 6:30 UTC). Consider using
  fuzzy schedule 'weekly on monday' instead.

Related Documentation

• Triggers - Complete trigger configuration
• Frontmatter - Workflow configuration reference
• GitHub Actions Schedule Events - GitHub’s schedule documentation