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?
answer
- the default cache lives on the runner
- fresh VM, empty archives folder
- VCPKG_BINARY_SOURCES with readwrite
- the removed x-gha provider
basics
~20 svcpkg'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 sBinary 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# 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 cigo deeper
Recall that vcpkg can reuse built packages through binary caching and that VCPKG_BINARY_SOURCES configures where they are stored.
Explain the default local cache, why ephemeral runners never benefit from it, and the source syntax with clear and read, write or readwrite.
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.
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.