# Add ccache to a CMake Project's GitHub Actions Builds

Yes. An agent wires ccache into your CMake CI matrix with a cache key per compiler and standard, shows the hit rate from a warm build, and opens a pull request.

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

## What the agent does

The agent clones the repository into its own cloud sandbox and reads the build matrix before touching it. In a C++ library like fmtlib/fmt, `.github/workflows/linux.yml` runs a matrix of `g++-4.9`, `g++-11`, `clang++-3.6` and `clang++-11` in Debug and Release at C++11, with `include` entries that add `g++-13`, `g++-14` with sanitizers, `g++-16` with `-freflection`, `clang++-14` and `clang++-20` at standards up to 26, some on `ubuntu-24.04` and some with the Ninja generator. Every job configures with `-DFMT_DOC=OFF -DFMT_PEDANTIC=ON -DFMT_WERROR=ON`, builds with `cmake --build . --parallel`, and runs `ctest`. `macos.yml` builds Debug and Release at C++11, 17, 20 and 23 on `macos-15`, and `windows.yml` covers MSVC `v142` and `v143` plus two MSYS2 jobs. The Linux workflow already caches something: `actions/cache` keeps `~/apt-cache` for the `.deb` files of old compilers, keyed on the OS, compiler and install line. Nothing caches object files, and `CMakeLists.txt` never mentions `CMAKE_CXX_COMPILER_LAUNCHER`.

The one place ccache appears is `test/fuzzing/build.sh`, which sets `CXX="ccache g++"` for a local fuzzer build, so the project is not opposed to it. The agent adds it to CI through the launcher variable rather than by wrapping the compiler, because the `linux.yml` matrix selects `CXX` and derives `CC` in a step of its own and the launcher leaves that alone. Each Linux and macOS job gets a step that installs `ccache` from `apt` or `brew`, a step that restores a cache directory keyed on the runner OS, `matrix.cxx`, `matrix.std`, `matrix.build_type` and the hash of `include/`, `src/` and `test/`, with a restore key that drops the hash so a changed source tree starts warm, and `-DCMAKE_CXX_COMPILER_LAUNCHER=ccache` on the configure line. A final step runs `ccache --show-stats` with `if: always()` so a miss is visible in the log.

Some jobs cannot use it and the agent says which. The `g++-4.9` and `clang++-3.6` jobs run compilers installed from downloaded `.deb` files that ccache handles, but the two sanitizer jobs pass `-fsanitize` through `CXXFLAGS`, which is part of ccache's hash and so simply caches separately. The MSVC jobs use the Visual Studio generator, where the launcher variable has no effect, so `windows.yml` is left as it is and the MSYS2 jobs, which use Ninja, get ccache from `pacboy`. The agent sets `CCACHE_COMPILERCHECK=content` so a compiler upgraded in place on the runner image invalidates its entries, and `CCACHE_MAXSIZE` to a value the repository's object output fits in, which it measures.

The proof is two builds in the sandbox with the same configure line as the `g++-11` Debug C++17 job: `cmake -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_STANDARD=17 -DFMT_DOC=OFF -DFMT_PEDANTIC=ON -DFMT_WERROR=ON`, a cold build and then a clean rebuild, with `ccache --show-stats` after each and `ctest` after the second to show the cached objects link into a passing test run. Those three outputs, the hit count and the cache size, go into the pull request. The agent changes no compiler flag and no CMake option, and `FMT_WERROR` stays on so a warning ccache might mask by replaying an old object is still a failure the first time.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add ccache to this CMake project's GitHub Actions. Read CMakeLists.txt and every workflow under .github/workflows first. For each Linux and macOS job, install ccache, restore a cache keyed on the runner OS, compiler, C++ standard and build type with a source hash and a fallback key, pass -DCMAKE_CXX_COMPILER_LAUNCHER=ccache at configure, and print ccache statistics at the end even on failure. Leave jobs whose generator ignores the launcher unchanged and say which. Change no compiler flag or CMake option. In your sandbox, run one job's exact configure line cold and then again from a clean build directory, and put both ccache statistics outputs and the ctest result in the pull request. Open a pull request.",
  "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 on its own branch that changes `.github/workflows/linux.yml`, `.github/workflows/macos.yml` and the MSYS2 jobs in `.github/workflows/windows.yml`, and nothing under `include/`, `src/`, `test/` or in `CMakeLists.txt`. The description lists each matrix job with the cache key it will use, the jobs left alone and why, and the two `ccache --show-stats` outputs from the sandbox: the cold run with every compilation a miss, and the rebuild with the hits, followed by the `ctest` summary from the rebuilt tree.

The run's record keeps the installation, both builds and the statistics commands with their full output, so a reviewer can confirm the hit rate was measured on this project's sources with this project's flags, not assumed from a template.

Before merging, a reviewer checks that the cache key includes everything that changes object code here, which is why `matrix.std`, `matrix.build_type` and `CXXFLAGS` are all in it, decides whether the `actions/cache` version pinned by hash in `linux.yml` should be the one the new steps use too, and watches the first few runs on the pull request itself, since the workflow runs there and the statistics step shows the cache filling.

## Run it on every repository

Start this once from a terminal with `POST /o/{org}/sessions`, this body and the repository in `resources`. The run carries on in its sandbox after the window closes, and a follow-up through `POST /o/{org}/sessions/{id}/messages` can add the Windows MSVC jobs with `sccache`, or change the key scheme, without a second cold start. After the merge, the workflows do the ongoing work on every push and pull request.

A team with several CMake repositories starts one run per repository from a script with the same body, each with its own `request_id`, a UUID, so a retried start returns the run it already began; the key's `webhook_url` receives `run.completed` for each with a `session_url` from which the handler reads the pull request link.

## Why run it on Rush?

A compiler cache is worth exactly its hit rate, and the hit rate depends on getting the key right for this matrix: a key without the C++ standard hands a C++11 object to a C++20 job and the build fails late, a key with too much in it never hits. The agent reads the matrix as written, builds the key from the variables that actually vary, and measures a warm rebuild in its sandbox before anyone waits on CI to find out.

Measuring that on a laptop means installing four compilers you do not otherwise use. The sandbox is disposable, the two builds and their statistics stay in the run's record, and several repositories can be done in parallel, each with its own pull request and its own measured numbers.

## Frequently asked questions

### Will ccache ever make a build wrong?

It hashes the preprocessed source, the compiler and the flags, so a changed header or flag is a miss. The agent sets `CCACHE_COMPILERCHECK=content` so a compiler replaced under the same path on the runner image invalidates its entries as well, and `FMT_WERROR` and `FMT_PEDANTIC` are left on so warnings still fail the build the first time they appear.

### Why are the MSVC jobs left out?

Those jobs use the Visual Studio generator through `cmake -A`, and `CMAKE_CXX_COMPILER_LAUNCHER` only applies to Makefile and Ninja generators. The MSYS2 jobs do use Ninja and get ccache. MSVC caching with `sccache` is a different change and can be asked for in a follow-up.

### Does this change any flags or what the tests build?

No. The configure lines keep every `-D` option they had, and the only addition is the launcher variable. The sandbox runs `ctest` on the rebuilt tree to show the cached objects link and pass as before.

### How is the cache kept from growing without bound?

`CCACHE_MAXSIZE` is set from the size the agent measured for a full build of this project, and the cache action's key includes the source hash, so a stale entry ages out as GitHub evicts unused caches. The statistics step prints the size on every run.

## More CMake jobs

- [Add a clang-format Check to CI for a CMake Project](https://getrush.ai/run/add-clang-format-check/cmake/)
- [Add clang-tidy to a CMake C++ Project and Its CI](https://getrush.ai/run/add-clang-tidy/cmake/)
- [Add CMakePresets.json to a CMake Project](https://getrush.ai/run/add-cmake-presets/cmake/)

## More jobs like this: Hand off a long task

- [Add Changesets to a TypeScript Library](https://getrush.ai/run/add-changesets/typescript-library/)
- [Add Checkov Scanning to a Terraform Module's CI](https://getrush.ai/run/add-checkov-to-ci/terraform/)
- [Add Checkstyle to a Maven Build](https://getrush.ai/run/add-checkstyle/maven/)

## 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/)
