Skip to content

Commit 2d40933

Browse files
committed
ci(scaffold): add workflow_dispatch to CI templates + trigger-drop playbook
Born repos should have a manual CI re-run lever from birth. Add workflow_dispatch to both CI-gate templates: ci.yml.j2 (mcp-server) and validate.yml.j2 (cursor-plugin). Additive and inert - a manual lever only, so no fleet-wide retrofit and no STANDARDS_VERSION bump. Document the push-trigger-drop failure mode in standards/ci-cd.md alongside the path-filter trap: symptom (squash-merge to main with zero push-triggered runs), first observed (godot-correctness-mcp PR #7), remedy (dispatch CI manually and verify green), and the escalation rule (a second occurrence on any repo promotes this to a fleet-standards change with a STANDARDS_VERSION bump and retrofit). No existing repos retrofitted. Signed-off-by: fOuttaMyPaint <154358121+TMHSDigital@users.noreply.github.com>
1 parent 951770a commit 2d40933

3 files changed

Lines changed: 15 additions & 0 deletions

File tree

scaffold/templates/ci.yml.j2

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ on:
55
branches: [main]
66
pull_request:
77
branches: [main]
8+
workflow_dispatch: {}
89

910
permissions:
1011
contents: read

scaffold/templates/validate.yml.j2

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ on:
55
branches: [main]
66
push:
77
branches: [main]
8+
workflow_dispatch: {}
89

910
permissions:
1011
contents: read

standards/ci-cd.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,19 @@ The companion `Check VERSION vs latest tag` job in `release.yml` is a post-merge
141141

142142
Required approvals are a per-repo decision: solo-maintainer repos may set 0 approvals provided all other gates pass; multi-maintainer repos should require at least 1.
143143

144+
## Workflow trigger pitfalls
145+
146+
Every scaffolded CI workflow (`ci.yml` for mcp-server repos, `validate.yml` for cursor-plugin repos) declares `workflow_dispatch` so it can be re-run manually on any ref. This is a deliberate operational lever for the pitfalls below; it is additive and inert.
147+
148+
**Path-filter trap (by design).** `release.yml` triggers on push to `main` with `paths-ignore` for docs, markdown, and `.github/` changes. A merge that touches only ignored paths will not start `release.yml`, so no tag is cut. This is intended: docs-only merges should not release. Just be aware that a `VERSION` bump landed in a docs-only-classified change will not tag until a subsequent non-ignored push.
149+
150+
**Push-trigger drop (non-deterministic, watch item).**
151+
152+
- *Symptom:* a squash-merge to `main` produces **zero** push-triggered workflow runs (no CI, no release, no drift-check on the merge commit), even though PR checks passed and no path filter applies. `gh api repos/<owner>/<repo>/commits/<sha>/check-runs` returns `total_count: 0`.
153+
- *First observed:* `godot-correctness-mcp` PR #7 (2026-07-19). Actions was enabled, the repo was public (unlimited minutes), and the immediately preceding and following merges triggered normally — i.e. a transient GitHub delivery drop, not a config error.
154+
- *Immediate remedy:* dispatch the CI workflow manually and confirm it is green before treating `main` as verified: `gh workflow run CI --ref main` (or `Validate` for cursor-plugin repos), then `gh run watch <id> --exit-status`. The `workflow_dispatch` trigger exists for exactly this.
155+
- *Escalation rule:* one occurrence is a watch item. A **second** occurrence on any fleet repo promotes this from an operational note to a fleet-standards change — investigate a structural cause (e.g. concurrency/`paths` interaction), apply the fix fleet-wide, and cut a proper `STANDARDS_VERSION` bump with a retrofit. Do not retrofit existing repos before that threshold.
156+
144157
**Configuration lives in repo settings, not in git.** Document the current ruleset in `.github/workflows/README.md` so the state is discoverable without admin access.
145158

146159
> Note: the tool-repo release model described in `release.yml` above uses conventional-commit auto-bumps and does not currently require the `VERSION`/`version-bump-check` gates. The meta-repo deviates intentionally. A decision on whether to propagate the `VERSION`-file model to tool repos is deferred; see `ROADMAP.md`.

0 commit comments

Comments
 (0)