Scheduled Workflows

Scheduled Workflows

Scheduled workflows let you run a workflow on a recurring cron schedule instead of (or in addition to) responding to repository events. This is useful for tasks like nightly validation runs, weekly housekeeping jobs, or periodic backups of generated artifacts.

How It Works

To turn a workflow into a scheduled workflow, add a schedule: entry to its on: block with one or more cron expressions:

name: Nightly Validation
on:
  schedule:
    - cron: '0 4 * * *'   # Every day at 04:00 UTC
jobs:
  validate:
    runs-on: windows10-S5K
    steps:
      - uses: actions/checkout@v4
      - run: echo "Running nightly validation..."

Copia evaluates due schedules once per minute and queues a new run for each schedule whose next fire time has elapsed. Scheduled runs are queued with the schedule event and use the latest commit on the repository's default branch as their checkout target.

Scheduled workflows are only registered from workflow files on the default branch. Adding a schedule: trigger on any other branch has no effect until the change is merged.

Lifecycle

1

Registration

When you push a workflow file containing a schedule: trigger to the default branch, Copia parses it and registers the cron specs. Any previously registered schedules for the repository are replaced.

2

Firing

Once per minute, Copia looks for any schedule whose next fire time is in the past. For each match, it queues a new run against the default branch and advances the schedule to its next fire time.

3

Refresh

Each subsequent push to the default branch refreshes the registered schedules from the new commit. If a workflow's schedule: block is removed or the workflow file is deleted, that schedule is dropped on the next default-branch push.

Cron Syntax

Schedules use the standard five-field cron format:

┌───────────── minute (0–59)
│ ┌─────────── hour (0–23)
│ │ ┌───────── day of month (1–31)
│ │ │ ┌─────── month (1–12 or JAN–DEC)
│ │ │ │ ┌───── day of week (0–6 or SUN–SAT)
│ │ │ │ │
* * * * *

The following shorthand descriptors are also supported:

Descriptor	Equivalent to	Description
@yearly / @annually	0 0 1 1 *	Once a year on January 1
@monthly	0 0 1 * *	On the first of every month
@weekly	0 0 * * 0	Every Sunday at midnight
@daily / @midnight	0 0 * * *	Every day at midnight
@hourly	0 * * * *	At the start of every hour

The smallest scheduling granularity is one minute. Sub-minute schedules are not supported.

Timezones

Cron expressions are evaluated in UTC by default. To pin a schedule to a different timezone, prefix the expression with TZ= (or CRON_TZ=) and a valid IANA timezone name:

on:
  schedule:
    - cron: 'TZ=America/Chicago 0 6 * * 1-5'   # 6:00 AM Central, Mon–Fri

Examples

Multiple schedules on one workflow

You can list more than one cron expression. The workflow will fire once for each schedule whose time has come.

name: Periodic Checks
on:
  schedule:
    - cron: '*/15 * * * *'  # Every 15 minutes
    - cron: '0 0 * * 0'     # Plus a deeper sweep every Sunday at midnight UTC
jobs:
  ping:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Tick at $(date -u)"

Combining scheduled and event triggers

A scheduled trigger can coexist with normal event triggers in the same workflow.

name: Build and Nightly Smoke Test
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 2 * * *'   # Nightly at 02:00 UTC
jobs:
  smoke:
    runs-on: windows10-S5K
    steps:
      - uses: actions/checkout@v4
      - name: Run smoke tests
        run: ./scripts/smoke.sh

You can detect which trigger started a run via the github.event_name context variable, which will be set to schedule for scheduled runs:

steps:
  - name: Send nightly report
    if: github.event_name == 'schedule'
    run: ./scripts/send-report.sh

Business-hours schedule with a custom timezone

name: Hourly Health Check
on:
  schedule:
    - cron: 'TZ=America/New_York 0 9-17 * * 1-5'   # Top of every hour, 9 AM – 5 PM ET, weekdays
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - run: ./scripts/health-check.sh

Notes and Limitations

• Only the default branch is scheduled. Schedules defined on feature branches are not active until merged.

• Disabling Actions on a repository pauses its schedules. They will not fire while Actions is disabled, but the schedule rows remain registered and will resume firing once Actions is re-enabled.

• Archived repositories do not fire scheduled workflows.

• Missed runs are not backfilled. If your Copia instance is down when a schedule was due to fire, that occurrence is skipped — the schedule will simply fire at its next scheduled time after the instance recovers.

• Cron expressions are evaluated in UTC unless a TZ= prefix is provided. Daylight saving transitions may cause a schedule to skip or repeat an hour in the affected timezone.