feat(hybrid-gate): expose docs_only so callers stop reimplementing it - #35
Merged
Conversation
This workflow already computes whether a change is docs-only, and uses it to skip its own full-gate-build. It never exposed that to the caller, so an adopting repo wanting the same saving had to restate the path patterns locally -- a second copy of logic that lives here, free to diverge, and invisibly so since each side would look correct alone. thumos hit this and stopped short of building the local version for exactly that reason (thumos#775): under `strict: true` every merge invalidates every open PR, so a one-line markdown change re-ran an armv7a cross-compile and the whole QEMU witness matrix, ~324s, twice. The output carries two warnings a caller needs and cannot infer: A required check must not be gated with a job-level `if:` or a `needs:` on a preflight -- either leaves the required context never reporting and strands the PR permanently. Gate the expensive STEPS inside the job so the check still reports. A required check that can pass vacuously is worse than a slow one. And the value is EMPTY, not `false`, when check-trailer does not reach a verdict. Callers act only on the literal `'true'`, which is the same conservative direction this workflow's own docs-only step takes for an empty diff. Additive: no existing caller changes behaviour.
forkwright
added a commit
to forkwright/thumos
that referenced
this pull request
Aug 14, 2026
…tput (#822) ci(gate): bump the shared hybrid-gate pin to pick up the docs_only output forkwright/.github#35 exposes `docs_only` as a `workflow_call` output, built in response to thumos#775 after I declined to reimplement the path classification locally. Adopters pin by SHA, so each repo needs its own bump. Purely additive on this side: no caller behaviour changes, and nothing here consumes the output yet. Bumping first so the capability is available and the pin does not drift further — it was already a release behind. Consuming it is a separate change and a larger one, deliberately not folded in here. thumos's expensive job (`kernel (i686 tests + armv7a build)`) lives in `ci.yml` while the hybrid-gate call lives in `gate-attestation.yml`, and a job cannot `needs:` across workflow files. Making the required check read `docs_only` therefore means restructuring where that job lives — and it is a REQUIRED context, so getting it wrong leaves the check never reporting and strands every PR. That earns its own PR and its own verification. Two constraints from the output's own description, recorded here so the consuming change does not have to rediscover them: the value is EMPTY, not `false`, when check-trailer reaches no verdict, so only the literal `'true'` may be acted on; and the guard must gate the expensive STEPS rather than the job, because a required check that can pass vacuously is worse than a slow one. Co-authored-by: admin <admin@ardentleatherworks.com>
This was referenced Aug 14, 2026
forkwright
pushed a commit
to forkwright/thumos
that referenced
this pull request
Aug 15, 2026
…tput (#822) ci(gate): bump the shared hybrid-gate pin to pick up the docs_only output forkwright/.github#35 exposes `docs_only` as a `workflow_call` output, built in response to thumos#775 after I declined to reimplement the path classification locally. Adopters pin by SHA, so each repo needs its own bump. Purely additive on this side: no caller behaviour changes, and nothing here consumes the output yet. Bumping first so the capability is available and the pin does not drift further — it was already a release behind. Consuming it is a separate change and a larger one, deliberately not folded in here. thumos's expensive job (`kernel (i686 tests + armv7a build)`) lives in `ci.yml` while the hybrid-gate call lives in `gate-attestation.yml`, and a job cannot `needs:` across workflow files. Making the required check read `docs_only` therefore means restructuring where that job lives — and it is a REQUIRED context, so getting it wrong leaves the check never reporting and strands every PR. That earns its own PR and its own verification. Two constraints from the output's own description, recorded here so the consuming change does not have to rediscover them: the value is EMPTY, not `false`, when check-trailer reaches no verdict, so only the literal `'true'` may be acted on; and the guard must gate the expensive STEPS rather than the job, because a required check that can pass vacuously is worse than a slow one.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Finding
This workflow already computes whether a change is docs-only — patterns
*.md,docs/*,llms.txt, with an empty diff conservatively treated as not-docs-only — and uses it to skip its ownfull-gate-build.It never exposed that to the caller. So an adopting repo wanting the same saving had to restate the path patterns locally: a second copy of logic that lives here, free to diverge, and invisibly so, because each side would look correct in isolation.
Why now
thumos hit it and deliberately stopped short of building the local version, routing the request here instead (thumos#775, with measurements).
Under
strict: trueevery merge invalidates every open PR, so a markdown-only change re-ran their full requiredkerneljob — an armv7a cross-compile plus the whole QEMU witness matrix, ~324s, twice for one one-line PR.That is the right call and worth naming: the local fix was available and obvious, and taking it would have created exactly the divergence this repo exists to prevent.
What changed
One
outputs:block onworkflow_call, wired to the existingcheck-trailerjob output. Purely additive — no existing caller changes behaviour.Two warnings the output carries, because a caller cannot infer them
A required check must not be gated on this with a job-level
if:or aneeds:on a preflight job. Either leaves the required context never reporting, which strands the PR permanently. The guard belongs on the expensive steps inside the job, so the check still reports a verdict.The value is empty, not
false, whencheck-trailerdoes not reach a verdict — skipped, cancelled, or superseded. Callers must act only on the literal string'true'. That is the same conservative direction this workflow's own docs-only step already takes for an empty diff, and it matters here becausecancelledis indistinguishable fromsupersededin the checks list.Verification
The workflow parses and the output resolves to
jobs.check-trailer.outputs.docs_only, confirmed by loading the YAML and reading the wiring rather than eyeballing the diff.