Workflow Scheduling Guide

Optimal trigger windows, quota requirements, and timing constraints for every scheduled workflow. Use this when deciding when to manually dispatch a workflow or when to adjust a cron schedule.

How to read this guide

Quota cost — REST API calls consumed per run (mid = typical, high = worst case). Source: config/workflow-quota-costs.yml. GraphQL calls count as 1 REST call regardless of how many repos are queried.

Best window — the UTC hour range where quota headroom is highest and concurrency with other workflows is lowest.

Avoid — hours where the scheduled burst is already high or where a dependency workflow hasn't finished yet.

Quota floor — the minimum remaining quota required before the workflow will run (from min_quota in config/workflow-quota-costs.yml). If quota is below this, the workflow skips itself and waits for the next reset.

Time format note

Per-workflow tables show two schedule columns:

• Schedule (UTC) — 24h UTC, the authoritative cron time
• Schedule (EST) — EST (UTC−5, Nov–Mar). Add 1h for EDT (UTC−4, Mar–Nov).

Example: 09:05 UTC = 4:05 AM EST = 5:05 AM EDT.

The timing map and "Best manual dispatch windows" tables use the full 24h UTC / 12h UTC / 12h ET (EST/EDT) format for completeness.

Daily quota budget

Check current quota before dispatching:

curl -sf -H "Authorization: token $SYNC_TOKEN" \
  "https://api.github.com/rate_limit" | \
  python3 -c "
import sys,json,datetime
d=json.load(sys.stdin)['resources']['core']
print(f\"remaining={d['remaining']}  resets={datetime.datetime.utcfromtimestamp(d['reset']).strftime('%H:%M UTC')}\")
"

Scheduled workflow timing map

All times UTC (24h) with 12h UTC and approximate ET equivalents. [*/2] = every other day (even days of month). (*/30) = every 30 min.

Hour (UTC)     12h UTC        ET (EDT/EST)    Workflows
─────────────────────────────────────────────────────────────────────────────
00:xx          12:xx AM       8:xx PM / 7:xx PM    mirror-to-osp (:13)  sync-in (:37)
                                                    mirror-osp-to-ooc (:45)  auto-merge-prs (:55)
01:xx          1:xx AM        9:xx PM / 8:xx PM    sync-pieroproietti-forks (:07)
                                                    mirror-osp-to-gitlab (:23)
                                                    sync-to-gitlab-variant (:50)
02:xx          2:xx AM        10:xx PM / 9:xx PM   mirror-artifacts (:10)  mirror-orgs-full (:17)
                                                    setup-osp-mirrors (:45)
03:xx          3:xx AM        11:xx PM / 10:xx PM  upstream-prs (:33)  upstream-commits (:47)
04:xx          4:xx AM        12:xx AM / 11:xx PM  git-platform-sync/pull (:27)
                                                    sync-registered-imports (:55)
05:xx          5:xx AM        1:xx AM / 12:xx AM   sync-btrfs-devel-branches (:02)
                                                    rebase-prs [*/2] (:10)
                                                    reconcile-org-refs [*/2] (:50)
06:xx          6:xx AM        2:xx AM / 1:xx AM    queue-manager (*/30)  quota-reserve (*/30)
                                                    [Mon only: update-infra-deps (:11)]
07:xx          7:xx AM        3:xx AM / 2:xx AM    resolve-ci (:43)
08:xx          8:xx AM        4:xx AM / 3:xx AM    check-ci (:05)  inject-badges [*/2] (:15)
09:xx          9:xx AM        5:xx AM / 4:xx AM    git-platform-sync/push (:23)
                                                    check-shell-tools-ci (:30)
10:xx          10:xx AM       6:xx AM / 5:xx AM    sync-in/daily (:15)
                                                    translate-readmes [*/2] (:43)
11:xx          11:xx AM       7:xx AM / 6:xx AM    translate-docs [*/2] (:15)
12:xx–23:xx    12:xx PM–      8:xx AM–             mirror-releases (:03 at 12:xx)
               11:xx PM       7:xx PM              queue-manager + quota-reserve (*/30, all hours)

Per-workflow scheduling reference

Core mirror chain

Mirror chain dependency order: Mirror I-D-1896 → OSP must complete before Mirror OSP → OOC. The :13/:45 stagger (32 min gap) is intentional — do not reduce this gap when manually dispatching both.

CI check + resolver

Note: Check CI Status requires a 1,500 quota floor — the highest of any workflow. If quota is below 1,500 at 09:05 UTC (4:05 AM EST / 5:05 AM EDT), it skips and waits for the next day. Manually dispatch after the 14:00 UTC reset if you need it to run same-day.

Sync operations

README + badge operations

Infrastructure / quota management

Heavy / manual-only workflows

Pre-Flush Prep has the highest floor (3,000) because it validates config, merges PRs, and then dispatches the full flush chain. Trigger it immediately after the 14:00 UTC (9:00 AM EST / 10:00 AM EDT) reset for maximum headroom.

Best manual dispatch windows

Highest quota headroom

Lowest concurrency (fewest parallel jobs)

Avoid

Pre-flush-prep checklist

Before triggering pre-flush-prep.yml:

# 1. Check quota
curl -sf -H "Authorization: token $SYNC_TOKEN" \
  "https://api.github.com/rate_limit" | \
  python3 -c "
import sys,json,datetime
d=json.load(sys.stdin)['resources']['core']
reset=datetime.datetime.utcfromtimestamp(d['reset']).strftime('%H:%M UTC')
ok = '✅' if d['remaining'] >= 3000 else '❌'
print(f\"{ok} remaining={d['remaining']} (need 3000)  resets={reset}\")
"

# 2. Run validators locally
python3 scripts/validate-workflow-guards.py
python3 scripts/validate-gitlab-subgroups.py config/gitlab-subgroups.yml
python3 scripts/validate-registered-imports.py registered-imports.json
python3 scripts/validate-priority-tiers.py config/workflow-priority-tiers.yml
python3 scripts/validate-cost-profiles.py config/workflow-cost-profiles.yml

# 3. Check for open PRs that would block the flush
gh pr list --state open --json number,title,mergeable

Ideal trigger time:

5 minutes after the hourly reset — maximum quota headroom before any scheduled workflows consume from the fresh bucket.

Quota drain reduction history

Current baseline: ~3,200 calls/day (~133/hr average).

Remaining quota reduction opportunities

These are known but not yet applied — each has a trade-off noted.

Speed improvement opportunities

Scripts

Workflows

Runner minutes

Public repos on GitHub get unlimited free runner minutes. If this repo is public, runner minutes are not a constraint. If private:

• Current worst-case estimate: ~8,000 min/month (well over 2,000 free tier)
• Self-hosted runner eliminates the cap entirely
• Alternatively: reduce timeout-minutes on workflows that consistently finish in < 5 min but have 30 min timeouts — this doesn't save minutes (billing is actual runtime, not timeout) but prevents runaway jobs

Workflows with oversized timeouts relative to typical runtime: