From 312635ce6256973d8b0745ceef399f924e4eee33 Mon Sep 17 00:00:00 2001 From: Leonid Svyatov Date: Tue, 11 Aug 2026 20:17:02 +0300 Subject: [PATCH] docs(oss-harden): update Code Quality for general availability The Code Quality paragraph was written during the public preview. It says the product must be turned on per repository or organization, which reads as a switch every reader has. Code Quality reaches organization-owned repositories on GitHub Team or GitHub Enterprise Cloud only, so a user-owned repository cannot enable it at all, and that filter settles most cases before cost or syntax matters. Its cost also stopped being deferred on 2026-07-20. GitHub now documents the code quality REST endpoints, so the prohibition on adding the rule where the product is off becomes a command a reader can run. `GET /repos/{owner}/{repo}/code-quality/setup` answers `configured`, `not-configured`, or 404 for a repository the plan excludes. The rulesets REST schema still documents `code_scanning` and no code quality rule, so that caution stands as written. --- AGENTS.md | 2 +- CHANGELOG.md | 1 + skills/oss-harden/references/github.md | 12 +++++++++++- 3 files changed, 13 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d0f4d58..5e41daa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,7 +100,7 @@ R-SEC-05 is met: `git cat-file -t v0.13.0` prints `tag`, and `git tag -v v0.13.0 R-SEC-04 is met, and R-SEC-09 is open for fork pull requests. The default branch is guarded by a repository ruleset named `main`, scoped to `~DEFAULT_BRANCH` rather than the literal branch name so renaming the branch cannot unguard it. It requires a pull request, resolved review threads, squash as the only merge method, and the four checks CI reports, and it rejects force pushes, deletion, and non-linear history. It requires no approving review, because R-SEC-12 does not reach a repository with one principal and R-SEC-04 no longer asks for one. Expect `Branch-Protection` in an OpenSSF Scorecard result to read 3 of 10 for that reason: its tiers gate each other, review is tier 2, and status checks are tier 3. That is the intended state, not a regression. Read the ruleset with `gh api repos/svyatov/oss-kit/rulesets`, not with the classic `branches/main/protection` endpoint: this repository has no classic branch protection rule, so that endpoint answers `404 Branch not protected`, which reads like an unguarded branch and is not one. Code scanning runs through CodeQL advanced setup, at `.github/workflows/codeql.yml`, and default setup is off. It used to be the other way round, and two things forced the move. Default setup returns a neutral verdict on a pull request that changes no analyzable code, because it has nothing to compare against the default branch, and the ruleset's `code_scanning` rule blocks on neutral, so a release, which only ever touches three plugin manifests and the changelog, was unmergeable. Default setup also excludes fork pull requests, while this repository routes every external contribution through a fork, so R-SEC-09 was open on the path that matters most. The workflow carries no path filter, which is what makes a verdict always arrive. Its matrix names `actions` and `javascript-typescript`, two languages where default setup reported four: `javascript-typescript` is the identifier covering both JavaScript and TypeScript, so naming all four analyzed the same tree three times. Do not add `paths-ignore` to it, because that reintroduces the neutral verdict this workflow exists to prevent. -The ruleset also carries a `code_scanning` rule requiring CodeQL at `security_alerts_threshold: high_or_higher` and `alerts_threshold: errors`, which blocks on what the analysis found where a required status check would only block on whether it reported. It used to carry a `code_quality` rule at `severity: errors` beside it, and that rule is gone. `gh api repos/svyatov/oss-kit/code-quality/setup` answers `404 Code quality is not available for this repository`, so the rule named a tool that can never report. `skills/oss-harden/references/github.md` already said not to add it to a repository where Code Quality is off, for exactly that reason, and this repository had done it anyway. Do not restore it unless that endpoint starts answering. +The ruleset also carries a `code_scanning` rule requiring CodeQL at `security_alerts_threshold: high_or_higher` and `alerts_threshold: errors`, which blocks on what the analysis found where a required status check would only block on whether it reported. It used to carry a `code_quality` rule at `severity: errors` beside it, and that rule is gone. `gh api repos/svyatov/oss-kit/code-quality/setup` answers `404 Code quality is not available for this repository`, so the rule named a tool that can never report. `skills/oss-harden/references/github.md` already said not to add it to a repository where Code Quality is off, for exactly that reason, and this repository had done it anyway. Code Quality went generally available on 2026-07-20, so the 404 is no longer a preview gap. The product reaches organization-owned repositories on GitHub Team or GitHub Enterprise Cloud, and this repository is owned by a user, so the endpoint cannot start answering while that holds. Re-checked on 2026-08-11: still 404. Moving the repository to an organization on one of those plans is the event that would change it, and nothing short of that warrants restoring the rule. A ruleset has no "Do not allow bypassing the above settings" checkbox; the equivalent is its bypass list, and this one is empty. Nothing here exempts the owner from anything. It used to hold `RepositoryRole` `5`, Repository admin, at `pull_request` mode, which existed for one reason: the ruleset required an approving review, nobody can approve their own pull request, and without the exemption every change the sole maintainer opened was unmergeable. Dropping the review requirement removed the reason, so the entry went too, and the ruleset now binds the owner as tightly as anybody else. Confirm it from the create or read response, where `bypass_actors` reads `[]` and `current_user_can_bypass` reads `never`. Do not restore the entry to unblock a merge; a required approval nobody can give, undone by an exemption for the only person it named, is strictly weaker than not requiring it. diff --git a/CHANGELOG.md b/CHANGELOG.md index 309a58b..4e56196 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ The format is based on [Keep a Changelog 2.0.0](https://keepachangelog.com/en/2. - The documented install is `npx skills add svyatov/oss-kit`. The `--skill '*'` flag existed to preselect nine loose rows in the picker, and 0.14.0 replaced those rows with one select-all row, so the flag now only repeats what a single keystroke does. - `oss-skill` says a repository documenting a whole-collection install groups its skills through a plugin manifest rather than through `--skill '*'`. The reference recommended the flag, which was the only answer before the CLI read a manifest for groupings. +- `oss-harden` prices GitHub Code Quality at its general availability rate, says the product reaches organization-owned repositories on GitHub Team or GitHub Enterprise Cloud only, and gives the setup command that decides whether the `code_quality` ruleset rule can be added at all. The paragraph was written during the public preview, when the cost was deferred and the availability limit was unstated. ## [0.14.0] - 2026-08-11 diff --git a/skills/oss-harden/references/github.md b/skills/oss-harden/references/github.md index 769a943..5cef59e 100644 --- a/skills/oss-harden/references/github.md +++ b/skills/oss-harden/references/github.md @@ -425,7 +425,17 @@ gh api repos/{owner}/{repo}/code-scanning/default-setup --jq '{state, languages} A `tool` name that matches nothing the repository reports reads as "not configured" and blocks every merge, so verify the name before the rule goes active. -GitHub Code Quality adds a second rule of the same shape, `code_quality`, whose `parameters.severity` names the level at or above which a result blocks the merge; `errors` is the value verified against a live ruleset. Two cautions belong with any recommendation of it. It is absent from the rulesets REST reference, which documents `code_scanning` and not this rule, so the API accepting it is currently better evidence than the reference is. And it is a licensed product that must be turned on per repository or organization and that consumes Actions minutes for its CodeQL passes plus per-seat licensing and AI credits for the rest, so name that cost before proposing it, and do not add the rule to a repository where Code Quality is not already on: a rule requiring a tool that never reports blocks every merge. R-SEC-09 does not require it, and CodeQL default setup with the `code_scanning` rule satisfies the rule on its own. +GitHub Code Quality adds a second rule of the same shape, `code_quality`, whose `parameters.severity` names the level at or above which a result blocks the merge. `errors` is the value verified against a live ruleset, and the rules reference names the levels Errors, Warnings and higher, and All. Check availability first, because it settles most cases in one step. The product reaches organization-owned repositories on GitHub Team or GitHub Enterprise Cloud. It does not run on GitHub Enterprise Server, and a user-owned repository cannot enable it at all. Price it before proposing it. It went generally available on 2026-07-20 at 10 US dollars per active committer per month. A committer counts as active for 90 days after a push, and once per organization. Add metered usage for the AI analysis and Actions minutes for the CodeQL passes. + +Note that `code_quality` is absent from the rulesets REST schema, which documents `code_scanning` and not this rule. The API accepting it is better evidence than that reference is. The branch rule is documented under its interface name, Require code quality results. + +Read the setup back before adding the rule: + +```bash +gh api repos/{owner}/{repo}/code-quality/setup --jq '{state, languages}' +``` + +`state` reads `configured` or `not-configured`. A 404 reading `Code quality is not available for this repository` means the plan or the ownership excludes the product, rather than that somebody switched it off. Add the rule only on `configured`. On the other two answers it names a tool that never reports, and blocks every merge with nothing to read. R-SEC-09 does not require it, and CodeQL default setup with the `code_scanning` rule satisfies the rule on its own. ## Detection controls (R-SEC-10, R-SEC-11)