github-security-report 0.18.0__tar.gz → 0.19.0__tar.gz

{github_security_report-0.18.0 → github_security_report-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: github-security-report
-Version: 0.18.0
+Version: 0.19.0
 Summary: Security and quality reporting across GitHub organisations
 Project-URL: Homepage, https://github.com/lfreleng-actions/github-security-report-action
 Project-URL: Repository, https://github.com/lfreleng-actions/github-security-report-action
@@ -29,16 +29,16 @@ Requires-Dist: jinja2==3.1.6
 Requires-Dist: jsonschema==4.26.0
 Requires-Dist: pyyaml==6.0.3
 Requires-Dist: rich==15.0.0
-Requires-Dist: typer==0.27.2
+Requires-Dist: typer==0.27.3
 Provides-Extra: dev
-Requires-Dist: mypy==2.3.1; extra == 'dev'
+Requires-Dist: mypy==2.4.0; extra == 'dev'
 Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
 Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
 Requires-Dist: pytest==9.1.1; extra == 'dev'
 Requires-Dist: respx==0.23.1; extra == 'dev'
-Requires-Dist: ruff==0.16.9; extra == 'dev'
+Requires-Dist: ruff==0.17.0; extra == 'dev'
 Requires-Dist: syrupy==6.1.1; extra == 'dev'
-Requires-Dist: types-jsonschema==4.26.0.20260518; extra == 'dev'
+Requires-Dist: types-jsonschema==4.26.0.20261006; extra == 'dev'
 Requires-Dist: types-pyyaml==6.0.12.20250915; extra == 'dev'
 Description-Content-Type: text/markdown
 
@@ -76,7 +76,9 @@ states and rendered worst-first:
 
 Every category renders the same **standardised summary footer** beneath its
 table: remediation-first count lines (failures, disabled, unknown, then the
-healthy pass line, then excluded). The pass line reads **"All <state>"** when
+healthy pass line, then excluded). A category may add a note qualifying the
+pass line (Code Quality's per-language breakdown) and a **Not applicable**
+count, both shown on every surface. The pass line reads **"All <state>"** when
 nothing needs attention, or **"N <state>"** otherwise. The terminal and Slack
 stay brevity-first; the explanatory per-category description and documentation
 link are shown only on the richer Markdown and HTML (GitHub Pages) outputs.
@@ -154,6 +156,26 @@ tables (org mode):
   window a reviewed dependency update sits in while the vulnerability it fixes
   stays unpatched. Read from the batched GraphQL prefetch, so it costs no extra
   request; hide it with the `auto_merge` render toggle.
+- **Code Quality** — repositories where
+  [GitHub Code Quality](https://docs.github.com/en/code-security/concepts/code-quality/code-quality)
+  is **Disabled**, or **Partial**: configured, but without a language the
+  repository holds. Code Quality analyses six language families, so each
+  repository is first classified from its GitHub Linguist languages, read
+  from the batched GraphQL prefetch: Python (`python`), Go (`go`), Java and
+  Kotlin (`java-kotlin`), JavaScript and TypeScript
+  (`javascript-typescript`), Ruby (`ruby`) and C# (`csharp`). A repository
+  with none of them, such as one holding only shell scripts and workflow
+  files, is **Not applicable**: counted on a line of its own and never
+  reported as off. Only applicable repositories have their setup read, with
+  `GET /repos/{owner}/{repo}/code-quality/setup`; one whose setup or languages
+  cannot be read, or that holds more than the twenty languages the prefetch
+  reads, is counted as **Unreadable**, never as Disabled. The
+  **Missing** column names the languages each listed repository still needs,
+  and a footer line on every surface, the terminal included, gives the
+  enabled count out of the applicable count per language, such as
+  `python 30/32 · go 5/5 · javascript-typescript 10/12`. See
+  [ADR-0006](docs/adr/0006-github-code-quality.md); hide it with the
+  `code_quality` render toggle.
 
 The four enablement categories count the repositories with and without the
 feature (plus any whose state could not be read), and by default name whichever
@@ -192,7 +214,13 @@ signal is skipped and every other part of the report is unaffected, so the
 minimal tokens below omit it. Grant the org-admin permission only if you want
 ruleset-based tool coverage.
 
-A token without that permission gets a `404` from the endpoint, which the tool
+GitHub Code Quality is gated the same way: a fine-grained token needs
+repository Administration **write** to read a repository's Code Quality setup,
+even though the report only reads it. Without it every repository Code Quality
+applies to is reported as **Unreadable** in that one category; a classic PAT's
+`repo` scope already covers the read.
+
+A token without the org-admin permission gets a `404` from the endpoint, which the tool
 reports at **INFO** — so it is invisible unless you pass `--verbose`:
 
 ```text
@@ -212,7 +240,7 @@ A fine-grained PAT is bound to one resource owner, so it works for a report
 covering a **single** organisation. Create it with **Resource owner** set to the
 organisation and **Repository access** set to *All repositories*, then grant:
 
-**Repository permissions** (all Read-only):
+**Repository permissions** (Read-only unless noted):
 
 | Permission | Used for |
 | ---------- | -------- |
@@ -222,7 +250,7 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Code scanning alerts | CodeQL / Scorecard / zizmor / aislop findings |
 | Secret scanning alerts | Open secret-scanning alerts, across every GitHub pattern category |
 | Issues | Open issues and their labels (GitHub Issues table) |
-| Administration | Dependabot enablement + security-updates status, and effective branch rules |
+| Administration | Dependabot enablement + security-updates status, and effective branch rules. *Optional* **write** reads the Code Quality setup, which GitHub gates behind write |
 | Actions | Workflow state behind a stale CodeQL configuration |
 
 **Organization permissions:**
@@ -232,7 +260,7 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Administration | Read (write for rulesets) | *Optional*, and the only permission here with a write variant. **Read** keeps the token read-only and unlocks GitHub's secret-scanning pattern inventory (see below). **Write** additionally unlocks organisation rulesets (detecting tools enforced through an org ruleset), which GitHub gates behind Administration write. Omit the permission entirely to skip both; everything else is unaffected. |
 
 > Read-only is enough for everything except the optional ruleset coverage
-> above. A fine-grained token cannot span organisations. For a report covering
+> and the Code Quality setup read above. A fine-grained token cannot span organisations. For a report covering
 > more than one org, use a classic PAT (below).
 
 ### Multiple organisations — classic PAT
@@ -348,6 +376,7 @@ environment-variable name, never embedded.
     "issue_age_warn_days": 30,
     "issue_age_error_days": 60,
     "graph_batch": 10,
+    "concurrency": 9,
     "order": { "style": "auto" }
   },
   "organizations": [
@@ -463,10 +492,11 @@ Pages output. The valid category keys are: `codeql`,
 `zizmor`, `aislop`, `dependabot_alerts`, `secret_scanning`,
 `dependabot_alerts_enabled`, `dependabot_updates_enabled`,
 `dependabot_cooldown`, `releases`, `mutable_releases`,
-`private_vulnerability_reporting`, `auto_merge`, `github_issues`,
-`pull_requests`, `pull_requests_assigned`. Like the other `report` settings,
-`categories` can be set globally and overridden per organisation (overrides
-merge key-by-key, so flipping one output leaves the rest untouched). The
+`private_vulnerability_reporting`, `auto_merge`, `code_quality`,
+`github_issues`, `pull_requests`, `pull_requests_assigned`. Like the other
+`report` settings, `categories` can be set globally and overridden per
+organisation (overrides merge key-by-key, so flipping one output leaves the
+rest untouched). The
 machine-readable `report.json` artifact always contains the complete dataset,
 regardless of these toggles.
 
@@ -1280,10 +1310,13 @@ see the relationship reports it), but one naming an outsider proves nothing,
 because that is exactly how a private member appears to an under-privileged
 token. Those authors are reported as indeterminate rather than external, so
 `Ext` **undercounts and should be read as a lower bound** — the table says so in
-its description whenever this happens, and the run logs a warning. Membership is
-never used partially: a failed page or an organisation beyond the pagination
-guard is treated as unreadable rather than as a member list with people missing
-from it, since every absent member would otherwise read as an outsider.
+its description whenever this happens, and the terminal report prints one
+warning line under each affected organisation's heading, naming the cause: a
+token without the membership permission, a token whose account is not a member,
+or a read that failed. Membership is never used partially: a failed page or an
+organisation beyond the pagination guard is treated as unreadable rather than as
+a member list with people missing from it, since every absent member would
+otherwise read as an outsider.
 
 **Automation is never counted as external.** Bots are outsiders by association —
 `dependabot[bot]` genuinely reports `CONTRIBUTOR` or `NONE` — so counting on
@@ -1296,8 +1329,9 @@ association value GitHub has newly introduced — is **not** counted as external
 The column understates rather than inventing an outsider.
 
 **Permissions.** Reading organisation membership needs `read:org` (classic) or
-**Members: read** (fine-grained). Without it the tool logs a warning and
-reports externally-raised counts as a lower bound rather than guessing from
+**Members: read** (fine-grained). Without it the terminal report prints
+`⚠️ Token lacks read/organisation permission; results incomplete for <org>`
+and reports externally-raised counts as a lower bound rather than guessing from
 `authorAssociation` alone.
 
 ### Organisation feature gating
@@ -1345,16 +1379,25 @@ size is bounded by *latency*, not by rate-limit cost: 25 repositories measured
 at ~9 s against `lfreleng-actions` and failed intermittently; 10 measured at
 ~3.5 s.
 
+Up to four of these queries run at once. Each takes a few seconds on GitHub's
+side, so a prefetch issued one query at a time left most of the client's
+concurrency idle; against `lfreleng-actions` it took about 50 s of a 100 s run.
+
 `report.graph_batch` (default `10`; minimum `1`) sets the starting batch size,
 globally or per organisation. It is a lever for a slow day rather than a hard
 limit: a batch that still fails on size after the transport's own retries is
-re-issued at **half** the size, and the smaller size is kept for the rest of
-that organisation's collection (each organisation in a multi-org run starts
-from its own configured size, since organisations differ in how much data a
-repository carries). Only a single-repository query GitHub still cannot
-answer, or a failure that a smaller query could not fix (a `403`, an
-exhausted rate limit, or a `500`/`503` outage rather than a `502`/`504`
-timeout), aborts the run with exit code `3`.
+re-issued at **half** the size, and every batch issued after that failure is
+seen uses the smaller size for the rest of that organisation's collection
+(each organisation in a multi-org run starts from its own configured size,
+since organisations differ in how much data a repository carries). The
+learned size only shrinks. Because queries overlap, the batches already in
+flight when the first failure arrives were issued at the old size, so on a
+slow day up to four oversized batches, rather than one, may fail before the
+smaller size takes effect; that bounded cost buys the overlap. Only a
+single-repository query GitHub still cannot answer, or a failure that a
+smaller query could not fix (a `403`, an exhausted rate limit, or a
+`500`/`503` outage rather than a `502`/`504` timeout), aborts the run with
+exit code `3`, and the queries still in flight are cancelled first.
 
 The value can be set three ways, in this order of precedence:
 
@@ -1379,6 +1422,65 @@ a larger value buys nothing except a longer first failure.
 > predating the flag will reject a set one with `No such option`, so set
 > `GSR_GRAPH_BATCH` only once the pinned release supports it.
 
+### Client concurrency
+
+Each organisation's run holds at most `report.concurrency` requests to the
+GitHub API open at once (default `9`; minimum `1`, maximum `32`), globally or
+per organisation. Reads from the external Scorecard API queue on a separate
+limit of four, so a slow third-party endpoint never holds a slot that a
+GitHub request is waiting for.
+
+The value can be set three ways, in this order of precedence:
+
+1. `--concurrency N` on the command line (the action's `concurrency` input).
+2. A **repository or organisation variable** passed to that input. The
+   bundled `reporting.yaml` passes `vars.GSR_CONCURRENCY`, so the value can be
+   adjusted from repository settings without a workflow edit or a release.
+3. `report.concurrency` in the configuration; otherwise the built-in `9`.
+
+`9` is a deliberate halfway point. GitHub documents its secondary rate limits
+as no more than 100 concurrent requests across REST and GraphQL, and no more
+than 900 points per minute for REST endpoints; this project has hit those
+limits before, so the default stays well clear of them. Measured against
+`lfreleng-actions` (143 repositories, about 1,400 requests; one run each in
+the same hour, so read ±10–15 % as GitHub latency noise), before the GraphQL
+prefetch ran concurrently:
+
+<!-- markdownlint-disable MD013 -->
+
+| Concurrency | Wall | Throughput | Mean time per request | Average slots busy | GitHub pushback |
+| ----------- | ---: | ---------: | --------------------: | -----------------: | --------------- |
+| 6 (former default) | 102.5 s | 13.7 req/s | 0.283 s | 3.9 / 6 | none |
+| 12 | 75.9 s | 18.5 req/s | 0.286 s | 5.3 / 12 | none |
+
+<!-- markdownlint-enable MD013 -->
+
+Raise it once a run shows no pushback; lower it if GitHub starts answering
+with secondary rate-limit `403`/`429` responses. To measure a change, run the
+CLI with `--verbose`: when each organisation's collection finishes it logs
+one line of what the run cost, for example
+
+<!-- markdownlint-disable MD013 -->
+
+```text
+GitHub API for lfreleng-actions: 1402 requests (0 retries), 822 core points, 64 graphql points, 41.3 MiB received, 102.5 s
+```
+
+<!-- markdownlint-enable MD013 -->
+
+The request count is every request the tool issued, including retries and
+attempts that never got an answer. The points come from GitHub's own
+`x-ratelimit-*` response headers rather than from counting: GitHub meters a
+token across more than one bucket per resource (alike requests seconds apart
+can carry different `x-ratelimit-reset` values with independent counters), so
+each bucket's spread between its lowest and highest reading is summed per
+resource. The lowest reading already includes that request's own cost, so the
+figure is short by the first request of each bucket — a measurement aid, not a
+bill. Nothing of this line reaches the rendered report or the step summary.
+
+> As with `graph_batch`, an empty input is not passed to the tool, so set
+> `GSR_CONCURRENCY` only once the pinned release supports `--concurrency`.
+
 ### Pass/fail severity cutoff
 
 The severity-ranked signals (CodeQL, Scorecard, Zizmor, aislop, Dependabot
@@ -1457,6 +1559,7 @@ and the Slack **bot token** is consumed by the workflow, not the CLI.
 | `force_notify` | No | `false` | Post to Slack regardless of `report_day` |
 | `hide` | No | `""` | Category keys to suppress on every output (space- or comma-separated). Overrides config, and is one-way: it cannot re-enable a disabled category |
 | `graph_batch` | No | `""` | Repositories per batched GraphQL prefetch query (minimum `1`; default: config, else `10`). Pass a repository or organisation variable such as `${{ vars.GSR_GRAPH_BATCH }}` to adjust it from settings. A batch that still fails is halved automatically, so this sets the starting size (see [GraphQL prefetch batch size](#graphql-prefetch-batch-size)) |
+| `concurrency` | No | `""` | Concurrent GitHub API requests per organisation (`1` to `32`; default: config, else `9`). Pass a repository or organisation variable such as `${{ vars.GSR_CONCURRENCY }}` to adjust it from settings (see [Client concurrency](#client-concurrency)) |
 | `tool_version` | No | `""` | Published PyPI version to install. Empty (the default) uses the Dependabot-managed pin in `.github/runtime-pin/requirements.txt`; set a specific version to override. Ignored on pull requests or when `use_local_source` is `true` (both run from source) |
 | `use_local_source` | No | `false` | Run from the checked-out source instead of PyPI (for testing unreleased code from any event) |
 
@@ -1578,8 +1681,8 @@ the run, rather than falling back to every repository. The run then collects
 exactly the repositories that check validated, without listing the
 organisation again, and prints `Limited to:` beneath its heading.
 
-The remediable categories are the simple on/off features with a documented
-enablement endpoint:
+The remediable categories are the features with a documented enablement
+endpoint:
 
 | `--category` | Enables |
 |---|---|
@@ -1589,15 +1692,48 @@ enablement endpoint:
 | `dependabot_updates_enabled` | Dependabot security updates (plus alerts) |
 | `private_vulnerability_reporting` | Private vulnerability reporting |
 | `auto_merge` | The repository's "Allow auto-merge" setting |
+| `code_quality` | GitHub Code Quality, per language (named only; billed) |
+| `codeql_stale_configurations` | Stale CodeQL cleanup (named only; deletes) |
 
 Qualitative findings (Scorecard, zizmor, open Dependabot alerts, cooldown,
 release freshness/mutability) are reported but not auto-remediated. Remediation
 is organisation-scoped (`--scope org`, the default and only supported scope).
 
+The last two run **only when named** with `--category`, and the no-argument
+run never includes them: `code_quality`, because GitHub bills it,
+and `codeql_stale_configurations`, because it deletes data.
+
+### Enabling GitHub Code Quality
+
+GitHub Code Quality is billed per active committer and uses GitHub Actions
+minutes, so switching it on is a spending decision a routine run must not
+make:
+
+```bash
+# Preview: each repository with the languages it would get.
+uvx github-security-report remediate --org lfreleng-actions \
+  --category code_quality
+
+# Apply.
+uvx github-security-report remediate --org lfreleng-actions \
+  --category code_quality --apply
+```
+
+It acts on the rows of **Code Quality**, the Disabled and Partial
+repositories. Each one is configured for the union of the languages its
+setup already analyses and the ones its Linguist languages make applicable,
+so a write never drops a configured language; the dry run names them, as in
+`dependamerge (python, javascript-typescript)`. Not applicable and Unreadable
+repositories are never written. GitHub provisions the first analysis
+asynchronously. A `409` (an update already in progress), a `403` (an archived
+repository, or Code Quality not allowed for it) or a `422` fails that
+repository only and names the cause. The token needs the classic `repo`
+scope, or a fine-grained token's Administration: write. See
+[ADR-0006](docs/adr/0006-github-code-quality.md) for the reasoning.
+
 ### Cleaning up stale CodeQL configurations
 
-One category is **destructive**, so it runs only when named. The no-argument
-run never includes it:
+This category is **destructive**, so it runs only when named:
 
 ```bash
 # Preview: which configurations would go, and which are refused and why.

{github_security_report-0.18.0 → github_security_report-0.19.0}/README.md

@@ -32,7 +32,9 @@ states and rendered worst-first:
 
 Every category renders the same **standardised summary footer** beneath its
 table: remediation-first count lines (failures, disabled, unknown, then the
-healthy pass line, then excluded). The pass line reads **"All <state>"** when
+healthy pass line, then excluded). A category may add a note qualifying the
+pass line (Code Quality's per-language breakdown) and a **Not applicable**
+count, both shown on every surface. The pass line reads **"All <state>"** when
 nothing needs attention, or **"N <state>"** otherwise. The terminal and Slack
 stay brevity-first; the explanatory per-category description and documentation
 link are shown only on the richer Markdown and HTML (GitHub Pages) outputs.
@@ -110,6 +112,26 @@ tables (org mode):
   window a reviewed dependency update sits in while the vulnerability it fixes
   stays unpatched. Read from the batched GraphQL prefetch, so it costs no extra
   request; hide it with the `auto_merge` render toggle.
+- **Code Quality** — repositories where
+  [GitHub Code Quality](https://docs.github.com/en/code-security/concepts/code-quality/code-quality)
+  is **Disabled**, or **Partial**: configured, but without a language the
+  repository holds. Code Quality analyses six language families, so each
+  repository is first classified from its GitHub Linguist languages, read
+  from the batched GraphQL prefetch: Python (`python`), Go (`go`), Java and
+  Kotlin (`java-kotlin`), JavaScript and TypeScript
+  (`javascript-typescript`), Ruby (`ruby`) and C# (`csharp`). A repository
+  with none of them, such as one holding only shell scripts and workflow
+  files, is **Not applicable**: counted on a line of its own and never
+  reported as off. Only applicable repositories have their setup read, with
+  `GET /repos/{owner}/{repo}/code-quality/setup`; one whose setup or languages
+  cannot be read, or that holds more than the twenty languages the prefetch
+  reads, is counted as **Unreadable**, never as Disabled. The
+  **Missing** column names the languages each listed repository still needs,
+  and a footer line on every surface, the terminal included, gives the
+  enabled count out of the applicable count per language, such as
+  `python 30/32 · go 5/5 · javascript-typescript 10/12`. See
+  [ADR-0006](docs/adr/0006-github-code-quality.md); hide it with the
+  `code_quality` render toggle.
 
 The four enablement categories count the repositories with and without the
 feature (plus any whose state could not be read), and by default name whichever
@@ -148,7 +170,13 @@ signal is skipped and every other part of the report is unaffected, so the
 minimal tokens below omit it. Grant the org-admin permission only if you want
 ruleset-based tool coverage.
 
-A token without that permission gets a `404` from the endpoint, which the tool
+GitHub Code Quality is gated the same way: a fine-grained token needs
+repository Administration **write** to read a repository's Code Quality setup,
+even though the report only reads it. Without it every repository Code Quality
+applies to is reported as **Unreadable** in that one category; a classic PAT's
+`repo` scope already covers the read.
+
+A token without the org-admin permission gets a `404` from the endpoint, which the tool
 reports at **INFO** — so it is invisible unless you pass `--verbose`:
 
 ```text
@@ -168,7 +196,7 @@ A fine-grained PAT is bound to one resource owner, so it works for a report
 covering a **single** organisation. Create it with **Resource owner** set to the
 organisation and **Repository access** set to *All repositories*, then grant:
 
-**Repository permissions** (all Read-only):
+**Repository permissions** (Read-only unless noted):
 
 | Permission | Used for |
 | ---------- | -------- |
@@ -178,7 +206,7 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Code scanning alerts | CodeQL / Scorecard / zizmor / aislop findings |
 | Secret scanning alerts | Open secret-scanning alerts, across every GitHub pattern category |
 | Issues | Open issues and their labels (GitHub Issues table) |
-| Administration | Dependabot enablement + security-updates status, and effective branch rules |
+| Administration | Dependabot enablement + security-updates status, and effective branch rules. *Optional* **write** reads the Code Quality setup, which GitHub gates behind write |
 | Actions | Workflow state behind a stale CodeQL configuration |
 
 **Organization permissions:**
@@ -188,7 +216,7 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Administration | Read (write for rulesets) | *Optional*, and the only permission here with a write variant. **Read** keeps the token read-only and unlocks GitHub's secret-scanning pattern inventory (see below). **Write** additionally unlocks organisation rulesets (detecting tools enforced through an org ruleset), which GitHub gates behind Administration write. Omit the permission entirely to skip both; everything else is unaffected. |
 
 > Read-only is enough for everything except the optional ruleset coverage
-> above. A fine-grained token cannot span organisations. For a report covering
+> and the Code Quality setup read above. A fine-grained token cannot span organisations. For a report covering
 > more than one org, use a classic PAT (below).
 
 ### Multiple organisations — classic PAT
@@ -304,6 +332,7 @@ environment-variable name, never embedded.
     "issue_age_warn_days": 30,
     "issue_age_error_days": 60,
     "graph_batch": 10,
+    "concurrency": 9,
     "order": { "style": "auto" }
   },
   "organizations": [
@@ -419,10 +448,11 @@ Pages output. The valid category keys are: `codeql`,
 `zizmor`, `aislop`, `dependabot_alerts`, `secret_scanning`,
 `dependabot_alerts_enabled`, `dependabot_updates_enabled`,
 `dependabot_cooldown`, `releases`, `mutable_releases`,
-`private_vulnerability_reporting`, `auto_merge`, `github_issues`,
-`pull_requests`, `pull_requests_assigned`. Like the other `report` settings,
-`categories` can be set globally and overridden per organisation (overrides
-merge key-by-key, so flipping one output leaves the rest untouched). The
+`private_vulnerability_reporting`, `auto_merge`, `code_quality`,
+`github_issues`, `pull_requests`, `pull_requests_assigned`. Like the other
+`report` settings, `categories` can be set globally and overridden per
+organisation (overrides merge key-by-key, so flipping one output leaves the
+rest untouched). The
 machine-readable `report.json` artifact always contains the complete dataset,
 regardless of these toggles.
 
@@ -1236,10 +1266,13 @@ see the relationship reports it), but one naming an outsider proves nothing,
 because that is exactly how a private member appears to an under-privileged
 token. Those authors are reported as indeterminate rather than external, so
 `Ext` **undercounts and should be read as a lower bound** — the table says so in
-its description whenever this happens, and the run logs a warning. Membership is
-never used partially: a failed page or an organisation beyond the pagination
-guard is treated as unreadable rather than as a member list with people missing
-from it, since every absent member would otherwise read as an outsider.
+its description whenever this happens, and the terminal report prints one
+warning line under each affected organisation's heading, naming the cause: a
+token without the membership permission, a token whose account is not a member,
+or a read that failed. Membership is never used partially: a failed page or an
+organisation beyond the pagination guard is treated as unreadable rather than as
+a member list with people missing from it, since every absent member would
+otherwise read as an outsider.
 
 **Automation is never counted as external.** Bots are outsiders by association —
 `dependabot[bot]` genuinely reports `CONTRIBUTOR` or `NONE` — so counting on
@@ -1252,8 +1285,9 @@ association value GitHub has newly introduced — is **not** counted as external
 The column understates rather than inventing an outsider.
 
 **Permissions.** Reading organisation membership needs `read:org` (classic) or
-**Members: read** (fine-grained). Without it the tool logs a warning and
-reports externally-raised counts as a lower bound rather than guessing from
+**Members: read** (fine-grained). Without it the terminal report prints
+`⚠️ Token lacks read/organisation permission; results incomplete for <org>`
+and reports externally-raised counts as a lower bound rather than guessing from
 `authorAssociation` alone.
 
 ### Organisation feature gating
@@ -1301,16 +1335,25 @@ size is bounded by *latency*, not by rate-limit cost: 25 repositories measured
 at ~9 s against `lfreleng-actions` and failed intermittently; 10 measured at
 ~3.5 s.
 
+Up to four of these queries run at once. Each takes a few seconds on GitHub's
+side, so a prefetch issued one query at a time left most of the client's
+concurrency idle; against `lfreleng-actions` it took about 50 s of a 100 s run.
+
 `report.graph_batch` (default `10`; minimum `1`) sets the starting batch size,
 globally or per organisation. It is a lever for a slow day rather than a hard
 limit: a batch that still fails on size after the transport's own retries is
-re-issued at **half** the size, and the smaller size is kept for the rest of
-that organisation's collection (each organisation in a multi-org run starts
-from its own configured size, since organisations differ in how much data a
-repository carries). Only a single-repository query GitHub still cannot
-answer, or a failure that a smaller query could not fix (a `403`, an
-exhausted rate limit, or a `500`/`503` outage rather than a `502`/`504`
-timeout), aborts the run with exit code `3`.
+re-issued at **half** the size, and every batch issued after that failure is
+seen uses the smaller size for the rest of that organisation's collection
+(each organisation in a multi-org run starts from its own configured size,
+since organisations differ in how much data a repository carries). The
+learned size only shrinks. Because queries overlap, the batches already in
+flight when the first failure arrives were issued at the old size, so on a
+slow day up to four oversized batches, rather than one, may fail before the
+smaller size takes effect; that bounded cost buys the overlap. Only a
+single-repository query GitHub still cannot answer, or a failure that a
+smaller query could not fix (a `403`, an exhausted rate limit, or a
+`500`/`503` outage rather than a `502`/`504` timeout), aborts the run with
+exit code `3`, and the queries still in flight are cancelled first.
 
 The value can be set three ways, in this order of precedence:
 
@@ -1335,6 +1378,65 @@ a larger value buys nothing except a longer first failure.
 > predating the flag will reject a set one with `No such option`, so set
 > `GSR_GRAPH_BATCH` only once the pinned release supports it.
 
+### Client concurrency
+
+Each organisation's run holds at most `report.concurrency` requests to the
+GitHub API open at once (default `9`; minimum `1`, maximum `32`), globally or
+per organisation. Reads from the external Scorecard API queue on a separate
+limit of four, so a slow third-party endpoint never holds a slot that a
+GitHub request is waiting for.
+
+The value can be set three ways, in this order of precedence:
+
+1. `--concurrency N` on the command line (the action's `concurrency` input).
+2. A **repository or organisation variable** passed to that input. The
+   bundled `reporting.yaml` passes `vars.GSR_CONCURRENCY`, so the value can be
+   adjusted from repository settings without a workflow edit or a release.
+3. `report.concurrency` in the configuration; otherwise the built-in `9`.
+
+`9` is a deliberate halfway point. GitHub documents its secondary rate limits
+as no more than 100 concurrent requests across REST and GraphQL, and no more
+than 900 points per minute for REST endpoints; this project has hit those
+limits before, so the default stays well clear of them. Measured against
+`lfreleng-actions` (143 repositories, about 1,400 requests; one run each in
+the same hour, so read ±10–15 % as GitHub latency noise), before the GraphQL
+prefetch ran concurrently:
+
+<!-- markdownlint-disable MD013 -->
+
+| Concurrency | Wall | Throughput | Mean time per request | Average slots busy | GitHub pushback |
+| ----------- | ---: | ---------: | --------------------: | -----------------: | --------------- |
+| 6 (former default) | 102.5 s | 13.7 req/s | 0.283 s | 3.9 / 6 | none |
+| 12 | 75.9 s | 18.5 req/s | 0.286 s | 5.3 / 12 | none |
+
+<!-- markdownlint-enable MD013 -->
+
+Raise it once a run shows no pushback; lower it if GitHub starts answering
+with secondary rate-limit `403`/`429` responses. To measure a change, run the
+CLI with `--verbose`: when each organisation's collection finishes it logs
+one line of what the run cost, for example
+
+<!-- markdownlint-disable MD013 -->
+
+```text
+GitHub API for lfreleng-actions: 1402 requests (0 retries), 822 core points, 64 graphql points, 41.3 MiB received, 102.5 s
+```
+
+<!-- markdownlint-enable MD013 -->
+
+The request count is every request the tool issued, including retries and
+attempts that never got an answer. The points come from GitHub's own
+`x-ratelimit-*` response headers rather than from counting: GitHub meters a
+token across more than one bucket per resource (alike requests seconds apart
+can carry different `x-ratelimit-reset` values with independent counters), so
+each bucket's spread between its lowest and highest reading is summed per
+resource. The lowest reading already includes that request's own cost, so the
+figure is short by the first request of each bucket — a measurement aid, not a
+bill. Nothing of this line reaches the rendered report or the step summary.
+
+> As with `graph_batch`, an empty input is not passed to the tool, so set
+> `GSR_CONCURRENCY` only once the pinned release supports `--concurrency`.
+
 ### Pass/fail severity cutoff
 
 The severity-ranked signals (CodeQL, Scorecard, Zizmor, aislop, Dependabot
@@ -1413,6 +1515,7 @@ and the Slack **bot token** is consumed by the workflow, not the CLI.
 | `force_notify` | No | `false` | Post to Slack regardless of `report_day` |
 | `hide` | No | `""` | Category keys to suppress on every output (space- or comma-separated). Overrides config, and is one-way: it cannot re-enable a disabled category |
 | `graph_batch` | No | `""` | Repositories per batched GraphQL prefetch query (minimum `1`; default: config, else `10`). Pass a repository or organisation variable such as `${{ vars.GSR_GRAPH_BATCH }}` to adjust it from settings. A batch that still fails is halved automatically, so this sets the starting size (see [GraphQL prefetch batch size](#graphql-prefetch-batch-size)) |
+| `concurrency` | No | `""` | Concurrent GitHub API requests per organisation (`1` to `32`; default: config, else `9`). Pass a repository or organisation variable such as `${{ vars.GSR_CONCURRENCY }}` to adjust it from settings (see [Client concurrency](#client-concurrency)) |
 | `tool_version` | No | `""` | Published PyPI version to install. Empty (the default) uses the Dependabot-managed pin in `.github/runtime-pin/requirements.txt`; set a specific version to override. Ignored on pull requests or when `use_local_source` is `true` (both run from source) |
 | `use_local_source` | No | `false` | Run from the checked-out source instead of PyPI (for testing unreleased code from any event) |
 
@@ -1534,8 +1637,8 @@ the run, rather than falling back to every repository. The run then collects
 exactly the repositories that check validated, without listing the
 organisation again, and prints `Limited to:` beneath its heading.
 
-The remediable categories are the simple on/off features with a documented
-enablement endpoint:
+The remediable categories are the features with a documented enablement
+endpoint:
 
 | `--category` | Enables |
 |---|---|
@@ -1545,15 +1648,48 @@ enablement endpoint:
 | `dependabot_updates_enabled` | Dependabot security updates (plus alerts) |
 | `private_vulnerability_reporting` | Private vulnerability reporting |
 | `auto_merge` | The repository's "Allow auto-merge" setting |
+| `code_quality` | GitHub Code Quality, per language (named only; billed) |
+| `codeql_stale_configurations` | Stale CodeQL cleanup (named only; deletes) |
 
 Qualitative findings (Scorecard, zizmor, open Dependabot alerts, cooldown,
 release freshness/mutability) are reported but not auto-remediated. Remediation
 is organisation-scoped (`--scope org`, the default and only supported scope).
 
+The last two run **only when named** with `--category`, and the no-argument
+run never includes them: `code_quality`, because GitHub bills it,
+and `codeql_stale_configurations`, because it deletes data.
+
+### Enabling GitHub Code Quality
+
+GitHub Code Quality is billed per active committer and uses GitHub Actions
+minutes, so switching it on is a spending decision a routine run must not
+make:
+
+```bash
+# Preview: each repository with the languages it would get.
+uvx github-security-report remediate --org lfreleng-actions \
+  --category code_quality
+
+# Apply.
+uvx github-security-report remediate --org lfreleng-actions \
+  --category code_quality --apply
+```
+
+It acts on the rows of **Code Quality**, the Disabled and Partial
+repositories. Each one is configured for the union of the languages its
+setup already analyses and the ones its Linguist languages make applicable,
+so a write never drops a configured language; the dry run names them, as in
+`dependamerge (python, javascript-typescript)`. Not applicable and Unreadable
+repositories are never written. GitHub provisions the first analysis
+asynchronously. A `409` (an update already in progress), a `403` (an archived
+repository, or Code Quality not allowed for it) or a `422` fails that
+repository only and names the cause. The token needs the classic `repo`
+scope, or a fine-grained token's Administration: write. See
+[ADR-0006](docs/adr/0006-github-code-quality.md) for the reasoning.
+
 ### Cleaning up stale CodeQL configurations
 
-One category is **destructive**, so it runs only when named. The no-argument
-run never includes it:
+This category is **destructive**, so it runs only when named:
 
 ```bash
 # Preview: which configurations would go, and which are refused and why.