Skip to content

ci(docs): restore the 'run documentation' label gate - #876

Merged
ocots merged 1 commit into
mainfrom
ci/restore-label-gate
Aug 23, 2026
Merged

ci(docs): restore the 'run documentation' label gate#876
ocots merged 1 commit into
mainfrom
ci/restore-label-gate

Conversation

@ocots

@ocots ocots commented Aug 23, 2026

Copy link
Copy Markdown
Member

Why

#875 removed the run documentation label gate and replaced it with an automatic paths
trigger. The premise was that the label had never been applied to any of the twelve
documentation pull requests, and that this was an oversight.

It was not an oversight — the label is the mechanism. It exists so documentation builds are
started deliberately instead of on every push, and the rewrite was verified locally with the
intent of finalising the docs before running builds online. #875 removed a control that was
working as designed.

What changes

.github/workflows/Documentation.yml goes back to its pre-#875 state, byte for byte. The
paths filter goes away with the rest: once a human decides when the job runs, a path filter
decides nothing.

The restored condition is worth restating, because it is more carefully built than it looks:

if: >
  github.event_name != 'pull_request' ||
  (github.event.action == 'labeled' && github.event.label.name == 'run documentation') ||
  (github.event.action != 'labeled' && contains(github.event.pull_request.labels.*.name, 'run documentation'))
  • On a labeled event it reacts only to run documentation — otherwise adding three labels
    in a row would start three builds.
  • On opened / synchronize / reopened it checks that the PR currently carries the label.
    So a build is opted into once, and then repeats on every push for as long as the label stays.

This also puts the repository back in line with the Handbook's Documentation.yml template
(VITEPRESS-DOC.md:484-493), which #875 had made OptimalControl the only package to diverge
from.

What is kept

docs/src/index.md keeps the Draft = false that #875 added. It is independent of the trigger,
and without it the landing page's five @example blocks execute nowhere — not in CI, not
locally. That one was a real gap.

Verification

This PR touches only the workflow. For a pull_request event GitHub evaluates the workflow file
from the PR head, so the restored file governs this PR too: no Documentation job should start
here unless the run documentation label is added. That is the check.

🤖 Generated with Claude Code

PR #875 replaced the label gate with an automatic `paths` trigger, on the
premise that the label had never been applied to any of the twelve
documentation pull requests and that this was an oversight. It was not: the
label is the mechanism. It exists so that documentation builds are started
deliberately rather than on every push, and the rewrite was verified locally
with the intent of finalising the docs before running builds online.

Restore the trigger and the condition byte for byte to their state before
#875. The original condition was already carefully built and is worth
restating: on a 'labeled' event it reacts only to 'run documentation', so
adding several labels in a row does not re-run the job once per label; on
opened/synchronize/reopened it checks that the pull request currently carries
the label, so a build is opted into once and then repeats on every push.

The `paths` filter goes away with the rest. Once a human decides when the job
runs, a path filter decides nothing.

`docs/src/index.md` keeps the `Draft = false` that #875 added — it is
independent of the trigger, and without it the landing page's five example
blocks execute nowhere, not even locally.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@ocots
ocots merged commit 2fbabb4 into main Aug 23, 2026
8 checks passed
@ocots
ocots deleted the ci/restore-label-gate branch August 23, 2026 17:18
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