CodeQL is widely used to identify security issues in source code as part of a development and CI workflow. For teams running CodeQL through GitHub Actions or the CodeQL CLI, changes to how the CLI is packaged can affect installation, automation, and maintenance.
One important change is the move away from the traditional all-platform CodeQL CLI bundle toward platform-specific bundles.
For teams that download or install CodeQL directly, this means the way the CLI is selected and configured in CI may need to change.
The important part is not simply replacing one download URL with another. Teams should understand which operating systems their pipelines use, how CodeQL is installed, and whether their automation assumes that one package works everywhere.
What Is CodeQL?
CodeQL is a static analysis technology used to find security vulnerabilities and other coding problems by analyzing source code.
A simplified workflow looks like this:
Source Code
|
v
CodeQL Analysis
|
v
Queries
|
v
Findings
|
v
Security ResultsInstead of looking only for known strings or patterns, CodeQL represents code in a form that can be queried.
A CI workflow can therefore include CodeQL alongside normal build and test steps:
Pull Request
|
+--> Build
|
+--> Unit Tests
|
+--> CodeQL Analysis
|
+--> Dependency Checks
|
v
ReviewWhat Is the All-Platform Bundle?
Historically, CodeQL CLI distribution could be obtained in a bundle designed to support multiple platforms.
Conceptually, that means one package could contain components needed for different environments:
CodeQL Bundle
|
+-- Linux
+-- Windows
+-- macOS
+-- CodeQL CLI
+-- Supporting ComponentsThis was convenient for environments where the same bundle needed to work across different operating systems.
The platform-specific approach changes that model.
Instead of treating one package as a universal installation, the CI environment should select the package appropriate for the operating system and architecture being used.
Why Is CodeQL Moving Toward Platform-Specific Bundles?
A multi-platform package can include components that a particular machine does not need.
For example:
Linux Runner
|
v
All-Platform Bundle
|
+--> Linux Components
+--> Windows Components
+--> macOS ComponentsThe runner may only require one platform's components.
A platform-specific bundle instead looks more like:
Linux Runner
|
v
Linux CodeQL BundleThis provides a clearer relationship between the runtime environment and the software package being installed.
The exact packaging and transition details should be checked against the current CodeQL documentation before modifying production workflows.
What Changes for CI?
The main impact is on pipelines that install or manage the CodeQL CLI themselves.
A workflow might currently depend on assumptions such as:
Download CodeQL
|
v
One Bundle
|
v
Any Supported RunnerAfter the transition, the workflow may need to identify the platform first:
CI Runner
|
+--> Linux -> Linux Bundle
|
+--> Windows -> Windows Bundle
|
+--> macOS -> macOS BundleThe actual implementation depends on how CodeQL is installed in the pipeline.
GitHub-Managed CodeQL Workflows
Teams using GitHub's managed CodeQL setup may have less installation work to perform because GitHub Actions can manage much of the CodeQL tooling.
A typical workflow might look like:
name: CodeQL
on:
push:
pull_request:
jobs:
analyze:
runs-on: ubuntu-latest
permissions:
security-events: write
packages: read
actions: read
contents: read
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Initialize CodeQL
uses: github/codeql-action/init@v3
with:
languages: csharp
- name: Build
run: dotnet build --no-restore
- name: Analyze
uses: github/codeql-action/analyze@v3The important point is that teams should distinguish between:
GitHub-managed CodeQL Actions
Direct CodeQL CLI installation
Custom CI scripts
Self-hosted runner installations
The migration impact can be different for each model.
Direct CodeQL CLI Installations Need More Attention
Some organizations download the CLI themselves.
For example, a custom pipeline may contain logic similar to:
curl -L "$CODEQL_URL" -o codeql.zip
unzip codeql.zip
./codeql/codeql versionThe exact commands vary by organization.
If the URL or package selection assumes an all-platform bundle, that logic should be reviewed.
Look for:
CODEQL_URL
CODEQL_VERSION
codeql.zip
codeql-bundle
download scripts
installation scriptsThese are common places where platform assumptions may exist.
Self-Hosted Runners Are Especially Important
Self-hosted runners deserve careful review because organizations control their operating systems and installation processes.
A company might have:
Self-Hosted Runners
|
+-- Windows
+-- Linux
+-- macOSIf the same installation script is used for all three, it may need to change to account for platform-specific CodeQL packages.
A simple architecture is:
Runner
|
v
Detect OS / Architecture
|
v
Select CodeQL Package
|
v
Install
|
v
Verify VersionThe package-selection logic should be tested separately on each runner type.
Check CPU Architecture Too
Operating system alone may not be enough.
A runner can also differ by CPU architecture.
For example:
Operating System
+
CPU Architecture
|
v
Correct CodeQL PackageTherefore, installation scripts should not blindly assume that every Linux machine or every Windows machine uses the same architecture.
This is particularly important when organizations use a mixture of hosted and self-hosted infrastructure.
Search Your CI Configuration First
Before changing anything, search the repository and CI infrastructure for CodeQL installation references.
For example:
grep -Rni "codeql" .github/On Windows PowerShell, an equivalent search can be performed with:
Get-ChildItem -Recurse .github | Select-String "codeql"You can also search for:
codeql-action
codeql-bundle
codeql-cli
CODEQL_VERSION
CODEQL_URLThe exact search command should match your operating system and repository structure.
Review Container Images
Some organizations run CodeQL inside custom containers.
For example:
FROM ubuntu:latest
COPY codeql /opt/codeql
ENV PATH="/opt/codeql:${PATH}"If the container contains a manually installed CodeQL bundle, inspect how that bundle was obtained.
A container image can hide the dependency from the repository's workflow files.
The real dependency may be in:
Dockerfile
Container build script
Base image
Installation script
CI image registryCheck Build Scripts Too
The CodeQL installation may not be defined directly in GitHub Actions.
It could exist in:
scripts/install-security-tools.sh
build.ps1
Makefile
Dockerfile
bootstrap.shFor example:
#!/usr/bin/env bash
CODEQL_VERSION="X.Y.Z"
# Download and install CodeQL
Join the conversation! Your thoughts help the community grow.