Skip to content

schedule-syntax.md

Latest commit

 

History

History
114 lines (84 loc) · 4.13 KB

schedule-syntax.md

File metadata and controls

114 lines (84 loc) · 4.13 KB
Raw

Schedule Syntax (Fuzzy Schedule Time Syntax)

Part of the ado-aw documentation.

Schedule Syntax (Fuzzy Schedule Time Syntax)

The on.schedule field supports a human-friendly fuzzy schedule syntax that automatically distributes execution times to prevent server load spikes. The syntax is based on the Fuzzy Schedule Time Syntax Specification.

Schedule is configured under the on: key:

on:
  schedule: daily around 14:00

Daily Schedules

schedule: daily                          # Scattered across full 24-hour day
schedule: daily around 14:00             # Within ±60 minutes of 2 PM
schedule: daily around 3pm               # 12-hour format supported
schedule: daily around midnight          # Keywords: midnight, noon
schedule: daily between 9:00 and 17:00   # Business hours (9 AM - 5 PM)
schedule: daily between 22:00 and 02:00  # Overnight (handles midnight crossing)

Weekly Schedules

schedule: weekly                              # Any day, scattered time
schedule: weekly on monday                    # Monday, scattered time
schedule: weekly on friday around 17:00       # Friday, within ±60 min of 5 PM
schedule: weekly on wednesday between 9:00 and 12:00  # Wednesday morning

Valid weekdays: sunday, monday, tuesday, wednesday, thursday, friday, saturday. Short aliases are also accepted: sun, mon, tue/tues, wed, thu/thurs, fri, sat.

Hourly Schedules

schedule: hourly       # Every hour at a scattered minute
schedule: every 1h     # Equivalent to hourly
schedule: every 2h     # Every 2 hours at scattered minute
schedule: every 2 hours # Long form also supported
schedule: every 6h     # Every 6 hours at scattered minute

Valid hour intervals: 1, 2, 3, 4, 6, 8, 12 (factors of 24 for even distribution)

Minute Intervals (Fixed, Not Scattered)

schedule: every 5 minutes     # Every 5 minutes (minimum interval)
schedule: every 5 min         # Singular/short forms also supported
schedule: every 15 minutes    # Every 15 minutes
schedule: every 30m           # Short form supported

Note: Minimum interval is 5 minutes (GitHub Actions/Azure DevOps constraint). Accepted minute units: minutes, minute, mins, min, m.

Special Periods

schedule: bi-weekly       # Every 14 days at scattered time
schedule: biweekly        # No-hyphen alias
schedule: tri-weekly      # Every 21 days at scattered time
schedule: triweekly       # No-hyphen alias
schedule: every 2 days    # Every N days at scattered time
schedule: every 2d        # Short day form
schedule: every 2 weeks   # Every N weeks (converted to N×7 days) at scattered time
schedule: every 2w        # Short week form

Accepted day/week units: days, day, d, weeks, week, w.

Timezone Support

All time specifications support UTC offsets for timezone conversion:

schedule: daily around 14:00 utc+9      # 2 PM JST → 5 AM UTC
schedule: daily around 3pm utc-5        # 3 PM EST → 8 PM UTC
schedule: daily around 09:00 utc        # Bare UTC means UTC+0
schedule: daily between 9am utc+05:30 and 5pm utc+05:30  # IST business hours

Supported offset formats: utc, utc+9, utc-5, utc+05:30, utc-08:00

How Scattering Works

The compiler uses a deterministic hash of the agent name to scatter execution times:

  • Same agent always gets the same execution time (stable across recompilations)
  • Different agents get different times (distributes load)
  • Times stay within the specified constraints (around, between, etc.)

This prevents load spikes that occur when many workflows use convenient times like midnight or on-the-hour.

Schedule Branch Filtering

By default, when no branches are explicitly configured, the schedule fires only on the main branch. To specify different branches, use the object form:

# Default: fires only on main branch (string form)
schedule: daily around 14:00

# Custom branches: fires on listed branches (object form)
schedule:
  run: daily around 14:00
  branches:
    - main
    - release/*