Skip to content

docs: document BRANCH and DEBUG, and info as a severity threshold - #45

Open
joeymussalli wants to merge 1 commit into
trustabl:mainfrom
joeymussalli:docs/document-branch-and-debug
Open

docs: document BRANCH and DEBUG, and info as a severity threshold#45
joeymussalli wants to merge 1 commit into
trustabl:mainfrom
joeymussalli:docs/document-branch-and-debug

Conversation

@joeymussalli

Copy link
Copy Markdown

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

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
@joeymussalli

Copy link
Copy Markdown
Author

Closing as a duplicate of #19 (bradAGI) documenting BRANCH and DEBUG.

@joeymussalli

Copy link
Copy Markdown
Author

Reopened — closed earlier by mistake. Leaving this up per author request.

@joeymussalli
joeymussalli force-pushed the docs/document-branch-and-debug branch from 0582650 to 312326a Compare August 24, 2026 20:05
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