Triage Codeql

GitHub Code Scanning Triage

Use the shipped helpers for GitHub REST alert operations. Run commands below from the repository root. Owner references starting with ./ are relative to this skill directory.

Pick The Task

Authorization and read-only scope follow AGENTS.md#when-a-sow-is-required; findings and evidence follow AGENTS.md#review. Inspection stops at the verified report. Applying remote state changes requires authorization covering those actions; preserve permission already granted for the current scope.

Owners

• Helpers: ./scripts/codeql-list.sh, ./scripts/codeql-dismiss.sh, and ./scripts/_lib.sh own their arguments, output and repository resolution. Use list-helper --help for its flags.
• CI suites and upload filters: .github/workflows/codeql.yml and its referenced .github/codeql/ configs. Do not infer every language uses the C/C++ security-extended configuration.
• API permissions, alert states and operations: GitHub REST code scanning.
• Authentication: gh environment.
• Discovery capture: AGENTS.md#knowledge-capture.

Setup

• The helpers need Bash, Git, gh and jq; summary output also uses awk, sort, head and column.
• Authentication belongs to gh, through its configured credentials or supported exported environment variables. The helpers do not source .env. Use gh auth status to diagnose missing authentication; use gh auth login only when setup is needed. Do not request credential values in conversation.
• Check the endpoint's token permissions and the account's repository access separately. A successful listing does not establish permission to dismiss.
• Confirm the target: the helpers prefer upstream, falling back to origin when that remote lookup is absent. They are intended for github.com remotes; a fork checkout can therefore operate on upstream alerts.

Resolve the same target used by both helpers; this reads Git configuration without displaying the remote URL. Keep Setup and subsequent examples in the same shell session so they share codeql_repo:

source .agents/skills/triage-codeql/scripts/_lib.sh
codeql_repo="$(gh_require_slug)"
printf '%s\n' "$codeql_repo"

Inspect

The default is open alerts across tools. The compact summary shows only the most frequent rule/severity groups; use --raw for the complete array merged across pages. For a CodeQL-only investigation:

bash .agents/skills/triage-codeql/scripts/codeql-list.sh --tool=CodeQL
bash .agents/skills/triage-codeql/scripts/codeql-list.sh --tool=CodeQL --raw \
  | jq -r '.[] | [.number, .rule.id, .most_recent_instance.location.path, .html_url] | @tsv'

The list helper also supports --state= and --severity=; choose filters from the requested investigation. A candidate list is not a dismissal list.

Set codeql_alert to a listed alert number, then inspect the alert with the target resolved in Setup:

gh api "/repos/${codeql_repo:?resolve the repository in Setup}/code-scanning/alerts/${codeql_alert:?set the alert number}"

Open the returned html_url for available traces. Verify the rule, affected code, reachability and relevant instances before deciding; a matching rule ID, directory or filename alone does not establish a false positive.

Triage Decisions

The dismissal helper supports the following reasons; this is its supported subset, not the complete GitHub API enum.

Fixing code and having analysis report fixed is different from dismissing a finding. Reopening a dismissed alert is also possible through GitHub or the update endpoint with state=open; the dismissal helper does not implement it. Consult GitHub's alert history when investigating a reopened finding.

Apply Verified Decisions

Use ./scripts/codeql-dismiss.sh only for the verified alert number, reason and comment covered by authorization. Set codeql_reason and codeql_comment from that decision. Comments SHOULD be short, factual and ASCII; the helper passes the quoted comment as one API string argument.

bash .agents/skills/triage-codeql/scripts/codeql-dismiss.sh \
  "${codeql_alert:?set the verified alert number}" \
  "${codeql_reason:?set the verified reason}" \
  "${codeql_comment:?set the supporting explanation}"

For a batch, you MUST record the exact verified alert numbers with their reasons and supporting evidence before applying the single-alert helper to each. You MUST NOT pipe a rule-only search directly into dismissal commands. Re-check the target and decision if the code or alert has changed since inspection; inspect the returned state after each request.

Apply writes sequentially and stop on errors. Handle throttling according to the response and GitHub's rate-limit guidance; there is no fixed safe request rate, and the helpers do not implement retries.

Troubleshooting

For direct calls beyond the helpers, use the linked REST reference and gh api manual. Dependabot's GraphQL vulnerabilityAlerts is a different data source; it does not retrieve CodeQL findings.