Summary
The release-docs.yml workflow promotes documentation from DRAFT to FINAL based on the openemr-tag input, but it never verifies that the supplied tag actually exists in openemr/openemr. If an operator (or upstream automation) supplies a non-existent or mistyped version, the workflow will happily stamp FINAL release docs pointing at a version that was never published.
Why this matters
Documentation is now part of the release path. A FINAL stamp on a non-existent tag:
- Misleads users into looking for downloads that do not exist.
- Pollutes the website with permanently-linked pages that cannot be undone without manual recovery.
- Is silent: there is no test for this branch, and the failure mode only surfaces after publication.
This is an architectural defect rather than a logic bug: there is no current way to test the "tag does not exist" branch because the workflow assumes the input is valid. Treating it as a Bug because the workflow's contract is violated and the breakage is silent.
Reproduction
- Trigger
release-docs.yml (workflow_dispatch) with:
openemr-tag: a value that is not a real tag in openemr/openemr (e.g. v999.0.0, or a typo like v8.1.O).state: FINAL.
- Observe: the workflow completes successfully and the docs are promoted to FINAL even though
git ls-remote https://github.com/openemr/openemr refs/tags/<tag> returns nothing.
Expected: the workflow should fail fast with a clear error before any DRAFT->FINAL flip, and require the tag to resolve in openemr/openemr first.
Proposed fix
Add a pre-flip step that resolves the tag against openemr/openemr (e.g. git ls-remote --exit-code --tags https://github.com/openemr/openemr refs/tags/${openemr-tag} or the GitHub API equivalent) and aborts the run if it does not exist. Run this guard before any state mutation.
Context
This worst case was tripped during a recent docs-first handoff; recovery required re-running the prior FINAL job to restore the correct state. The guard would have prevented the bad flip outright.
Summary
The
release-docs.ymlworkflow promotes documentation from DRAFT to FINAL based on theopenemr-taginput, but it never verifies that the supplied tag actually exists inopenemr/openemr. If an operator (or upstream automation) supplies a non-existent or mistyped version, the workflow will happily stamp FINAL release docs pointing at a version that was never published.Why this matters
Documentation is now part of the release path. A FINAL stamp on a non-existent tag:
This is an architectural defect rather than a logic bug: there is no current way to test the "tag does not exist" branch because the workflow assumes the input is valid. Treating it as a Bug because the workflow's contract is violated and the breakage is silent.
Reproduction
release-docs.yml(workflow_dispatch) with:openemr-tag: a value that is not a real tag inopenemr/openemr(e.g.v999.0.0, or a typo likev8.1.O).state:FINAL.git ls-remote https://github.com/openemr/openemr refs/tags/<tag>returns nothing.Expected: the workflow should fail fast with a clear error before any DRAFT->FINAL flip, and require the tag to resolve in
openemr/openemrfirst.Proposed fix
Add a pre-flip step that resolves the tag against
openemr/openemr(e.g.git ls-remote --exit-code --tags https://github.com/openemr/openemr refs/tags/${openemr-tag}or the GitHub API equivalent) and aborts the run if it does not exist. Run this guard before any state mutation.Context
This worst case was tripped during a recent docs-first handoff; recovery required re-running the prior FINAL job to restore the correct state. The guard would have prevented the bad flip outright.