Document Actions schedule latency mitigation (#492)
Co-authored-by: jmservera <jmservera@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Juan Manuel Servera committed
Jun 15, 2026 at 19:01 UTC
4444fecdb3d27d5f2b28c81c90f187ac75ea415b
6 files changed
+57
-16
.github/workflows/crawl-and-publish.yml
+4
-1
@@ -2,7 +2,10 @@ name: Crawl and publish weekly data
2
3
on:
4
schedule:
5
- # Sundays at 11:53 UTC (GitHub can delay scheduled workflows during peak load)
5
+ # Sundays at 11:53 UTC as the low-effort default. On GitHub-hosted
6
+ # runners this schedule is best-effort and can start hours late; see
7
+ # docs/operator-guide.md#schedule-latency-and-mitigation-ladder and use
8
+ # workflow_dispatch from an external scheduler if punctuality matters.
9
- cron: '53 11 * * 0'
10
workflow_dispatch:
11
inputs:
README.md
+5
-3
@@ -14,7 +14,7 @@ Claracle solves the information overload problem in open-source development. Eac
14
4. **Publishes** to GitHub Pages with RSS feeds for consumption
15
5. **Reskills** every 5 runs to improve its own analysis quality
16
17
-Result: Curated tech trend insights delivered automatically every Monday.
17
+Result: Curated tech trend insights delivered automatically every week.
18
19
## Architecture
20
@@ -101,7 +101,7 @@ JSON Markdown Hugo Pages Improvements
101
102
## Automated weekly pipeline
103
104
-`.github/workflows/crawl-and-publish.yml` runs the full weekly automation every Monday at 06:53 UTC:
104
+`.github/workflows/crawl-and-publish.yml` runs the full weekly automation on a best-effort Sunday schedule at 11:53 UTC:
105
106
1. **Crawl:** GitHub API → `data/raw/YYYY-WNN.json`; external RSS feeds → `data/raw/YYYY-WNN-external-news.json`
107
2. **Analyze:** Copilot → `data/analyzed/YYYY-WNN-summary.md`
@@ -112,8 +112,10 @@ JSON Markdown Hugo Pages Improvements
112
113
### Schedule and manual runs
114
115
-- **Automated schedule:** Monday 06:53 UTC (`53 6 * * 1`)
115
+- **Automated schedule:** Sunday 11:53 UTC (`53 11 * * 0`) on GitHub-hosted runners
116
+- **Timing expectation:** GitHub Actions `schedule` is best-effort on shared runners; this repo has observed multi-hour delays on scheduled starts
117
- **Manual trigger:** `gh workflow run crawl-and-publish.yml` or GitHub Actions UI
118
+- **If punctuality matters:** trigger the existing `workflow_dispatch` from an external scheduler; see [`docs/operator-guide.md#schedule-latency-and-mitigation-ladder`](docs/operator-guide.md#schedule-latency-and-mitigation-ladder)
119
120
### Required secrets
121
docs/matrix-crawl-runbook.md
+1
-1
@@ -16,7 +16,7 @@ This runbook covers how to trigger, monitor, and troubleshoot the SquadScope mat
16
17
### Scheduled (default)
18
19
-The `crawl-and-publish.yml` workflow runs automatically every Monday at 06:53 UTC via cron schedule.
19
+The `crawl-and-publish.yml` workflow runs automatically on Sundays at 11:53 UTC (`53 11 * * 0`). Treat this as a best-effort GitHub-hosted schedule, not an exact start minute; scheduled runs can start hours late on shared runners. For the supported mitigation ladder (manual trigger, external scheduler -> `workflow_dispatch`, optional self-hosted runners), see [`docs/operator-guide.md#schedule-latency-and-mitigation-ladder`](operator-guide.md#schedule-latency-and-mitigation-ladder).
20
21
### Manual dispatch
22
docs/operator-guide.md
+35
-4
@@ -132,9 +132,40 @@ This generates the `public/` directory with optimized static assets.
132
133
### Option A: Automatic scheduling (default)
134
135
-The pipeline runs automatically every **Monday at 06:53 UTC** via `.github/workflows/crawl-and-publish.yml`.
135
+The pipeline runs automatically on Sundays at **11:53 UTC** (`53 11 * * 0`) via `.github/workflows/crawl-and-publish.yml`.
136
137
-You don't need to do anything. Go to your repo's **Actions** tab to monitor runs.
137
+GitHub-hosted scheduled workflows are **best effort**, not an exact-time SLA, so a cron match does not guarantee the job will start at 11:53. Go to your repo's **Actions** tab to monitor runs.
138
+
139
+#### Schedule latency and mitigation ladder
140
+
141
+SquadScope treats GitHub Actions `schedule` on shared runners as a convenience default, not as a punctual trigger. This repository has already observed multi-hour delays on the previous Monday `06:53 UTC` slot:
142
+
143
+- 2026-05-25: started at **11:55 UTC**
144
+- 2026-06-01: started at **14:37 UTC**
145
+- 2026-06-08: started at **12:17 UTC**
146
+
147
+Supported operating model, in order:
148
+
149
+1. **Default:** keep the current Sunday `53 11 * * 0` cron as the low-effort baseline.
150
+2. **Manual fallback:** run `gh workflow run crawl-and-publish.yml -R YOUR_USERNAME/SquadScope` (or use the Actions UI) when an operator needs to start the pipeline immediately.
151
+3. **Recommended mitigation for punctual launches:** keep the workflow as-is and have an external scheduler call the existing `workflow_dispatch` trigger. Example CLI target for a cron job or scheduler host:
152
+
153
+ ```bash
154
+ gh workflow run crawl-and-publish.yml -R YOUR_USERNAME/SquadScope
155
+ ```
156
+
157
+ Example GitHub API dispatch:
158
+
159
+ ```bash
160
+ curl -L \
161
+ -X POST \
162
+ -H "Accept: application/vnd.github+json" \
163
+ -H "Authorization: Bearer $GITHUB_TOKEN" \
164
+ https://api.github.com/repos/YOUR_USERNAME/SquadScope/actions/workflows/crawl-and-publish.yml/dispatches \
165
+ -d '{"ref":"main","inputs":{"run_mode":"normal","source_refresh_policy":"reuse-same-day"}}'
166
+ ```
167
+
168
+4. **Optional future escalation:** move to self-hosted runners only if you need tighter operational control; that is not required for the default setup.
169
170
### Option B: Manual trigger
171
@@ -806,10 +837,10 @@ Edit `.github/workflows/crawl-and-publish.yml`:
837
```yaml
838
on:
839
schedule:
809
- - cron: '53 6 * * 1' # Change to your desired time (UTC)
840
+ - cron: '53 11 * * 0' # Sunday 11:53 UTC; still best-effort on GitHub-hosted runners
841
```
842
812
-Times are in UTC. Use crontab.guru to generate your schedule.
843
+Times are in UTC. Use crontab.guru to generate your schedule, but assume GitHub-hosted `schedule` can start late and use the `workflow_dispatch` mitigation ladder above if exact timing matters.
844
845
### Change the reskill interval
846
docs/pipeline-validation.md
+4
-1
@@ -5,7 +5,8 @@ This checklist validates the automated weekly workflow in `.github/workflows/cra
5
## Trigger and scheduling
6
7
- [x] `schedule` is enabled in the workflow.
8
-- [x] Cron is `53 6 * * 1`, which runs every Monday at 06:53 UTC.
8
+- [x] Cron is `53 11 * * 0`, which targets Sundays at 11:53 UTC.
9
+- [x] The documented expectation is **best effort**: GitHub-hosted scheduled workflows can start late on shared runners, so validation checks the configured cron plus the mitigation path instead of assuming an exact start minute.
10
- [x] `workflow_dispatch` is enabled for manual runs from the Actions tab or `gh workflow run crawl-and-publish.yml`.
11
- [x] `concurrency.group` is `weekly-crawl` with `cancel-in-progress: false`, so a second run waits instead of overlapping the active run.
12
@@ -126,6 +127,7 @@ Required secrets/tokens:
127
128
- Actions tab → **Crawl and publish weekly data** → **Run workflow**
129
- CLI: `gh workflow run crawl-and-publish.yml`
130
+- External scheduler / automation host: call the same `workflow_dispatch` endpoint or CLI command if punctual timing matters more than GitHub-hosted `schedule` latency
131
132
### Trigger locally
133
@@ -144,3 +146,4 @@ Required secrets/tokens:
146
- Weekly momentum quality is only as good as the historical star snapshots; first runs and sparse history can make `stars_gained` incomplete.
147
- Hugo must be `0.146.0+`; the workflow pins `0.161.1` because older runner binaries fail with the current theme.
148
- The scheduled workflow now deploys Pages directly. `deploy-site.yml` skips bot-authored pushes so the scheduled run does not trigger a duplicate Pages deployment.
149
+- GitHub-hosted `schedule` is best-effort. This repo has observed multi-hour delays on scheduled starts, so the supported mitigation path is manual `gh workflow run`, then external scheduler -> `workflow_dispatch`, with self-hosted runners reserved as optional future work.
docs/rollout-checklist.md
+8
-6
@@ -68,9 +68,11 @@ Use this checklist to verify your SquadScope instance is ready for production. C
68
- [ ] Verify workflow file: `.github/workflows/crawl-and-publish.yml` has schedule trigger:
69
```yaml
70
schedule:
71
- - cron: '53 6 * * 1' # Monday 06:53 UTC
71
+ - cron: '53 11 * * 0' # Sunday 11:53 UTC
72
```
73
- [ ] Confirm schedule is correct for your timezone
74
+ - [ ] Confirm operators understand GitHub-hosted `schedule` is best-effort and may start hours late on shared runners
75
+ - [ ] If punctual launches matter, document who owns the external scheduler or manual `gh workflow run crawl-and-publish.yml -R OWNER/REPO` fallback
76
77
- [ ] **Run counter initialized**
78
- [ ] File exists: `.squad/run-counter.txt`
@@ -79,8 +81,8 @@ Use this checklist to verify your SquadScope instance is ready for production. C
81
82
## First Automated Run
83
82
-- [ ] **Automated run completed (wait until next Monday 06:53 UTC or manual trigger)**
83
- - [ ] Check Actions tab at scheduled time
84
+- [ ] **Automated run completed (wait until the next Sunday schedule window or use a manual trigger)**
85
+ - [ ] Check the Actions tab after the schedule window; do not assume the run starts exactly at 11:53 UTC
86
- [ ] Verify workflow completed with green checkmark
87
- [ ] Monitor logs for any warnings or errors
88
@@ -100,8 +102,8 @@ Use this checklist to verify your SquadScope instance is ready for production. C
102
## Post-Launch Monitoring
103
104
- [ ] **Weekly runs continue automatically**
103
- - [ ] Check Actions every Monday morning to confirm workflow ran
104
- - [ ] (Optional) Set a calendar reminder to check on Mondays
105
+ - [ ] Check Actions every Sunday/Monday window to confirm the workflow eventually ran
106
+ - [ ] (Optional) Set a calendar reminder to check after the scheduled window rather than at an exact minute
107
108
- [ ] **Quality remains consistent**
109
- [ ] Review a few published analyses for quality
@@ -128,7 +130,7 @@ Use this checklist to verify your SquadScope instance is ready for production. C
130
- [ ] Restore secret after testing
131
132
- [ ] **Reskill cycle verified (after 5 runs)**
131
- - [ ] Count automated runs (every Monday = 1 run)
133
+ - [ ] Count automated runs (every scheduled weekly publish = 1 run)
134
- [ ] After 5 weeks, check for `.squad/reskill/YYYY-WNN.md` file
135
- [ ] Verify the workflow invokes the real reskill path (`scripts/reskill.py`) and outputs analysis + recommendations
136