skip to content

A GitHub-hosted CI pipeline rebuilds every vcpkg dependency on every run; why does that happen, and how do you configure vcpkg binary caching to stop it?

level: seniorimportance: should knowfreq 40%

answer

  1. the default cache lives on the runner
  2. fresh VM, empty archives folder
  3. VCPKG_BINARY_SOURCES with readwrite
  4. the removed x-gha provider

basics

~20 s

vcpkg's default binary cache is a local folder, such as ~/.cache/vcpkg/archives, and hosted runners start empty, so every package is built from source. Set VCPKG_BINARY_SOURCES to durable storage, such as clear;nuget,<feed>,readwrite, so packages are restored by ABI hash.

solid answer

~50 s

Binary caching is on by default, but with a `files` provider in a per-user folder: `$VCPKG_DEFAULT_BINARY_CACHE`, else `$XDG_CACHE_HOME/vcpkg/archives` or `$HOME/.cache/vcpkg/archives` (on Windows `%LOCALAPPDATA%\vcpkg\archives`). A GitHub-hosted runner is a fresh machine each run, so that folder is always empty and every port builds from source. The fix is a durable cache in `VCPKG_BINARY_SOURCES`, a semicolon-separated list read before any `--binarysource` options: start with `clear` to drop the default, then add a provider with `readwrite`, for example `nuget,<feed>,readwrite` for GitHub Packages, `files,<absolute path>,readwrite` on a directory your CI system persists, `http,<url-template>,readwrite`, or a cloud bucket provider. In vcpkg 2026.10.16 the old `x-gha` provider has been removed and only prints a warning. A restore happens only when the **ABI hash** matches: port files, triplet, compiler, features, dependencies and tool versions, so an updated runner image can still cause rebuilds.

code

bash · 10 lines
bash
# CI step on a Linux runner, before configuring the project
export VCPKG_BINARY_SOURCES="clear;nuget,https://nuget.pkg.github.com/<OWNER>/index.json,readwrite"
NUGET="$(./vcpkg/vcpkg fetch nuget | tail -n 1)"
mono "$NUGET" sources add \
  -source "https://nuget.pkg.github.com/<OWNER>/index.json" \
  -name GitHub -username "<OWNER>" -password "$GITHUB_TOKEN" \
  -storepasswordincleartext
mono "$NUGET" setapikey "$GITHUB_TOKEN" \
  -source "https://nuget.pkg.github.com/<OWNER>/index.json"
cmake --preset ci && cmake --build --preset ci

go deeper

for a junior

Recall that vcpkg can reuse built packages through binary caching and that VCPKG_BINARY_SOURCES configures where they are stored.

for a middle

Explain the default local cache, why ephemeral runners never benefit from it, and the source syntax with clear and read, write or readwrite.

for a senior

Show you can set up a durable provider, recognise the removed x-gha configuration in old pipelines, and explain cache misses through the ABI hash inputs.

for a principal

Decide who may write to the cache and how runner images are pinned, since both determine whether caching saves time or spreads bad binaries.

## Why the pipeline rebuilds everything vcpkg builds ports from source. **Binary caching** stores each built package as a zip archive keyed by an **ABI hash** and restores it the next time the same hash is needed. It is enabled by default with a `files` provider at the first valid location of: - `VCPKG_DEFAULT_BINARY_CACHE`; - on non-Windows hosts, `$XDG_CACHE_HOME/vcpkg/archives`, then `$HOME/.cache/vcpkg/archives`; - on Windows, `%LOCALAPPDATA%\vcpkg\archives`, then `%APPDATA%\vcpkg\archives`. On a developer laptop that works well. A GitHub-hosted runner, though, is a new virtual machine for every job; the archives folder starts empty and is thrown away afterwards. Every run therefore builds every dependency, which for a graph containing Boost, Qt or OpenSSL means tens of minutes per job, multiplied by each OS and triplet in the matrix. The vcpkg docs call this out: binary caching is especially effective where ephemeral agents start from a clean slate, **provided** the cache outlives the agent. ## Configuring a durable cache Sources are configured with the `VCPKG_BINARY_SOURCES` environment variable (`<source>;<source>;...`) and the `--binarysource=<source>` option; the environment is read first, then the command line. Each source may end in `read` (the default), `write` or `readwrite`. | Source | Meaning | |---|---| | `clear` | drop all earlier sources, including the default | | `default[,<rw>]` | the default files location | | `files,<absolute path>[,<rw>]` | a directory: local disk or a network share | | `nuget,<uri>[,<rw>]` | a NuGet feed, such as GitHub Packages | | `http,<url_template>[,<rw>[,<header>]]` | any HTTP server, with an optional auth header | | `x-azblob`, `x-gcs`, `x-aws`, `x-cos` | cloud storage; marked experimental | | `x-gha` | removed; now only produces a warning | For a GitHub workflow, the vcpkg docs recommend the NuGet provider against GitHub Packages: ```yaml env: VCPKG_BINARY_SOURCES: "clear;nuget,https://nuget.pkg.github.com/<OWNER>/index.json,readwrite" ``` plus a step that registers credentials with the NuGet client vcpkg uses (`vcpkg fetch nuget` reports its path). Alternatives: - `files,<abs path>,readwrite` on a directory your CI system saves and restores with its own cache feature; the docs suggest using vcpkg's binary caching together with a CI-native cache where one exists; - `http,https://cache.example.com/{name}/{version}/{sha},readwrite,Authorization: Bearer <token>` for a team-run server. ## The removed GitHub Actions cache provider Older tutorials configure `clear;x-gha,readwrite`, which stored packages in the GitHub Actions cache. The backend has been removed from vcpkg-tool; in the 2026-09-26 tool used by the 2026.10.16 release, an `x-gha` source only emits a warning that it has been removed and suggests a NuGet-based provider. A pipeline still configured that way silently has no remote cache. ## Why a configured cache can still miss A package is restored only when its ABI hash matches. The hash covers: - every file in the port directory and the helper functions its portfile uses; - the triplet file's contents and name, and any chain-loaded toolchain's text; - the C and C++ compiler, the CMake version and, on Windows, PowerShell; - the selected features and the ABI hash of every dependency. So a runner image with a new compiler or CMake, a moved baseline, or a changed triplet rebuilds everything once and repopulates the cache. The hash inputs of an installed package are kept in `share/<port>/vcpkg_abi_info.txt`, and `--debug` prints the full computation, which is how two hashes are compared when a restore is unexpectedly missed. ## Making the cache mandatory in CI Once a cache is in place, two install options make its behaviour explicit: - `--only-binarycaching` refuses to build anything and fails if a package is missing from every configured cache, which is useful for a job that must only consume what a trusted job produced; - `--skip-install-if-cached` (manifest mode only) skips installation entirely when everything in the plan is already in the binary caches. In a matrix of operating systems and triplets, each combination produces its own archives, because the triplet and compiler are hash inputs; the first run on a new combination is always cold. Pass such options to the configure-time install through `VCPKG_INSTALL_OPTIONS`. ## Verifying it works - The install log reports, per provider, how many packages were restored and how long it took, in lines of the form "Restored N package(s) from <source> in <time>"; a second run with no changes should restore everything and build nothing. - Only `write` or `readwrite` sources receive uploads, so a feed that never fills up usually means `read` was left as the default. - Source downloads are a separate concern, handled by asset caching.

  • Why did a working binary cache suddenly rebuild everything after a CI image update?
    The compiler and CMake versions are inputs to every package's ABI hash. A new image changes them, so no cached archive matches and vcpkg rebuilds and re-uploads once. Pinning the image, or accepting one cold run per image update, are the two choices.
  • What does the clear source do in VCPKG_BINARY_SOURCES?
    It discards every source configured before it, including the default local files cache, so only the sources listed after it are used. Starting with `clear` makes the configuration explicit and avoids writing to a local folder the runner throws away.
  • Is binary caching a way to distribute your dependencies to users?
    No. The docs describe it as reuse of build output between machines that build the same configuration, not as a distribution mechanism; `vcpkg export` exists for packaging built dependencies for others.

  • vcpkg binary caching is off by default and must be enabled with a feature flag.
  • Setting VCPKG_BINARY_SOURCES to clear;x-gha,readwrite caches packages in GitHub Actions.
  • A source without a mode uploads new builds, since readwrite is the default.
  • A cached package is reused whenever the port name and version match.
  • Binary caching also caches the downloaded source archives.

Assumes vcpkg 2026.10.16 with vcpkg-tool 2026-09-26, where the x-gha binary caching provider has been removed and only produces a warning.