Skip to content
ado-aw

Writing schedule expressions

Writing schedule expressions

Section titled “Writing schedule expressions”

ado-aw lets you write schedules in a human-readable format instead of hand-writing cron.

You configure schedules under on.schedule.

Start with a simple schedule

Section titled “Start with a simple schedule”
on:
  schedule: daily around 14:00

This says: run every day at roughly 2 PM.

Daily schedules

Section titled “Daily schedules”
on:
  schedule: daily                        # Any time of day (fully scattered)
on:
  schedule: daily around 14:00           # Within ~60 minutes of 2 PM
on:
  schedule: daily around midnight        # Keywords: midnight, noon
on:
  schedule: daily between 09:00 and 17:00  # Any time in a business-hours window

Time values accept 24-hour (14:00), 12-hour (3pm, 11am), or keywords (midnight, noon).

Weekly schedules

Section titled “Weekly schedules”
on:
  schedule: weekly                           # Any day, scattered time
on:
  schedule: weekly on monday                 # Monday, scattered time
on:
  schedule: weekly on friday around 17:00    # Friday, within ~60 min of 5 PM
on:
  schedule: weekly on wednesday between 09:00 and 12:00

Valid weekdays: sunday, monday, tuesday, wednesday, thursday, friday, saturday.

Hourly schedules

Section titled “Hourly schedules”
on:
  schedule: hourly          # Every hour at a scattered minute
on:
  schedule: every 2h        # Every 2 hours at scattered minute
on:
  schedule: every 6 hours   # Short and long forms both accepted

Valid hour intervals: 1, 2, 3, 4, 6, 8, 12 (factors of 24 for even distribution). The minute within each hour is scattered per agent.

Minute intervals

Section titled “Minute intervals”

Minute intervals are scheduled at fixed minutes — they are not scattered like hour and day schedules.

on:
  schedule: every 5 minutes    # Minimum supported interval
on:
  schedule: every 15 minutes
on:
  schedule: every 30m          # Short form supported

The minimum interval is 5 minutes (an Azure DevOps / GitHub Actions constraint).

Multi-day and bi-weekly schedules

Section titled “Multi-day and bi-weekly schedules”
on:
  schedule: every 2 days       # Every N days at scattered time
on:
  schedule: every 2 weeks      # Every N weeks (converted to N×7 days)
on:
  schedule: bi-weekly          # Every 14 days at scattered time
on:
  schedule: tri-weekly         # Every 21 days at scattered time

Add a timezone

Section titled “Add a timezone”

You can add UTC offsets directly in the expression.

on:
  schedule: daily around 14:00 utc+9
on:
  schedule: daily between 09:00 utc-5 and 17:00 utc-5

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

Use this when you want the schedule to reflect a team’s local business hours without manually converting everything to UTC.

Understand scattering

Section titled “Understand scattering”

ado-aw does not always compile a fuzzy schedule to the exact same wall-clock minute you typed.

Instead, it applies scattering: a deterministic offset based on the agent name that spreads runs out to avoid thundering-herd effects.

For example:

on:
  schedule: daily around 14:00

means:

  • stay near 14:00
  • pick a stable offset for this specific agent
  • avoid scheduling every agent at the exact same minute

This helps when many teams use convenient schedule times like midnight, 9 AM, or the top of the hour. Scattering applies to all schedule types except minute intervals, which always run at fixed intervals.

Know what happens at compile time

Section titled “Know what happens at compile time”

Azure DevOps pipelines ultimately need concrete schedule values. During compilation, ado-aw converts the fuzzy expression into a concrete schedule that Azure DevOps can run.

In practice, that means:

  • your human-readable expression is parsed
  • timezone offsets are converted to UTC
  • scattering is applied
  • the compiled pipeline gets a concrete cron-style schedule

You write the friendly expression; the compiler emits the precise schedule.

Schedule specific branches

Section titled “Schedule specific branches”

By default, scheduled runs fire on the main branch only. To specify different branches, use the object form:

on:
  schedule:
    run: weekly on monday around 09:00
    branches:
      - main
      - release/*

This is useful when scheduled automation should run on release branches as well as main.

Practical examples

Section titled “Practical examples”

Business-hours review agent

Section titled “Business-hours review agent”
on:
  schedule: daily between 09:00 and 17:00 utc-5

Use this for an agent that should run once each day during US Eastern business hours.

Weekly maintenance window

Section titled “Weekly maintenance window”
on:
  schedule: weekly on monday around 06:00 utc+1

Use this for a Monday morning maintenance agent.

Regular polling

Section titled “Regular polling”
on:
  schedule: every 6 hours

Use this when you need a repeated check throughout the day.

Frequent monitoring

Section titled “Frequent monitoring”
on:
  schedule: every 15 minutes

Use this for lightweight checks that need to run often. Remember: minute intervals are fixed, not scattered.

Tips for choosing a schedule

Section titled “Tips for choosing a schedule”
  • Use daily around ... for routine maintenance jobs.
  • Use weekly on ... for lower-frequency cleanup or reporting.
  • Use every N hours for repeated monitoring or polling.
  • Use every N minutes for high-frequency, latency-sensitive checks.
  • Add a timezone when the schedule should track local working hours.
  • Let scattering do its job instead of trying to force an exact shared minute across many agents.
  • Prefer hour-based schedules over minute intervals when sub-hourly frequency is not truly required.