Skip to content

docs(cloud-security): troubleshoot the six code-scanning messages support sees first - #365

Draft
maximelb wants to merge 3 commits into
masterfrom
docs/code-scanning-troubleshooting
Draft

docs(cloud-security): troubleshoot the six code-scanning messages support sees first#365
maximelb wants to merge 3 commits into
masterfrom
docs/code-scanning-troubleshooting

Conversation

@maximelb

Copy link
Copy Markdown
Contributor

Draft — please review and merge; I have not merged it.

Adds six rows to the Troubleshooting table on docs/cloud-security/code-scanning.md, so support can link the page instead of paraphrasing. The page's table today has six CLI/ingest rows and carried none of these messages — checked before writing, no row is duplicated.

Documentation only.

The rows

Message What the row is careful to say
github_app_missing_contents_permission Editing the App is not the whole fix — an owner must accept the permission increase on the existing installation. Nothing was scanned and no finding changed.
scan_status: partial with sast_ruleset_unresolved Only static analysis is affected; dependency, infrastructure, licence and secret findings are complete and still close.
scan_status: unknown with repo_not_scanned Nothing has scanned it yet, and the scan-run status is authoritative when the two disagree.
free_tier_code_repos_cap / free_tier_code_images_cap The covered set is stable rather than rotating, so findings do not flap; _report means the limit is not being applied.
write_app_not_configured / write_app_lacks_contents Only the write was refused. Scanning and existing findings are unaffected, and the two messages are two different pages in GitHub's settings.
lockfile_stale The pull request is real and correct; the lock still has to be regenerated, with the exact command per ecosystem.

The "what is still working" half is the reason these rows exist: four of the six name a limit on one thing and are routinely read as "the whole repository is broken".

Checks

  • mkdocs build --strict — passes (built in a clean venv from requirements.txt).
  • scripts/check-release-note-headings.py — 0 new issues.
  • scripts/check-release-feeds.py — 9 feeds OK.
  • No nav change, no new page, no new links.

Deliberately left out

  • All internal build details. The source material for these rows carries component version numbers and internal ticket references for the changes that produced two of the messages; none of that is on the page. The rows describe observable behaviour only.
  • The policy switch that turns off registry access for fix pull requests. It is one of the causes of lockfile_stale, but the code_scanning policy record's fields are not documented publicly, so the row gives the regeneration command and stops there.
  • Any introduction to pull-request checks or fix pull requests. Neither feature is described anywhere in these docs today. The two rows that mention them are written to be meaningful only to somebody who has already enabled the feature and hit the message. Flagging this for a decision: if you would rather not name those features on a published page before they have one, drop those two rows and I will keep them internal-only.

The internal operator runbook for the same six messages is a separate PR on the private host repository.

…port sees first

Adds six rows to the Code Scanning troubleshooting table for the messages a
customer is most likely to quote: a GitHub App that cannot read repository
contents, an unresolvable static-analysis rule pack, a repository nothing has
scanned yet, the free-tier repository and image limits, a missing or
under-permissioned write App, and a fix pull request whose lockfile was not
regenerated.

Each row says what is explicitly still working, because four of these six name
a limit on one thing and are routinely read as "the whole repository is broken".

Documentation only. `mkdocs build --strict` passes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
lcbill
lcbill previously approved these changes Aug 30, 2026
lcbill
lcbill previously approved these changes Aug 30, 2026
Maxime's call: neither pull-request checks nor dependency AutoFix has any page in
the public documentation, so a Troubleshooting row for their error strings would
be the only public surface implying those features exist.

The four remaining rows all describe behaviour a customer meets through features
this page already documents.

Nothing is lost operationally: all six strings, with where each surfaces and what
each does NOT mean, are in legion_cloudsec_host/docs/CODE-LANE.md §4 ("The six
strings support hears first"), which is merged. Support has the answers; the
public page simply does not advertise two features it cannot otherwise explain.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.

2 participants