ci(docs): add code->docs environment-variable coverage gate#410
Merged
Conversation
check-docs-drift.sh guards the docs->code direction (a doc referencing an env var that no longer exists), but nothing checked the reverse: a user-facing env var added to the tool with no documentation. That is the gap the recent doc-sync audit surfaced. Add scripts/check-doc-env-coverage.sh: it reads the "Environment:" block of scan-sbom.sh --help (the user-facing contract) and fails if any name there is documented in neither docs/reference/cli.md nor docs/reference/docker-image.md. Wire it into the Doc Coverage CI job. Applying the gate found one real gap: SBOM_AIBOM_IMAGE was advertised in --help but documented nowhere. Add it to the cli.md env table (EN + KO).
haksungjang
force-pushed
the
ci/doc-env-forward-gate
branch
from
cf24b44 to
ac23dde
Compare
haksungjang
added a commit
that referenced
this pull request
Jul 16, 2026
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.
Why
The recent doc-sync audit found user-facing features (including several env vars) that shipped in code but were never documented.
tests/check-docs-drift.shonly guards the docs→code direction — a doc that references an env var missing from the code. Nothing checked the reverse: an env var added to the tool with no doc mention. This PR closes that structural gap.Stacked on #409 (the doc fixes). Base will retarget to
mainonce #409 merges.What
scripts/check-doc-env-coverage.sh: reads theEnvironment:block ofscan-sbom.sh --help(the user-facing env contract) and fails if any variable there is documented in neitherdocs/reference/cli.mdnordocs/reference/docker-image.md.SBOM_AIBOM_IMAGEwas advertised in--helpbut documented nowhere. Added to thecli.mdenv table (EN + KO).Verification
bash scripts/check-doc-env-coverage.sh— pass (18 vars, all documented)shellcheck --severity=warning— cleancheck-docs-drift.sh,mkdocs build --strict— passScope note
The gate checks the EN reference pages, which are the canonical env contract; EN/KO mirror parity stays enforced by the existing convention and drift checks. Extending the gate to assert KO parity for env vars is possible follow-up.