From 7aff54cf181e38cbd8d38ecd9a2ab2e2174d68ca Mon Sep 17 00:00:00 2001 From: Chad Bentz <1760475+felickz@users.noreply.github.com> Date: Mon, 6 Jul 2026 13:30:36 -0400 Subject: [PATCH 1/2] docs: document CodeQL version pinning and pack compatibility - Add a consumer-facing compatibility note in README linking to GitHub's official CodeQL pack compatibility docs, reassuring users that older published packs generally keep working with newer CLIs (with caveats). - Add a maintainer-facing 'Supported CodeQL versions' section in CONTRIBUTING.md documenting the two-file pinning mechanism (.codeqlversion for the CLI, /src/codeql-pack.lock.yml for the locked library version) with a table of current locked versions per language, including the upstream *-queries dependency used by C/C++ and C# only. - Link out to the community CodeQL Bundle Version Tracker for the broader CLI-to-library version mapping. Motivated by GHSL PR #151 (java-all API rename between 7.1.3 and 9.1.2 causing local/CI compile mismatches) and issue #145 (stale packs). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 29 +++++++++++++++++++++++++++++ README.md | 7 +++++++ 2 files changed, 36 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 167a408b..76ee3ee9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,8 +60,37 @@ Queries and libraries may not be actively maintained as the supported libraries 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). + +The pinning is codified in two places per language: +- [`.codeqlversion`][codeqlversion] (repo root) — the CodeQL **CLI** version CI installs and compiles/tests against. +- `/src/codeql-pack.lock.yml` — the exact resolved (locked) version of `codeql/-all` and its transitive dependencies, generated by `codeql pack install` against the CLI above. The `qlpack.yml` files themselves only declare an unpinned `'*'` range, so the lock file — not the qlpack.yml — is the real source of truth. + +CodeQL CLI: [`v2.21.1`](https://github.com/github/codeql-action/releases/tag/codeql-bundle-v2.21.1) (released 2025-04-16) + +| 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/-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). + ## Using your personal data If you contribute to this project, we will record your name and email address (as provided by you with your contributions) as part of the code repositories, which are public. We might also use this information to contact you in relation to your contributions, as well as in the normal course of software development. We also store records of CLA agreements signed in the past, but no longer require contributors to sign a CLA. Under GDPR legislation, we do this on the basis of our legitimate interest in creating the CodeQL product. Please do get in touch (privacy@github.com) if you have any questions about this or our data protection policies. + + + +[codeqlversion]: ./.codeqlversion diff --git a/README.md b/README.md index 87392c95..03db2992 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,9 @@ Collection of community-driven CodeQL query, library and extension packs. ## Getting started +> [!NOTE] +> These packs are published with precompiled queries, so a pack built against an older CodeQL CLI generally keeps working with a newer one too — see [CodeQL pack compatibility](https://docs.github.com/en/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs#codeql-pack-compatibility) for how that works. If you're curious which CodeQL CLI version we currently build and test against, see [Supported CodeQL versions](./CONTRIBUTING.md#supported-codeql-versions) in CONTRIBUTING.md. + ### Default query suites Using a `githubsecuritylab/codeql-LANG-queries` query pack will reference the default suite for that pack (e.g. `python.qls` for python). However, you may use a different suite such as `python-audit.qls` by referencing the query pack with the following syntax: `githubsecuritylab/codeql-python-queries:suites/python-audit.qls`. The examples below work for both syntaxes. @@ -68,6 +71,10 @@ This project is licensed under the terms of the MIT open source license. Please Please [create GitHub issues](https://github.com/advanced-security/brew-dependency-submission-action) for any feature requests, bugs, or documentation problems. +## Contributing + +We welcome contributions — see [CONTRIBUTING.md](./CONTRIBUTING.md) for how to submit a new query or improve an existing one, and for the CodeQL CLI/library versions we currently build and test against. + [configurations]: ./configs From bdd8f2e84fb9b042ad6ffd7436f7b5fd5a390c9b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 6 Jul 2026 17:42:55 +0000 Subject: [PATCH 2/2] docs: split CodeQL CLI references into Bundle and Binary links --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 76ee3ee9..5e8667a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,7 +68,7 @@ The pinning is codified in two places per language: - [`.codeqlversion`][codeqlversion] (repo root) — the CodeQL **CLI** version CI installs and compiles/tests against. - `/src/codeql-pack.lock.yml` — the exact resolved (locked) version of `codeql/-all` and its transitive dependencies, generated by `codeql pack install` against the CLI above. The `qlpack.yml` files themselves only declare an unpinned `'*'` range, so the lock file — not the qlpack.yml — is the real source of truth. -CodeQL CLI: [`v2.21.1`](https://github.com/github/codeql-action/releases/tag/codeql-bundle-v2.21.1) (released 2025-04-16) +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 | | --- | --- | --- | --- | --- |