Skip to content

docs: retire hand-maintained CodeQL version table, point to GitHub Releases #178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
felickz merged 1 commit into from
Jul 11, 2026
Merged

docs: retire hand-maintained CodeQL version table, point to GitHub Releases #178

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions .github/workflows/update-codeql-version.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -224,7 +224,6 @@ jobs:
echo '- [ ] Check CI on this PR - fix any compilation/test errors caused by upstream'
echo ' API changes. This is usually the hardest part; consider delegating it to a'
echo ' Copilot coding agent session pointed at this PR/branch.'
echo '- [ ] Update the "Supported CodeQL versions" table in CONTRIBUTING.md.'
echo '- [ ] Review and merge - this alone will trigger the real batch publish.'
else
echo '**This PR does not publish anything by itself** - no pack `version:` field is'
Expand All @@ -235,7 +234,6 @@ jobs:
echo '- [ ] Check CI on this PR - fix any compilation/test errors caused by upstream'
echo ' API changes. This is usually the hardest part; consider delegating it to a'
echo ' Copilot coding agent session pointed at this PR/branch.'
echo '- [ ] Update the "Supported CodeQL versions" table in CONTRIBUTING.md.'
echo '- [ ] Review and merge.'
echo '- [ ] Once merged, run the "CodeQL Update Release" workflow'
echo ' (`update-release.yml`) to bump every pack'"'"'s `version:` in lockstep via'
Expand Down
58 changes: 36 additions & 22 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ After the query is merged, we welcome pull requests to improve it.

## Supported CodeQL versions

Every query pack in this repository is compiled and tested against a specific version of the upstream CodeQL standard libraries (e.g. `codeql/java-all`). These queries are **only guaranteed to compile** against the exact library versions shown below: newer or older CodeQL CLI/library versions may rename or remove APIs the queries depend on (see [#151](https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/151) for an example, and [#145](https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/issues/145) for the ongoing effort to refresh these pins).
Every query pack in this repository is compiled and tested against a specific, pinned version of the upstream CodeQL standard libraries (e.g. `codeql/java-all`). These queries are **only guaranteed to compile** against those exact library versions (see the latest release for the current versions): newer or older CodeQL CLI/library versions may rename or remove APIs the queries depend on (see [#151](https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/151) for an example, and [#145](https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/issues/145) for the ongoing effort to refresh these pins).

The pinning is codified per language across:
- [`.codeqlversion`][codeqlversion] (repo root): the CodeQL **CLI** version CI installs and compiles/tests against.
Expand All @@ -78,9 +78,9 @@ The pinning is codified per language across:
`codeql pack upgrade` is run against one directory but not the other, or one `qlpack.yml` pin is
hand-edited without the other) for them to drift apart. Always upgrade both when bumping
`.codeqlversion` (the [automated workflow](#updating-the-pinned-codeql-clilibrary-version) does this
for every pack directory in one pass); the table below only shows `src` for brevity, but the
auto-generated table in every publish summary (see [Cutting a release](#cutting-a-release)) checks
both and will flag drift between them.
for every pack directory in one pass); the auto-generated table in every publish summary (see
[Cutting a release](#cutting-a-release)) checks both `src` and `lib` independently and will flag
drift between them.

> [!WARNING]
> **Why `codeql/*` dependencies are pinned to an exact version instead of left as `'*'`:** they used
Expand Down Expand Up @@ -119,22 +119,36 @@ The pinning is codified per language across:
> `codeql/<pkg>: '*'`, that just means its dependencies haven't been re-resolved since, not that the
> convention doesn't apply to it.

CodeQL CLI: `v2.21.1` (released 2025-04-16) ([Bundle](https://github.com/github/codeql-action/releases/tag/codeql-bundle-v2.21.1) / [Binary](https://github.com/github/codeql-cli-binaries/releases/tag/v2.21.1))

| Language | Query pack | Standard library (`*-all`) | Upstream query pack (`*-queries`) | Lock file |
| --- | --- | --- | --- | --- |
| C/C++ | [codeql-cpp-queries](./cpp) | `codeql/cpp-all` 4.2.0 | `codeql/cpp-queries` 1.3.8 | [cpp/src/codeql-pack.lock.yml](./cpp/src/codeql-pack.lock.yml) |
| C# | [codeql-csharp-queries](./csharp) | `codeql/csharp-all` 5.1.4 | `codeql/csharp-queries` 1.1.1 | [csharp/src/codeql-pack.lock.yml](./csharp/src/codeql-pack.lock.yml) |
| Go | [codeql-go-queries](./go) | `codeql/go-all` 4.2.3 | *not used* | [go/src/codeql-pack.lock.yml](./go/src/codeql-pack.lock.yml) |
| Java/Kotlin | [codeql-java-queries](./java) | `codeql/java-all` 7.1.3 | *not used* | [java/src/codeql-pack.lock.yml](./java/src/codeql-pack.lock.yml) |
| JavaScript/TypeScript | [codeql-javascript-queries](./javascript) | `codeql/javascript-all` 2.6.1 | *not used* | [javascript/src/codeql-pack.lock.yml](./javascript/src/codeql-pack.lock.yml) |
| Python | [codeql-python-queries](./python) | `codeql/python-all` 4.0.5 | *not used* | [python/src/codeql-pack.lock.yml](./python/src/codeql-pack.lock.yml) |
| Ruby | [codeql-ruby-queries](./ruby) | `codeql/ruby-all` 4.1.4 | *not used* | [ruby/src/codeql-pack.lock.yml](./ruby/src/codeql-pack.lock.yml) |

Most of our query packs only depend on the standard library (`*-all`) for CodeQL's core language APIs. C/C++ and C# are the exception: their `qlpack.yml` also declares a dependency on the upstream `codeql/<language>-queries` pack, because one query (`audit/explore/Dependencies.ql`) reuses a `Metrics.Dependencies` helper that ships with the upstream query pack rather than the standard library. That's an extra surface area those two languages need to stay compatible with.

> [!NOTE]
> This table is maintained by hand today; update it whenever `.codeqlversion` or the `codeql-pack.lock.yml` files are refreshed. For a broader mapping of CodeQL CLI/bundle versions to per-language library versions (useful when triaging why a query compiles locally but not in CI, or vice versa), see the community [CodeQL Bundle Version Tracker](https://github.com/advanced-security/advanced-security-material/blob/main/codeql/codeql-version-tracker.md).
**This section no longer hand-maintains a version table** - it used to, but that table went stale
across multiple CLI bumps in a row (nobody remembered to update it, and there was no CI check
enforcing it) while the *real* answer was already being generated automatically and posted
somewhere more visible. Don't add one back here; see below for where to actually look.

To find the CodeQL CLI/library versions this repo currently builds and tests against:

- **[Latest GitHub Release][latest-release]** - every release's notes include an auto-generated
**"CodeQL standard library & query pack versions"** table (produced by `publish.yml`'s `summary`
job, see [Cutting a release](#cutting-a-release)), comparing every language's locked `codeql/*`
dependency - independently for both `src` and `lib`, since they're separately-resolved lock files
that can drift apart - against what [github/codeql][codeql-repo] itself ships for that exact CLI
version, with a ✅/mismatch status per row and a direct link to the exact file/line on both sides
(our lock file, upstream's `qlpack.yml`) so any claim can be verified with one click. This is
always in sync with what's actually on `main` at release time, because it's generated from the
real lock files, not typed by hand.
- **[`.codeqlversion`][codeqlversion]** (repo root) directly, if you just need the pinned CLI
version and don't need the per-language library breakdown.

For a broader mapping of CodeQL CLI/bundle versions to per-language library versions (useful when
triaging why a query compiles locally but not in CI, or vice versa), see the community
[CodeQL Bundle Version Tracker](https://github.com/advanced-security/advanced-security-material/blob/main/codeql/codeql-version-tracker.md).

Most of our query packs only depend on the standard library (`*-all`) for CodeQL's core language
APIs. C/C++ and C# are the exception: their `qlpack.yml` also declares a dependency on the upstream
`codeql/<language>-queries` pack, because one query (`audit/explore/Dependencies.ql`) reuses a
`Metrics.Dependencies` helper that ships with the upstream query pack rather than the standard
library. That's an extra surface area those two languages need to stay compatible with, which is
why the version table in each release shows an extra `codeql/<language>-queries` row for those two
languages that the others don't have.

## Releases & publishing

Expand Down Expand Up @@ -244,15 +258,13 @@ coding agent) in the loop for the hard part — fixing whatever the new CLI brea
[`copilot-setup-steps.yml`][copilot-setup-steps-workflow] pre-installs the pinned
CodeQL CLI and the matching `github/codeql` test-stubs checkout so the agent can
actually run `codeql test run` itself instead of guessing.
- [ ] Update the "Supported CodeQL versions" table above.
- [ ] Review and merge.
- [ ] Once merged, run [`update-release.yml`][update-release-workflow] as described in
[Cutting a release](#cutting-a-release) below to bump every pack's `version:` in
lockstep and trigger the real batch publish.
- **With `release_bump` set** — merging this PR *is* the release; there's no separate follow-up
step:
- [ ] Fix any compilation/test errors CI surfaces from upstream API changes, same as above.
- [ ] Update the "Supported CodeQL versions" table above.
- [ ] Review and merge — this alone triggers the real batch publish and the same
`summary` job / GitHub Release upsert described in
[Cutting a release](#cutting-a-release) below.
Expand Down Expand Up @@ -406,6 +418,8 @@ Please do get in touch (privacy@github.com) if you have any questions about this
[release-config]: ./.release.yml
[patch-release-me]: https://github.com/42ByteLabs/patch-release-me
[releases]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/releases
[latest-release]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/releases/latest
[codeql-repo]: https://github.com/github/codeql
[ghcr-packages]: https://github.com/orgs/GitHubSecurityLab/packages?repo_name=CodeQL-Community-Packs
[pr-118]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/118
[pr-124]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/124
Expand Down
Loading