Your branch reads what CI built for it

A remote cache scope is now the branch. A laptop that checks out a pull request’s branch reads what CI already built for it, and each task asks the remote one key instead of two.

This release is breaking for anyone who set a cache scope, used run.affectedBase, or runs a bare --affected on the base branch. Read the breaking changes first.

Enjoy the release!

In this release

• Your laptop reads what CI built for your branch
• Affected runs on the base branch name a commit
• Breaking changes

Your laptop reads what CI built for your branch

A pull request’s cache scope was pr-<n>. A laptop on the same branch could not name it, so it rebuilt what CI had already built there. A scoped run also asked the remote two keys per task, main’s and then the scope’s, and a scope split the local cache too.

Now the scope is <owner>/<repo>:<branch>. On GitHub Actions, github() from @vzn/vx-ci names it from the event: a pull request from feat-x is acme/app:feat-x, and a fork’s is eve/app:feat-x. A checkout with a remote cache derives the same name from .git, with no network, and has none on the base branch.

Run	Scope	Remote writes
push to the default branch	none	the default keys
push to, or pull request from, feat-x	acme/app:feat-x	that scope only
pull request from a fork’s feat-x	eve/app:feat-x	that scope only

Each task asks the remote one key. A task the branch changed (its declared inputs match a changed file, or a dependsOn task’s do) reads the scope’s entry; every other task reads main’s, so a README edit leaves build on main’s entry. CI saves every task it builds under the scope, so a branch never writes main’s keys.

The local cache never knows a scope. What a laptop fetches for its branch it keeps under the task key, so the same inputs hit locally on any branch, main included. The summary’s info row names the scope:

  info      4 workers · local + remote cache · scope acme/app:feat-x · run …

What a branch changed is the diff from a pull request’s base commit (github() reads it from the event, so fetch-depth: 2 is enough), else from the merge base with origin/<baseBranch>. Git is asked for that diff only at a scoped run’s first remote call, so a run the local cache answers asks it nothing more. VX_CACHE_SCOPE names a scope by hand, for a CI with a detached HEAD, and an empty value turns it off. See Cache scopes and tokens.

Affected runs on the base branch name a commit

A bare --affected on the base branch guessed HEAD~1, which is wrong after any push of more than one commit. It now compares with the same base the cache scope uses, and on the base branch it asks for the commit to compare with:

$ vx run build --affected --dry
✗ vx run  --affected has no default on the base branch (main): name the last good commit, --affected=<sha>

run.affectedBase is now baseBranch, a branch name, read from VX_BASE_BRANCH. Unset, it is origin/HEAD’s branch, then main, then master.

Breaking changes

• --cache-scope and cache.scope → removed. VX_CACHE_SCOPE names a scope by hand; empty turns it off.
• run.affectedBase / VX_RUN_AFFECTED_BASE → baseBranch / VX_BASE_BRANCH, a branch name.
• A bare --affected on the base branch → refused. Pass --affected=<sha>.
• github() → scopes <owner>/<repo>:<branch>, not pr-<n>. Entries saved under pr-<n> are no longer read.
• The local cache → keeps every entry under its task key, whatever the scope.
• Plugin API: a cache call carries its scope (absent for a default key), and the config hook’s ctx gains setBranch.

See also Upgrading.

How to update

npm install -D @vzn/vx@latest
npx @vzn/vx lock

A standalone binary updates itself with vx upgrade.