A CodeQL query pack is more than a folder of .ql files. It is a versioned artifact that can be shared, published to the GitHub Container registry, and consumed by other analyses. That makes its file boundary worth treating as a security and reproducibility boundary.
CodeQL CLI 2.27.4, released on November 2, 2026, adds a useful guard at that boundary. The codeql pack bundle and codeql pack publish commands now resolve symbolic links while checking files for inclusion. If a link resolves outside the pack root, CodeQL omits that file and emits a warning.
This is a focused hardening change, not a replacement for dependency review or artifact governance. The practical lesson is simple: update the CLI, make the pack root explicit, inspect links before bundling, and treat warnings as release-blocking until you understand them.
Why a pack root matters
The root of a CodeQL pack is the directory containing its qlpack.yml. GitHub's documentation uses that file to define the pack name, version, dependencies, and optional default query suite. A typical query pack might look like this:
my-checks/
├── qlpack.yml
├── codeql-pack.lock.yml
├── queries/
│ ├── unsafe-redirect.ql
│ └── unsafe-redirect.qlref
└── tests/
The important boundary is my-checks/. Files physically below that directory are candidates for the pack. A symbolic link can make the apparent layout misleading, however. For example, an author might place shared queries in a neighboring directory and link to them:
workspace/
├── shared-queries/
│ └── common.ql
└── my-checks/
├── qlpack.yml
└── queries/
└── common.ql -> ../../shared-queries/common.ql
That link is convenient during development, but its target is outside my-checks/. A published archive that follows it is no longer a self-contained snapshot of the pack directory. It could also include content that a reviewer did not expect to ship.
The example is illustrative and was not executed in this environment. The point is the boundary: a directory listing alone does not tell you where every symlink ultimately leads.
What changed in CodeQL 2.27.4
The 2.27.4 changelog describes the behavior precisely: both codeql pack bundle and codeql pack publish check that each file added to the archive remains inside the pack root after symbolic links are resolved. A file that resolves outside that root is omitted, and CodeQL prints a warning.
That gives pack authors two useful properties:
- A link cannot silently expand the archive beyond the directory being packaged.
- The warning provides a review signal when the source layout does not match the intended artifact.
The protection is applied at bundling and publishing time. It does not mean every link in your repository is bad, and it does not decide whether a file inside the root is appropriate for your project. It enforces one narrow rule: the resolved file must stay within the pack root.
The same release also moves Java virtual machine warnings and initialization errors to standard error rather than standard output. That matters if a CI job parses JSON or another machine-readable output stream. It is separate from the path-boundary check, but upgrading can make automated log handling more predictable.
A safer pack-author workflow
1. Create a real pack root
Start with the documented CLI flow, or confirm that an existing pack has one unambiguous directory containing qlpack.yml:
codeql pack init example-org/my-checks
cd my-checks
For a query pack, the generated manifest is the starting point. Library packs must explicitly declare library: true; model packs have additional requirements and are still documented as public preview. Do not copy a manifest from an unrelated pack without checking its pack type and dependencies.
Before publishing, review at least:
name: example-org/my-checks
version: 1.0.0
description: Checks for the example service
dependencies:
codeql/javascript-all: ^2.3.0
The version and dependency ranges here are examples, not recommendations for a particular project. Use versions compatible with your own analysis setup.
2. Inspect links and generated files
Look for symbolic links before asking the CLI to produce an artifact. On a Unix-like system, an author could use:
find . -type l -print -exec readlink -f {} \;
For every result, ask whether the resolved target is intentionally part of this pack. A link that leaves the pack root should normally be replaced with a file inside the root, copied during a deliberate build step, or removed from the published layout.
Also check files created by the tooling. For query and library packs, codeql pack install generates codeql-pack.lock.yml with precise dependency versions. GitHub recommends checking that lockfile into version control. It makes dependency resolution easier to review and repeat, but it does not make an unexpected source file safe to publish.
3. Bundle before you publish
Use a local bundle step as a release review point:
codeql pack install
codeql pack bundle . --output=dist/my-checks-1.0.0.tgz
The exact output option and destination should follow the CLI version used by your project. The command above is a documented usage pattern, not a command run for this article.
Read the command output. With 2.27.4 or newer, a symlink that resolves outside the root should produce a warning and be omitted. Do not treat that as harmless noise: compare the warning with the intended pack contents. If the file was required, fix the layout and bundle again. If it was accidental, the omission is the desired result.
An archive listing is another useful review step when your environment has a compatible archive tool:
tar -tzf dist/my-checks-1.0.0.tgz
This confirms what names are in the resulting tarball. It does not prove that the queries are correct or that all dependencies are safe, so it belongs alongside manifest, lockfile, and query review.
4. Publish only the reviewed artifact
Once the bundle contains the intended files, publish from the pack root:
GITHUB_TOKEN="$TOKEN_FROM_YOUR_CI_SECRET_STORE" codeql pack publish
Do not paste a real token into a repository, shell history, article, or build log. GitHub also documents --github-auth-stdin as an authentication option. Choose the least-privileged credential and registry visibility appropriate for the pack.
For a controlled release, make the version in qlpack.yml, the reviewed bundle, and the published package reference the same release. If a CI job builds from a moving branch and publishes without a reviewable artifact boundary, the new symlink check reduces one risk but does not make the overall release process reproducible.
What this fix does not cover
The root check is valuable because it closes a specific packaging ambiguity. It should not be overinterpreted.
It does not replace dependency locking. A pack can stay inside its root while depending on an unwanted or changed external pack. Keep codeql-pack.lock.yml under review and understand the version ranges in qlpack.yml.
It does not validate query behavior. A syntactically valid archive can still produce noisy results, miss a vulnerability, or contain a broken query. Run the pack's tests and analysis checks in the normal environment.
It does not sign the artifact. The release note describes path checking and omission, not signing, provenance attestations, or registry policy. Those controls belong in the repository and release design around CodeQL.
It does not make publishing risk-free. Authentication, package visibility, permissions, and retention still need explicit decisions. A public pack should contain only material intended for public distribution.
It does not make every old CLI equivalent. The symlink behavior is documented for 2.27.4. Pin the CLI version in CI or otherwise verify the version used to create the release artifact, rather than assuming a developer workstation and the release runner behave identically.
A compact CI checklist
Before publishing a CodeQL pack, confirm:
- The release runner uses CodeQL CLI 2.27.4 or a later version with the required fix.
qlpack.ymlis at the intended pack root and has the correct name, type, version, and dependencies.codeql-pack.lock.ymlis present where the pack type supports dependencies and has been reviewed.- Symbolic links have been enumerated, and every resolved target is intentionally inside the root.
codeql pack bundlecompletes without unexplained warnings.- The generated archive is inspected before publication.
- Tests and analysis checks pass in the project's supported environment.
- Publishing credentials come from the CI secret store and are not printed.
- Consumers can select an explicit pack version when repeatability matters.
The 2.27.4 change is small, but it improves the contract that matters: the package you publish should not silently reach outside the directory you reviewed. Treat the warning as part of your release review, keep the pack and its dependencies versioned, and publish only the artifact you can explain.