CodeQL Action Architecture and Version Migration

The CodeQL Action represents the primary integration mechanism for GitHub's semantic code analysis engine, designed to perform deep static analysis of a repository's source code to identify security vulnerabilities. By leveraging the CodeQL engine, the action converts source code into a searchable database, which is then queried using a set of extensible queries developed by the GitHub Security Lab and the broader community. The operational flow of the action involves the analysis of the codebase, the identification of flaws, and the subsequent automatic upload of these results to GitHub. This integration allows vulnerabilities to be surfaced directly within pull requests and the dedicated security tab of a repository, facilitating a "shift-left" security approach where flaws are identified and mitigated during the development lifecycle rather than after deployment.

The action operates under a dual-licensing model. The CodeQL Action itself is released under the MIT License, ensuring flexibility for its use. However, the underlying CodeQL CLI, which powers the actual analysis, is governed by the GitHub CodeQL Terms and Conditions. This specific licensing structure dictates that the action is available for use on all open-source projects hosted on GitHub, as well as on private repositories, provided those repositories are owned by an organization that has GitHub Advanced Security (GHAS) enabled.

Core Functional Components and Actions

The CodeQL Action repository is not a single monolithic entity but a collection of several actions tailored for different stages of the security analysis pipeline. These components allow users to either use a streamlined, automated process or a highly granular, manual configuration.

Primary Analysis Actions

The workflow for performing a semantic analysis typically revolves around two main actions:

• init: This action is responsible for setting up the CodeQL environment for analysis. It prepares the workspace and initializes the database required for the semantic engine to operate.
• analyze: This action serves as the finalization step. It completes the CodeQL database, executes the specified queries against the source code, and uploads the resulting findings to the GitHub Code Scanning interface.

Third-Party Integration and Support Actions

Beyond the core analysis loop, the system provides mechanisms for integrating external security tools and experimental environment handling:

• upload-sarif: This action enables the upload of Static Analysis Results Interchange Format (SARIF) files to GitHub Code Scanning. This is critical for teams using third-party SAST tools that produce SARIF output. It is important to note that if the analyze action is already being used, there is no operational requirement to use upload-sarif, as analyze handles the upload process natively.
• autobuild: This component attempts to automatically build the code, which is a prerequisite for analyzing compiled languages. While it exists as a standalone action, it is generally recommended to use the build-mode: autobuild input within the init action instead.
• resolve-environment: An experimental tool designed to infer a build environment that is suitable for automatic builds, reducing the manual overhead of environment configuration.
• setup-codeql: An experimental action that installs the CodeQL CLI without initializing a database, providing a lightweight setup for custom scripting.
• start-proxy: An experimental internal action used to start an HTTP proxy server; it is intended for internal use and is subject to change without notice.

Build Mode Configurations

The efficiency and success of a CodeQL analysis depend heavily on the chosen build mode. The action supports three distinct modes to accommodate different language types and project complexities:

• none: The database is created without building the source code. This is the default and preferred mode for interpreted languages and certain compiled languages that do not require a build step for analysis.
• autobuild: The system attempts to automatically determine the build requirements and execute the build to create the database. This is available for all compiled languages.
• manual: This mode allows the user to specify a custom build command. This is essential for complex projects with non-standard build systems where autobuild fails to correctly identify the compilation process.

Versioning Evolution and Runtime Transitions

The CodeQL Action has undergone significant transitions in its runtime environment and versioning to keep pace with Node.js advancements and GitHub Enterprise Server (GHES) releases.

The v2 to v3 Transition

CodeQL Action v3 was released on December 13, 2023, transitioning the runtime to Node.js 20. This move rendered CodeQL Action v2 obsolete. By January 2024, it was announced that v2 would be retired in tandem with GHES 3.11. Since that retirement period has elapsed, v2 is now discontinued. While GitHub does not proactively delete discontinued versions unless a security vulnerability is found, workflows relying on v2 are susceptible to breakage and lack access to new analysis capabilities.

The v3 to v4 Transition

On October 7, 2025, CodeQL Action v4 was released, moving the runtime to Node.js 24. This represents the current latest version. The deprecation of v3 is tied to the lifecycle of GHES 3.19, with a scheduled deprecation date in December 2026.

The impact of this transition varies based on the configuration method used by the repository:

• Default Setup Users: Those using the default configuration for code scanning are automatically migrated to v4 by GitHub, requiring no manual intervention.
• Advanced Setup Users: Those utilizing custom workflow files must manually update their YAML configurations to reference v4.

Platform Compatibility and Requirements

The ability to run specific versions of the CodeQL Action is strictly tied to the hosting platform and the version of GitHub Enterprise Server.

Platform-Specific Update Requirements

Users on the following platforms must update their workflow files to refer to v4:

• GitHub.com: This includes all open-source repositories, as well as users of GitHub Teams and GitHub Enterprise Cloud.
• GitHub Enterprise Server (GHES): Versions 3.20 and newer. Notably, GHES 3.20 ships with v4 included by default.

GHES Version Constraints

The transition to v4 is not uniform across all GHES versions due to Node.js runtime support:

• GHES 3.19: This version supports Node.js 24 Actions, but it does not ship with CodeQL Action v4 pre-installed. Users on 3.19 must request their system administrator to enable GitHub Connect to download v4 before updating their workflow files.
• GHES 3.18 and Older: These versions do not support the Node.js 24 runtime. Consequently, they are fundamentally unable to run CodeQL Action v4.

Version Mapping Table

The following table outlines the minimum required versions of the Action and Bundle relative to the GHES environment:

Advanced Configuration and Security Permissions

For users implementing an advanced setup, precise configuration of permissions and version tagging is mandatory to ensure stability and security.

Required Workflow Permissions

All advanced setup code scanning workflows must be granted specific permissions to interact with the GitHub API and security features:

• security-events: write: This permission is mandatory for all advanced setups to allow the action to upload analysis results.
• contents: read: This permission is specifically required for workflows operating within private repositories to allow the action to access the source code.

Version Tagging Strategy

GitHub recommends a specific strategy for referencing the action in YAML files to avoid manual updates:

• Major Version Tagging: Users should reference the action using a major version tag, such as v4. This ensures the workflow automatically inherits the latest releases within that major version, including bug fixes, new features, and updated CLI versions.
• Specific Pinning: If a user chooses to pin the action to a specific commit SHA or a patch version tag, they must implement a mechanism (such as Dependabot) to keep the version updated, otherwise, they risk missing critical security updates.

CodeQL Library for GitHub Actions

Beyond the execution of the action, CodeQL provides a specialized library designed to analyze the GitHub Actions workflows themselves. This allows security researchers to find vulnerabilities within the YAML files and metadata of actions.

Object-Oriented Analysis of YAML

The CodeQL library for GitHub Actions provides a set of classes that represent the data from a CodeQL database in an object-oriented form. This enables the use of predicates and abstractions to perform complex analysis on workflow structures.

• Implementation: The library is implemented as a series of modules with the .qll extension.
• Core Import: The primary entry point for this library is the actions.qll module. By adding the following statement to a query:

ql import actions

Analysts gain access to the complete library, including the Abstract Syntax Tree (AST) library. This allows for the precise location of program elements and the matching of syntactic elements within the YAML source code, which is essential for identifying dangerous patterns or incorrect values in workflow definitions.

Technical Conclusion and Analysis

The evolution of the CodeQL Action from v2 through v4 reflects a broader trend in the GitHub ecosystem toward faster runtime updates and tighter integration with the Enterprise Server lifecycle. The shift to Node.js 24 in v4 is not merely a version bump but a requirement for modern execution environments, creating a hard compatibility wall for GHES versions 3.18 and older.

For the end-user, the distinction between "Default Setup" and "Advanced Setup" is the most critical operational pivot. Default setup provides a seamless, managed experience where GitHub handles the version migration. In contrast, Advanced Setup grants the user total control over the analysis pipeline—allowing for manual build commands and the integration of third-party SARIF data—but shifts the burden of maintenance onto the developer. Failure to update workflow files from v3 to v4 in an advanced setup will eventually lead to a failure state as v3 reaches its deprecation limit in December 2026.

The inclusion of the actions.qll library transforms CodeQL from a tool that simply scans code into a tool that can audit the very infrastructure (GitHub Actions) used to run the scans. This recursive capability allows organizations to ensure that their CI/CD pipelines are not introducing security regressions. The requirement for security-events: write permissions underscores the sensitive nature of this integration, as the action essentially writes security telemetry directly into the repository's metadata.

Sources

1. GitHub CodeQL Action Repository
2. Upcoming Deprecation of CodeQL Action v3
3. CodeQL Library for Actions Documentation
4. Code Scanning CodeQL Action v2 Deprecation