Skip to content

ci: scope docs-only skipping to jobs, so required checks still report - #1954

Closed
efiten wants to merge 1 commit into
Kpa-clawbot:masterfrom
efiten:ci/docs-skip-without-blocking-merges
Closed

ci: scope docs-only skipping to jobs, so required checks still report#1954
efiten wants to merge 1 commit into
Kpa-clawbot:masterfrom
efiten:ci/docs-skip-without-blocking-merges

Conversation

@efiten

@efiten efiten commented Sep 4, 2026

Copy link
Copy Markdown
Collaborator

Replaces the trigger-level paths-ignore from #1949 and #1950. That approach was wrong, and it is currently blocking #1953 from merging.

What was wrong

GitHub documents the distinction I had backwards:

a workflow skipped by path filtering keeps its checks pending and blocks the merge, while a job skipped by an if: conditional reports Success and does not.

So the filtering has to live on the jobs, not on the trigger.

I compounded it by claiming, in both the commit and the description of #1949, that master had no required checks: "verified: the branch protection endpoint returns 404". That verification was invalid. A 404 there means the token cannot read protection details, not that none exist. The branch reports protected=true, and #1953 was refused with the base branch policy prohibits the merge.

I wrote the trap into that workflow as a comment and then walked into it, because I had established the precondition wrongly.

What this does

A 🔎 Change scope job computes whether anything outside docs/, *.md and LICENSE changed. go-test, e2e-test, build-and-publish and release-artifacts are gated on its output. A documentation-only pull request skips those jobs, they report Success, and the PR can merge.

Only pull requests are scoped. A push or a dispatch always runs the full pipeline.

That second part is deliberate and it fixes today's other failure. release-fast-path.yml re-tags :edge to :vX.Y.Z only when the :edge revision label matches the tagged commit. A master commit with no image breaks tagging, which is precisely what happened to the v3.10.0 tag, where the tagged commit was documentation-only: the fast path could not re-tag, fell back to a dispatch, and the dispatch published nothing (#1951).

Master pushes now always produce an image. The cost is running the pipeline on documentation commits to master. Pull requests are where the queue pressure actually was: a pull_request run created at 12:13 did not start its first job until 16:19.

Two conservative defaults

In the scope check, a non-pull_request event and an empty diff both count as code. An unexpected shape runs everything rather than silently skipping.

Verification

The YAML parses, the trigger has no paths filter left, and the four gated jobs carry both needs: [..., changes] and the if:. The real proof is this PR itself: it changes only the workflow, so Change scope must resolve to code=true and the full pipeline must run.

Replaces the trigger-level paths-ignore from Kpa-clawbot#1949 and Kpa-clawbot#1950. That approach was
wrong and it blocked Kpa-clawbot#1953 from merging.

What was wrong. GitHub documents the distinction I got backwards: a workflow
skipped by path filtering leaves its checks in a pending state that never
arrives, and a pull request requiring those checks can never merge. A JOB
skipped by an if: conditional reports Success and does not block. So the
filtering has to live on the jobs, not on the trigger.

I compounded that by asserting master had no required checks, "verified: the
branch protection endpoint returns 404". That verification was invalid. The 404
means the token cannot read protection details, not that none exist; the branch
reports protected=true, and Kpa-clawbot#1953 was refused with "the base branch policy
prohibits the merge".

What this does. A "Change scope" job computes whether anything outside docs/,
*.md and LICENSE changed, and go-test, e2e-test, build-and-publish and
release-artifacts are gated on it. Documentation-only pull requests skip those
jobs, which report Success, so they still merge.

Only pull requests are scoped. A push or a dispatch always runs the full
pipeline. That is deliberate: release-fast-path.yml re-tags :edge to :vX.Y.Z
only when the :edge revision label matches the tagged commit, so a master commit
without an image breaks tagging. That is exactly what happened to the v3.10.0
tag, where the tagged commit was documentation-only. Master pushes now always
produce an image, at the cost of running the pipeline on documentation commits
to master. Pull requests are where the queue pressure was.

Two conservative defaults in the scope check: a non-pull_request event and an
empty diff both count as code, so an unexpected shape runs everything rather
than silently skipping.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PQS3XLoPD98yu9pxdRujqg
@efiten efiten closed this Sep 4, 2026
@efiten efiten reopened this Sep 4, 2026
efiten added a commit that referenced this pull request Sep 4, 2026
The previous commit left two 'if:' keys on release-artifacts, one pre-existing
tag guard and one added by the gating pass. GitHub rejects a duplicate mapping
key and refuses to load the whole workflow, which is why the branch push
produced a run named after the file path with zero jobs, and why PR #1954 got no
run at all. PyYAML accepts duplicates silently (last wins), so local validation
passed. The two conditions are now one expression, and the check I run locally
looks for duplicate keys per job as well as valid YAML.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PQS3XLoPD98yu9pxdRujqg
@efiten

efiten commented Sep 4, 2026

Copy link
Copy Markdown
Collaborator Author

Closing in favour of #1955, which carries the same change from a branch on this repository plus one fix.

This PR got no workflow run and no check suite at all. The cause was not a policy or the fork boundary, which is what I first suspected: the commit left two if: keys on the release-artifacts job, one pre-existing tag guard and one added by the gating pass. GitHub rejects a duplicate mapping key and refuses to load the entire workflow, so no run could be created. PyYAML accepts duplicates silently, last one wins, which is why local validation passed and I did not catch it.

Same content, corrected, in #1955.

@efiten efiten closed this Sep 4, 2026
efiten added a commit that referenced this pull request Sep 4, 2026
…#1955)

Same change as #1954, opened from a branch on this repository instead of
from a fork. #1954 never received a workflow run: zero runs and zero
check suites for its head commit, and closing and reopening it changed
nothing. A manual `workflow_dispatch` on master ran immediately, so
Actions itself is working; the `pull_request` event from the fork is
what produces nothing. See the note at the end.

Replaces the trigger-level `paths-ignore` from #1949 and #1950. That
approach was wrong, and it is currently blocking #1953 from merging.

## What was wrong

GitHub documents the distinction I had backwards:

> a workflow skipped by path filtering keeps its checks **pending** and
blocks the merge, while a **job** skipped by an `if:` conditional
reports **Success** and does not.

So the filtering has to live on the jobs, not on the trigger.

I compounded it by claiming, in both the commit and the description of
#1949, that master had no required checks: *"verified: the branch
protection endpoint returns 404"*. **That verification was invalid.** A
404 there means the token cannot read protection details, not that none
exist. The branch reports `protected=true`, and #1953 was refused with
`the base branch policy prohibits the merge`.

## What this does

A `🔎 Change scope` job computes whether anything outside `docs/`, `*.md`
and `LICENSE` changed. `go-test`, `e2e-test`, `build-and-publish` and
`release-artifacts` are gated on its output. A documentation-only pull
request skips those jobs, they report Success, and the PR can merge.

**Only pull requests are scoped.** A push or a dispatch always runs the
full pipeline.

That second part is deliberate and it fixes a separate failure.
`release-fast-path.yml` re-tags `:edge` to `:vX.Y.Z` only when the
`:edge` revision label matches the tagged commit. A master commit with
no image breaks tagging, which is what happened to the v3.10.0 tag: the
tagged commit was documentation-only, the fast path could not re-tag, it
fell back to a dispatch, and the dispatch published nothing (#1951).
Master pushes now always produce an image. The cost is running the
pipeline on documentation commits to master; pull requests are where the
queue pressure was.

Two conservative defaults in the scope check: a non-`pull_request` event
and an empty diff both count as code, so an unexpected shape runs
everything rather than silently skipping.

## Note for whoever has repository settings access

Fork pull requests stopped getting workflow runs between 22:36 and
05:40. #1949, #1950 and #1951 all came from the same fork and each got a
run; #1954 got none, with no check suite created at all, which is
different from a skipped run. `repos/.../actions/permissions` returns
403 for a non-admin token, so this could not be confirmed from the API.
If the "Fork pull request workflows from outside collaborators" setting
was tightened, that would explain it, and it would affect every outside
contributor, not just this branch.

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant