Security in software development has evolved dramatically, yet it’s still one of the easiest things to postpone. Everyone knows it should start early — vulnerabilities are cheaper and simpler to fix when caught before deployment, but deadlines and complexity often push it to the sidelines.

That’s where Static Application Security Testing (SAST) tools like CodeQL come in.

If you’ve used CodeQL, you already know how powerful it is. Instead of relying on predefined rules or pattern matching, it treats your code like data, allowing deep semantic analysis that finds subtle, logic-based vulnerabilities other scanners miss — and it does so with impressive precision, minimizing false positives.

If this is your first contact with CodeQL, it’s worth checking out this great introduction before diving in.

However, while CodeQL’s power is undeniable, integrating it smoothly across large organizations, monorepos, or custom CI/CD pipelines can be challenging.

Here are some of the issues teams typically encounter:

• Multiple programming languages and build systems in a single repository
• The need to scan only what actually changed in a pull request
• Running CodeQL outside of GitHub Actions

We’ve been there ourselves. That’s why we built CodeQL Wrapper, an open-source tool that simplifies running CodeQL in any environment, no matter how complex your repo or CI system might be.

This post explains why we built it, what it does in practice, and how to use it to simplify your CodeQL workflows without a deep technical dive.

What Is CodeQL Wrapper?

CodeQL Wrapper is a universal Python CLI that abstracts away much of the setup pain and provides a consistent way to run CodeQL across projects.

It allows you to run CodeQL anywhere — locally or in CI systems like GitHub Actions, Jenkins, Azure Pipelines, CircleCI, or Harness while ensuring consistent behavior across environments.

It automatically fetches and installs the correct version of the CodeQL CLI, meaning your local runs and CI analyses always stay in sync. And even if your pipelines don’t run on GitHub, CodeQL Wrapper can still send results back to GitHub Advanced Security in SARIF format for centralized visibility.

Beyond simplifying setup, CodeQL Wrapper helps teams maintain consistent configuration using a flexible .codeql.json file. This lets you define build modes, custom queries, and paths once — then apply them consistently across projects.

But where the wrapper really shines is in its ability to handle monorepos, tackling two of the biggest pain points: language detection and performance.

Automatic Language Detection

Many modern projects mix languages. A Python API here, a JavaScript frontend there, maybe a bit of Go for background services.

CodeQL’s default GitHub Action setup requires manually specifying which language to analyze. That’s fine for small projects, but a maintenance nightmare for monorepos.

CodeQL Wrapper removes this burden entirely. It automatically detects languages present in your codebase and configures the analysis for you.

This automation ensures nothing slips through the cracks (no forgotten languages, no partial scans) and keeps your configuration simple and future-proof.

Smarter Performance Through Parallelization and Change Detection

Running CodeQL can be time-consuming, especially in large repositories. CodeQL Wrapper optimizes this in two complementary ways: it runs analyses in parallel and skips unchanged code altogether.

The parallelization happens on two levels:

• Across projects – In the context of CodeQL Wrapper, a project refers to a distinct subdirectory within a repository that can be analyzed independently. Each project gets its own CodeQL database, allowing multiple components to be analyzed simultaneously.
• Within each project – If a project contains multiple languages (Python, JavaScript, Go, etc) CodeQL Wrapper can run analysis for each language concurrently instead of processing them sequentially.

The tool intelligently adapts to your system’s hardware using all available CPU cores without exhausting memory. Though you can manually tune the settings if needed.

And because avoiding unnecessary work is even better than parallelizing it, CodeQL Wrapper includes a change detection algorithm that analyzes only the code that has actually changed since the last scan.

It uses Git to identify modified files and determines which projects those files belong to. If no relevant files have changed, the tool automatically skips redundant analysis steps, avoiding unnecessary database creation and query execution, cutting analysis time from hours to minutes on large monorepos.

At a high level, the wrapper determines a base commit (from CI variables or an explicit flag), fetches any missing refs, computes the diff, and maps changed files to projects. Only those projects proceed to database creation and query execution. The logic is platform‑agnostic, so the same behavior applies whether you run in GitHub Actions, Azure Pipelines, CircleCI, Harness, or locally.

Installing and Running CodeQL Wrapper

We designed CodeQL Wrapper so that the first run feels frictionless and the hundredth run still feels predictable. Installation is a single step, and from there you can either prepare the environment or jump straight into analysis.

pip install codeql-wrapper

This will install the tool in your environment. Once installed, you’ll have access to two commands:

• install – Installs CodeQL CLI and query packs (you can pin a specific version if needed).
• analyze – Runs CodeQL analysis on your project(s), with automatic project detection and parallelized scans. If you only need the CodeQL CLI (and don’t want to run a scan yet), just run:

codeql-wrapper install

This fetches the CodeQL CLI and query packs, and you can pin versions with --version to keep results reproducible. When you’re ready to analyze, analyze takes over the heavy lifting: it confirms CodeQL is installed, detects languages and projects, creates databases, and runs queries in parallel to suit your hardware.

Basic Usage

Most teams start by pointing the wrapper at the repository root. That’s intentional: you shouldn’t need to hand‑craft language lists or database steps to get useful results.

codeql-wrapper analyze ./repo

Behind the scenes, the wrapper inspects your codebase, identifies the languages that matter, and builds one database per language. If your repo is a monorepo, it scopes the work to projects it finds, running them concurrently. The default configuration leans on safe, broadly applicable queries and build-mode: none, which makes first‑time adoption smooth even without bespoke build instructions.

As codebases grow, consistency matters more than one‑off tweaks. The wrapper’s model — automatic detection plus ergonomic overrides — offers practical advantages: it adapts to monorepos with different needs per project, keeps query policies uniform across CI providers, and makes exceptions explicit without touching pipeline YAML.

Why CI Integration is Easier

Rather than generic promises, here’s what changes in day‑to‑day pipelines:

• One command surface: install and analyze. The wrapper handles language detection, database creation, and query execution, so pipelines don’t need fragile per‑language steps.
• Version pinning: install --version locks the CodeQL CLI version, avoiding environment drift between developer machines and CI runners.
• Monorepo awareness: Independent projects (subdirectories) are processed in parallel, reducing custom CI logic.
• Change detection: Git diffs are mapped to affected projects; unchanged ones are skipped, cutting incremental scan time.
• Consistent outputs: SARIF is generated uniformly, so reporting stays the same regardless of CI platform.

Usage Examples

Local runs establish trust, but enterprise adoption hinges on repeatable automation. To make that transition easy, we ship codeql-wrapper-pipelines, a companion repository with templates for common CI/CD providers. These examples handle the practicalities — auth, artifacts, and reporting — while keeping the interface consistent. You get one way of invoking the wrapper, regardless of whether your pipelines live in GitHub Actions, Azure Pipelines, CircleCI, Harness, or elsewhere.

Why We Built It

Our work with global enterprises adopting GitHub Advanced Security led us to build both codeql-wrapper and codeql-wrapper-pipelines. The tools distill hard‑won lessons from monorepo rollouts: minimize manual configuration, keep behavior consistent across environments, and make smart defaults easy to override.

The goal isn’t just faster scans; it’s a smoother path to reliable, organization‑wide CodeQL usage. If you’re strengthening DevSecOps without piling on process, we think this approach strikes the right balance. Give the wrapper a try, explore the pipelines, and reach out on the repositories if you want help shaping them to your environment.