Support CodeQL versions, ranges, release offsets, and nightly transitions

[felickz]

What this changes

The tools input for github/codeql-action/init and github/codeql-action/setup-codeql can now select CodeQL using a version, a SemVer range, a release offset, or an automatic nightly transition.

The Action resolves the requested version and downloads the correct bundle for the runner's operating system and architecture.

Select an exact version

- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript
    tools: 2.20.1

An optional v prefix is also accepted:

tools: v2.20.1

This replaces the need to provide a full platform-specific bundle URL.

Select a SemVer range

The input supports npm-style SemVer ranges and selects the newest stable CodeQL release satisfying the range:

tools: 2.20.x
tools: 2.x
tools: ~2.20.0
tools: ^2.20.0
tools: ">=2.20.0 <2.21.0"

If no release satisfies the range, the error reports the available stable CodeQL version range.

Stay behind the latest release

Use latest-N to select a stable release by its position behind the newest stable release:

tools: latest-0  # Newest stable release
tools: latest-1  # One stable release behind
tools: latest-2  # Two stable releases behind

If the offset is outside the available release history, the error reports how many stable releases are available.

Include prereleases

Use latest-prerelease to select the newest semantic CodeQL bundle while allowing GitHub releases marked as prereleases:

tools: latest-prerelease

Stable releases remain eligible, so the newest eligible version wins. Draft and date-based bundle releases are ignored. Existing latest-N and SemVer range inputs remain stable-only.

Use nightly until a release is available

Use nightly-until-<version> to test a feature expected in a future CodeQL release:

tools: nightly-until-2.26.3

The Action uses the latest nightly until a published CodeQL release at or above the threshold exists. GitHub prereleases are eligible. It then switches to the newest eligible published release.

Use nightly until the normal default is ready

Use nightly-until-default-<version> when you want to return to the Action's normal default selection only after the CodeQL CLI that would actually be selected contains the required feature:

tools: nightly-until-default-2.26.3

The Action first resolves its normal default source and continues using nightly while that selected CLI is below the threshold. Once the CLI that would actually be used is at or above the threshold, normal default selection resumes.

This form does not list CodeQL releases or switch merely because a release was published.

Existing inputs remain supported

Existing tools values—including URLs, local paths, latest, nightly, linked, and toolcache—continue to work as before.

Risk assessment

Risk level: Low risk

The new behavior is opt-in through previously unsupported tools input values. Existing inputs and workflows remain unchanged. The implementation has unit coverage and was exercised in a dedicated cross-platform test workflow.

Which use cases does this change impact?

Workflow types:

• Advanced setup - Impacts users who explicitly configure the tools input.
• Managed - May impact managed workflows when github-codeql-tools supplies one of the new values.

Products:

• Code Scanning - Impacts analyses using the new tools values.
• Code Quality - Impacts analyses using the new tools values.
• Other first-party - May impact first-party analyses using the new tools values.

Environments:

• Dotcom - Supports GitHub.com and GitHub Enterprise Cloud with Data Residency.
• GHES - Exact/default downloads retain existing instance-aware behavior. Dynamic release discovery uses the canonical public GitHub.com release inventory without forwarding enterprise credentials.

How did/will you validate this change?

• Test repository - Tested through a dedicated matrix workflow using Python analysis across Ubuntu, Windows, and macOS.
• Unit tests - Added focused coverage for exact versions, SemVer ranges, release offsets, prereleases, nightly transitions, malformed inputs, release filtering, overlay-aware defaults, and GHES toolcache overrides.
• End-to-end tests - PR checks completed successfully except for unavailable macOS xlarge runners, which received no runner and executed no steps.
• Other - The matrix exercised 37 input forms across three operating systems. Expected unsupported inputs produced clear errors, while supported inputs resolved the expected versions and platform-specific assets. (see run)

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

• Rollback - The change can be disabled by rolling back the release or releasing a new version with a fix.
• Other - The behavior is opt-in. Users can immediately return to existing supported inputs such as an exact bundle URL, linked, latest, nightly, toolcache, or an omitted tools value.

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

• Telemetry - Existing Action telemetry records the tools source and selected version.
• Other - Version resolution, download, compatibility, and malformed-input failures produce explicit Action errors describing the requested input and available release range.

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.
• Add a changelog entry for this change.
• Confirm the readme and docs have been updated if necessary.