# Add CodeQL Scanning to a CMake C++ Project

Yes. An agent adds a CodeQL workflow that builds the project with CMake so the analysis sees compiled code, checks it with the CodeQL CLI first, in a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-codeql-scanning/cmake/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the project builds before it writes a workflow. In a library like jarro2783/cxxopts, `CMakeLists.txt` declares `cmake_minimum_required(VERSION 3.5...3.19)`, reads the version with `cxxopts_getversion` from `cmake/cxxopts.cmake`, defines `cxxopts` as an `INTERFACE` library over the single header in `include/`, and switches `CXXOPTS_BUILD_EXAMPLES`, `CXXOPTS_BUILD_TESTS`, `CXXOPTS_ENABLE_INSTALL` and `CXXOPTS_ENABLE_WARNINGS` on when it is the top-level project. `test/CMakeLists.txt` builds `options_test` and `options_test_noregex` from `main.cpp` and `options.cpp` and registers them with `add_test`; `src/` holds `example.cpp`. Under `.github/workflows/`, `cmake.yml` runs a matrix of Ubuntu with three compilers, macOS and Windows through `cmake -S . -B build`, `cmake --build` and `ctest`; `build.yml` does a plain `make` build; `meson.yml` covers the Meson build; `cifuzz.yml` runs OSS-Fuzz on pull requests. There is no `codeql.yml` and no `dependabot.yml`.

It writes a workflow that compiles, because a header-only library has nothing for CodeQL to trace unless something includes it. `.github/workflows/codeql.yml` runs on push and pull request to `master` and on a weekly schedule, with `permissions` limited to `contents: read` and `security-events: write`. It calls `github/codeql-action/init` with the C and C++ language and a manual build mode, then configures with `-DCXXOPTS_BUILD_EXAMPLES=ON -DCXXOPTS_BUILD_TESTS=ON` and runs `cmake --build build`, so `example.cpp` and the two test binaries pull `cxxopts.hpp` through the compiler and every template in the header is analyzed as instantiated, and finishes with `github/codeql-action/analyze`. The step names mirror `cmake.yml` so the two workflows read alike, and the action versions match the `actions/checkout@v4` the existing files pin.

It also settles the choices a reviewer would ask about. The query suite is left at the default rather than `security-extended`, with a comment on the line to change, since the fuzzing workflow already covers crash-style findings. The build runs on `ubuntu-latest` with the default compiler only, because CodeQL needs one compilation, not the full matrix. Pull requests from forks get `security-events: write` refused by GitHub, so the job is allowed to upload only on pushes and same-repository pull requests, and that condition is written on the step.

Then it runs the same analysis in the sandbox before asking CI to. The agent downloads the CodeQL CLI bundle, creates a database with `codeql database create --language=cpp --command` wrapping the exact `cmake --build` line from the workflow, confirms the database reports the compiled source files, and runs `codeql database analyze` with the default C++ suite to SARIF. It reads the findings count and the first few results, lints the workflow with `actionlint`, and opens the pull request with the local result quoted so the first CI run has a baseline to compare against.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add CodeQL scanning to this CMake C++ project. Read CMakeLists.txt, cmake/cxxopts.cmake, include/CMakeLists.txt, test/CMakeLists.txt, src/CMakeLists.txt and every file under .github/workflows first. Write .github/workflows/codeql.yml running on push and pull request to the default branch and on a weekly schedule, with permissions limited to contents read and security-events write. Use github/codeql-action init for C and C++ with a manual build, configure with the examples and tests options on so the header is compiled through them, build with cmake, then run analyze. Keep the default query suite with a comment on where to extend it, run on one Ubuntu job, and restrict the upload to pushes and same-repository pull requests. Match the checkout action version the existing workflows pin and name steps like cmake.yml. Before opening the pull request, download the CodeQL CLI, create a cpp database with the workflow's build command, confirm the compiled files are in it, run the default analysis and quote the result count in the description. Run actionlint on the workflow.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request adding `.github/workflows/codeql.yml`, and nothing else unless `actionlint` points at a line in the new file. The description explains why the job builds the examples and tests instead of relying on autobuild for a header-only library, names the schedule, the permissions and the fork condition, and quotes the local CodeQL run: the files the database compiled and the number of results the default suite produced.

The run's record keeps the `codeql database create` and `codeql database analyze` output and the `actionlint` result, so a reviewer can see the build command compiled `example.cpp` and the test sources rather than an empty database.

Before merging, a reviewer enables code scanning in the repository settings if it is not already on, merges, and opens the Security tab after the first run to confirm the same count the description quoted, then decides whether to switch the suite to `security-extended`.

## Run it on every C++ repository with CI but no static analysis

The setup is one `POST /o/{org}/sessions` with this body and the repository in `resources`, started from a terminal; the run continues in its sandbox after the window closes, and a follow-up through `POST /o/{org}/sessions/{id}/messages` can switch the suite or add a second language without a new run. A team with several C++ repositories sends one request per repository, each with its own UUID as `request_id`, so a rerun of the script returns the run it already started.

Give the API key a `webhook_url` and Rush POSTs `run.completed` or `run.failed` when a run's turn finishes, with `session_url` so your server can read the pull request link and the analysis output.

## Why run it on Rush?

A CodeQL workflow copied from a template looks finished and scans nothing: autobuild on a header-only project compiles no translation unit, so the database is empty and the Security tab stays green for the wrong reason. The agent builds the database in its own sandbox with the workflow's exact command and reads which files went in, so the pull request ships with evidence the analysis has something to analyze.

The CLI runs and their output stay with the run, so the pull request can quote the compiled file list and the result count, and the first CI run has a number to match rather than a hope.

## Frequently asked questions

### Why not use CodeQL's autobuild?

The library is a single header behind an `INTERFACE` target; autobuild would find nothing to compile and CodeQL would analyze nothing. Building the examples and tests with CMake compiles the header through real call sites, so templates are instantiated and the queries have code to trace.

### Will this slow down every pull request?

It adds one Ubuntu job alongside the existing CMake matrix, not a matrix of its own. The build is the same `cmake --build` the project already runs, plus the analysis time, and the weekly schedule catches query updates without waiting for a push.

### Does it find anything in a header-only parser?

The agent runs the default suite locally and quotes the count in the pull request, whatever it is. It does not change code to satisfy a query; findings are for the maintainers to triage in the Security tab.

### What about pull requests from forks?

GitHub refuses `security-events: write` to a fork's workflow run, so the upload step is conditioned on pushes and same-repository pull requests. Fork contributors still get the build and analysis; only the upload is skipped, and the condition says so in the file.

## More CMake jobs

- [Add Conan 2 Packaging to a CMake C++ Library](https://getrush.ai/run/add-conan-package/cmake/)
- [Add Test Coverage Reporting to a CMake Project's CI](https://getrush.ai/run/add-coverage-to-ci/cmake/)
- [Add Cppcheck to CI for a CMake Project](https://getrush.ai/run/add-cppcheck-to-ci/cmake/)

## The same job on other stacks

- [Add CodeQL Scanning to a Cobra CLI](https://getrush.ai/run/add-codeql-scanning/cobra/)
- [Add CodeQL Scanning to a Repository with GitHub Actions](https://getrush.ai/run/add-codeql-scanning/github-actions/)
- [Add CodeQL Scanning to a Go CLI](https://getrush.ai/run/add-codeql-scanning/go-cli/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
