💡 Reusable Workflow Caller-Callee Compatibility Contract & Lint Standard

[github-actions[bot]]

Summary

Add a CI lint check that validates every reusable workflow caller reference resolves to an existing callee with compatible inputs, catching interface drift before it causes silent failures. Addresses a recurring bug pattern where caller stubs pin stale or non-existent workflow versions, stranding merged commits.

Market Signal

GitHub Actions added four new job context properties in September 2026 (job.workflow_ref, job.workflow_sha, job.workflow_repository, job.workflow_file_path) enabling reusable workflows to know their own identity at runtime. Combined with GitHub's growing reusable workflow ecosystem and the official workflow lockfile initiative (public preview expected 3-6 months from March 2026 roadmap), the need for static contract verification — ensuring callers and callees agree on inputs before runtime — is becoming a first-class concern.

Sources: GitHub Actions September 2026 updates, GitHub Actions workflow lockfile roadmap

User Signal

Five incidents in the last 30 days trace to the same failure class — caller-callee interface drift:

• Fleet pr-review callers pin legacy bare pr-review/stable and are unmanaged — no pr-review release can reach the fleet #1125: Fleet pr-review callers pin legacy bare pr-review/stable — no release can reach the fleet
• pr-review is not a registered canary-ring agent — its release channels have been frozen since 2026-06-20, stranding 50 merged commits #1106: pr-review frozen since 2026-06-20, stranding 50 merged commits
• standards/v1-stable has no staleness alarm and no pre-promotion consumer verification — it fell 14 commits / 8 files behind main unnoticed #1173: standards/v1-stable fell 14 commits / 8 files behind main unnoticed
• Dependabot never updates standards/workflows/ — standards stub pins go stale while consumers move ahead #1172: Dependabot never updates standards/workflows/ — stub pins go stale while consumers move ahead
• RING_REUSABLES has drifted from canary-rings.json — 7 agents deploy verbatim, 2 with pins that do not exist #1088: RING_REUSABLES drifted from canary-rings.json — 7 agents deploy verbatim, 2 with pins that do not exist

Technical Opportunity

The caller stubs in standards/workflows/ follow a predictable pattern: they declare uses: references with explicit @ref pins. A pure, side-effect-free lint script can:

1. Extract all uses: references from workflow files
2. Resolve each reference to its target workflow file (local or cross-repo)
3. Extract the target's workflow_call.inputs schema
4. Verify the caller's with: block provides all required inputs

This fits the org's "decision logic in a pure tested script" pattern (AGENTS.md) and can be gated by a bats test suite in CI, triggered on changes to .github/workflows/ or standards/workflows/.

Assessment

Dimension	Score	Rationale
Feasibility	med	Cross-repo ref resolution adds complexity; intra-repo is straightforward
Impact	high	Catches the single most common class of deployment bug in the last 30 days
Urgency	high	Five incidents in September alone; the bug rate is accelerating as the fleet grows

Adversarial Review

Strongest objection: YAML workflow inputs lack a formal schema — they are key-value pairs with optional type and default declarations. A full compatibility checker would need to handle optional vs required inputs, type coercion, default values, and cross-repo references. Building this reliably is more work than the bug frequency justifies.

Rebuttal: The minimum viable version does not need full schema validation. The most common failure mode is a uses: reference pointing at a tag/ref that does not exist or a callee that has renamed/removed an input. A lint check that verifies (1) the ref resolves to an existing file/tag and (2) all required inputs in the callee are present in the caller's with: block would have caught 3 of the 5 recent incidents. This is a 200-line shell script, not a type system.

Suggested Next Step

Prototype a lint script that extracts uses: references from all workflow files, resolves each to its target, and checks for missing required inputs. Gate it behind a new CI workflow triggered on changes to .github/workflows/ or standards/workflows/.