docs: document BRANCH and DEBUG, and info as a severity threshold - #45
Open
joeymussalli wants to merge 1 commit into
Open
docs: document BRANCH and DEBUG, and info as a severity threshold#45joeymussalli wants to merge 1 commit into
joeymussalli wants to merge 1 commit into
Conversation
Three gaps in the root README's inputs table, all cases where the script reads something the table does not mention. `BRANCH` and `DEBUG` are both read (the script's own header comment lists them) but neither appears in the table, so the only way to discover them is to read the source. `BRANCH` is not a nicety. The script works out the branch and repository three ways and on CodePipeline -- the primary integration here -- all three miss. CODEBUILD_WEBHOOK_HEAD_REF is documented as the head ref "of the webhook event that triggers the current build", so it is unset for pipeline-triggered builds. CODEBUILD_SOURCE_REPO_URL "may be empty" when the build originates from CodePipeline. And a pipeline source artifact is an unzipped snapshot with no .git for the final fallback. So every report and every trustabl-summary.md in that integration reads `Repository: .` / `Branch: unknown`, and the one variable that fixes it was undocumented. `SEVERITY_THRESHOLD` was documented as accepting `none/low/medium/high/critical`, but sev_rank ranks `info` at 0 and MAX_SEV can be `info`, so `SEVERITY_THRESHOLD=info` is accepted and does fail the build on info-only findings. Worth stating, because docs/EVALUATION.md says "info and META signals never fail a build on their own" -- true of the default, not true once you set this. - Add `BRANCH` and `DEBUG` rows. - Add `info` to the documented severity set. - Add a short section explaining why BRANCH is needed on CodePipeline, with the reasoning rather than just the instruction. Documentation only; no code changes. Refs: https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html
Author
|
Closing as a duplicate of #19 (bradAGI) documenting BRANCH and DEBUG. |
Author
|
Reopened — closed earlier by mistake. Leaving this up per author request. |
joeymussalli
force-pushed
the
docs/document-branch-and-debug
branch
from
August 24, 2026 20:05
0582650 to
312326a
Compare
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
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.
Three gaps in the root README's inputs table, all cases where the script reads something the table does not mention.
BRANCHandDEBUGare both read (the script's own header comment lists them) but neither appears in the table, so the only way to discover them is to read the source.BRANCHis not a nicety. The script works out the branch and repository three ways and on CodePipeline -- the primary integration here -- all three miss. CODEBUILD_WEBHOOK_HEAD_REF is documented as the head ref "of the webhook event that triggers the current build", so it is unset for pipeline-triggered builds. CODEBUILD_SOURCE_REPO_URL "may be empty" when the build originates from CodePipeline. And a pipeline source artifact is an unzipped snapshot with no .git for the final fallback. So every report and every trustabl-summary.md in that integration readsRepository: ./Branch: unknown, and the one variable that fixes it was undocumented.SEVERITY_THRESHOLDwas documented as acceptingnone/low/medium/high/critical, but sev_rank ranksinfoat 0 and MAX_SEV can beinfo, soSEVERITY_THRESHOLD=infois accepted and does fail the build on info-only findings. Worth stating, because docs/EVALUATION.md says "info and META signals never fail a build on their own" -- true of the default, not true once you set this.BRANCHandDEBUGrows.infoto the documented severity set.Documentation only; no code changes.
Refs: https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html