Use the combined bundle when queries may need other languages' library packs

[henrymercer]

We support custom configuration files that include packs for other languages, for example:

name: Use custom queries
disable-default-queries: true
queries:
  ...
  - name: Go queries
    uses: codeql-testing/go-querypack@master
  - name: Cpp queries
    uses: codeql-testing/cpp-querypack@second-branch
  - name: JavaScript queries
    uses: codeql-testing/javascript-querypack/show_ifs2.ql@master
  - name: Python queries
    uses: codeql-testing/python-querypack/show_ifs2.ql@second-branch

as taken from our PR checks.

If these custom queries live in compiled packs, then the packs ship their own dependencies. However if the custom query is just a path to a QL file, then the dependencies are resolved from a bundle.

This creates an issue with per-language bundles: CodeQL resolves every configured query before selecting the ones for the analyzed language, so a single-language analysis with a configuration like the above will fail. This is evidenced by failures in the "Go: Custom queries" and "Start proxy" PR checks when using per-language bundles.

This PR only selects a per-language bundle when the query configuration known before CodeQL is set up can't reference such queries: there's no configuration file, the config input is unset or only sets threat models and model packs like default setup's does, and the queries input and github-codeql-extra-queries repository property only name built-in query suites. This avoids loading configuration files before setting up CodeQL, at the cost of using the combined bundle for configuration files that only use built-in queries.

This PR also modifies setup-codeql to always use the combined bundle, since it can't tell whether the queries that a workflow runs with the CLI will need library packs for other languages. A separate commit corrects the docs for its languages and analysis-kinds inputs, which said to also pass them to init, even though init fails if setup-codeql has run in the same job.

It also disables per-language bundles in the "Export file baseline information" PR check, since a per-language bundle only reports file baseline information for its own language. The second commit moves defaultSuites so that per-language-bundles.ts can use it without an import cycle.

Finally, it moves per-language bundles to a new per_language_bundles_v2 feature flag, so that we can roll them out to Action versions that include this fix without also enabling them for earlier versions.

Risk assessment

Low risk: The change only affects bundle selection when the per_language_bundles or per_language_bundles_v2 feature flag is enabled.

Which use cases does this change impact?

Workflow types:

• Advanced setup - Single-language analyses with a configuration file, a config input, or queries that aren't built-in query suites, and workflows that pass a single language to setup-codeql.
• Managed - Default setup analyses that get a configuration file, or queries that aren't built-in query suites, from repository properties.

Products:

• Code Scanning
• Code Quality

Environments:

• Dotcom - Per-language bundles are only selected on GitHub.com.

How did/will you validate this change?

• Unit tests - Each source of query configuration, and bundle selection for releases and nightlies. The setup-codeql Action's entry point has no unit tests, so its reason is only covered indirectly.
• End-to-end tests - "Go: Custom queries" and "Start proxy" use configuration files that reference other languages' queries, so they cover this change whenever they download a bundle with per-language bundles enabled.

If something goes wrong after this change is released, what are the mitigation and rollback strategies?

• Feature flags - Disable per-language bundle selection with per_language_bundles_v2.

How will you know if something goes wrong after this change is released?

• Telemetry - Monitor init failures in analyses that use a per-language bundle.

Are there any special considerations for merging or releasing this change?

• No special considerations - This change can be merged at any time.

Merge / deployment checklist

• Confirm this change is backwards compatible with existing workflows.
• Consider adding a changelog entry for this change.
• Confirm the readme and docs have been updated if necessary.

[Copilot]

Warning

• Copilot's review of this pull request may be incomplete because some of the changed files are excluded by your Copilot content exclusion settings. See Excluding content from Copilot for details.

Copilot review overview

🟢 Approval recommended

Bundle eligibility is consistently propagated and covered by focused tests without unresolved correctness issues.

Review effort: Balanced
Findings: None

What changed in this PR

Updates bundle selection to use combined bundles whenever configured queries may depend on other languages’ library packs.

Changes:

• Detects query configurations requiring combined bundles.
• Propagates bundle-selection reasoning through CodeQL setup.
• Updates tests, documentation, and PR-check configuration.

File	Description
src/​per-language-bundles.ts	Adds query eligibility logic.
src/​per-language-bundles.test.ts	Tests eligibility and explanations.
src/​setup-codeql.ts	Applies eligibility to release and nightly bundles.
src/​setup-codeql.test.ts	Tests combined-bundle selection.
src/​setup-codeql-action.ts	Forces combined bundles for standalone setup.
src/​init-action.ts	Collects query configuration inputs.
src/​init.ts	Propagates bundle-selection reasoning.
src/​codeql.ts	Propagates setup options.
src/​codeql.test.ts	Updates setup calls.
src/​upload-lib.ts	Updates initialization call.
src/​config/​db-config.ts	Centralizes built-in suite names.
src/​analyze.ts	Uses centralized suite names.
src/​analyze.test.ts	Updates suite import.
setup-codeql/​action.yml	Corrects input documentation.
pr-checks/​checks/​export-file-baseline-information.yml	Disables per-language bundles for the baseline check.
lib/​entry-points.js	Generated output; excluded from review.
.github/​workflows/​__export-file-baseline-information.yml	Generated workflow; excluded from review.

Files excluded by content exclusion policy (2)

• .github/workflows/__export-file-baseline-information.yml
• lib/entry-points.js

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mbg]

Thank you for taking care of this! I think this approach makes sense to work around the issue. Query customisation is reasonably rare so that this still allows most users to benefit from per-language bundles, while avoiding any issues like we saw in CI for those that do customise them.

I left a few comments, with one or two points about long-term maintainability and otherwise minor comments. So, generally this looks pretty good already and it shouldn't be far off from being ready to merge.

[mbg]

Minor: Prefer placing the comment above the relevant line, rather than at the end of it.

[henrymercer]

I feel the other way — I'll leave this as is, but open to discussing this in general and updating the linter configuration.

[mbg]

Minor: Consider creating an enum for the reasons, returning a value of that enum here, and then mapping to a string when needed.

[henrymercer]

I can see some value in listing all the reasons, but since we also have values associated with the reasons (e.g. the config file path), I don't listing the reasons is worth the complexity.

[mbg]

Long-term issue: if our hard-coded assumption about dynamic workflows ever changes in any of the products that use dynamic workflows, then this will be quite tricky to track down. Perhaps to guard a little again that and be extra defensive, consider introducing a constant somewhere along the lines of ASSUME_DEFAULT_SETUP_CONFIG_NO_QUERIES with a suitable comment and factor that into the logic here.

[henrymercer]

Are you thinking of adding an environment variable to the default setup template as an indicator of when we can no longer assume that the default setup config won't specify custom queries? Perhaps it would be simpler to indeed parse the config input and check that it only has the properties we expect?

[henrymercer]

Perhaps it would be simpler to indeed parse the config input and check that it only has the properties we expect?

I've implemented this.

[mbg]

That seems like a better approach, thanks!

[mbg]

Thank you for addressing the comments from my previous review! I've had some more comments on the changes here. The main ones are again related to the maintainability of duplicated logic and whether we can reduce that or move some of the work to a common place before any of the consumers.

[mbg]

Minor: This comment is largely about how this function is used, not what it does. I.e. this function is completely disconnected from the queries input and doesn't control how the returned combines value is interpreted by the caller.

[mbg]

Minor: Same issue with this comment as with the one for parseQueriesInput.

[mbg]

This function is essentially the same as parseQueriesInput, except that it provides the additional argument to parseQueriesFromInput. When I added the repo property, I added the extra, optional parameter to parseQueriesFromInput so that the function could be shared between the two uses.

Consider whether parseQueriesInput could have a second, optional parameter for the error like parseQueriesFromInput does to avoid having a mostly duplicate parseExtraQueriesProperty or whether we could move the shouldCombine call into parseQueriesFromInput.

[mbg]

Thanks for changing this to better reuse the existing implementation!

Another concern here, which I don't think is blocking for this PR, is that getOtherLanguagePacksReason is more conservative than it needs to be. Specifically, we ignore the combines property and so are ignoring the precedence / combination rules that are implemented in combineQueries. Since that may discard some of the configured queries if others take precedence / don't allow combining, not all of the configured queries may actually end up getting passed to the CLI. If that is the case, then we might disable per-language bundles here even though we may not need to. Since this is more conservative than necessary, it is fine as-is, but we could look into reusing more of the combineQueries logic here to ensure consistency and to allow per-language bundles in more cases.

[mbg]

Observation: getOtherLanguagePacksReason will now throw if parseQueriesInput or parseExtraQueriesProperty throws. Previously, getOtherLanguagePacksReason would never have thrown an error.

It's probably fine because the circumstances under which an error is thrown here would lead to an error later on in any case, but it moves that error to an earlier point in the execution.

I don't think that's an issue because I don't think there's anything happening in-between the two throwing sites that would particularly matter, but if we wanted to be more conservative then we could catch the exceptions in getOtherLanguagePacksReason and treat them as equivalent to no custom queries being configured in the respective case.

[mbg]

Super minor: instead of the example at the end, we could mention the DefaultSetupConfig type here (from db-config.ts) to look at for what assumptions we do make about the configuration provided by Default Setup. Since that affects the behaviour of the Action, we are more likely to update it if things change than the example in this comment.

[mbg]

matchesDefaultSetupConfigSchema implements similar logic to mergeDefaultSetupAndUserConfigs with some minor differences (mergeDefaultSetupAndUserConfigs expects to already be given a UserConfig object and doesn't parse the YAML itself; both handle the outcomes of checkSchema differently).

Two concerns with this:

1. We may end up parsing and validating the config twice. That seems a bit unnecessary.
2. If we change one for any reason, we should also change the other.

Alongside the similar points for getOtherLanguagePacksReason, I am starting to think that maybe we should refactor this more so that we perform the input processing once before getOtherLanguagePacksReason and initConfig are called, and then pass the results of the input processing to both. I appreciate that it's more work to do that than we'd like for this though, and I haven't checked if any of the relevant input processing in initConfig has a dependency on the CLI.

Could we at least modify the flow so that the config input is parsed as YAML earlier and the resulting object can be used here as well as in mergeDefaultSetupAndUserConfigs?

[mbg]

If we are keeping the YAML processing here, I think it would be good to add an inline comment here before the if (error instanceof ...) check to explain why we are happy to treat a YAMLException as indicative that the configuration wasn't provided by Default Setup. (Maybe also add a logger.debug call to log that case.)