CI / Speed and debugging
Skip a slow step when its inputs did not change
A slow step, like a build or a code generator, takes minutes in every run, but its files change only in some pull requests. A step cache skips the step when it already passed with the same input files: the files that it made come back from the cache.
6 min read
Before the step runs, the runner hashes the files that the step reads. Without Nx or Turborepo, nothing else skips the step for you.
To skip the tests of the packages of a monorepo that did not change, see Skip the tests of packages that did not change.
1. Add cache to the step
Give the step cache, with the files that it reads (inputs) and the files that it makes (outputs):
import { defineWorkflow, pullRequest, push, setup } from '@tanstack-source/ci'
export default defineWorkflow('ci', { on: [pullRequest({ branches: ['main'] }), push({ branches: ['main'] })] })
.job('test', {
steps: [
setup.node(),
setup.pnpm(),
{ name: 'Install dependencies', run: 'pnpm install --frozen-lockfile' },
{
name: 'Generate the API client',
run: 'pnpm codegen',
cache: { inputs: ['schema/**', 'codegen.ts', 'pnpm-lock.yaml'], outputs: ['src/generated'] },
},
{ name: 'Test', run: 'pnpm test' },
],
})
A do step takes cache too:
{
name: 'Build the docs',
do: async (ctx) => {
await ctx.sh`pnpm docs:build`
},
cache: { inputs: ['docs/**', 'docs.config.ts'], outputs: ['docs/dist'], key: 'docs-v1' },
}
2. Push the workflow
The first run has no entry for the step yet. The step runs, and its log starts with:
No cache for step-3f2a... (12 input files): the step runs, and saves its outputs if it passes
When the step passes, the runner saves its outputs at once, before the next step starts. The last line of its log is Saved the cache step-3f2a....
3. Push a change that does not touch the inputs
The step does not run in the new run:
- Its name has
(cached)after it, likeGenerate the API client (cached), in the step list and on the Timing card. - Its log says
Restored the outputs from the cache step-3f2a... This step did not run. - Its outputs are in the workspace, so the steps after it use them as usual.
Done
The slow step runs only when one of its inputs changes. Change a file of the inputs, and the step runs again, and saves a new entry.
Cache a step that makes no files
A test step or a lint step makes no files. Leave out outputs:
{ name: 'Lint', run: 'pnpm lint', cache: { inputs: ['src/**', 'eslint.config.js', 'pnpm-lock.yaml'] } }
When the step passes, the runner saves only that it passed with these inputs. On a hit, the step does not run, and nothing comes back. Its log on a miss ends with saves that it passed if it passes.
Cache each cell of a matrix
The values of the matrix cell are in the key, so each cell of a matrix job has its own entry. A cell that passes does not make the other cells skip.
When the cells read other files, give cache a function of the ctx of the step:
.job('test', {
matrix: { suite: ['git', 'ci', 'cli'] },
steps: [
setup.node(),
setup.pnpm(),
{ name: 'Install dependencies', run: 'pnpm install --frozen-lockfile' },
{
name: 'Tests',
do: async (ctx) => {
await ctx.sh`pnpm -C packages/${ctx.matrix.suite} test`
},
cache: (ctx) => ({ inputs: [`packages/${ctx.matrix.suite}/**`, 'pnpm-lock.yaml'] }),
},
],
})
- The runner calls the function before the step, after its
if. - When the function gives a cache that breaks a rule, the step fails with the reason.
- The plan cannot know what the function gives.
src ci plan --jsonshows the cache of the step as{ "atRunTime": true }.
What goes into the key
The key is step- and a sha256 of:
- The name of the step. For a
runstep, also its command and itsworkingDirectory. Adostep has no command text in the key: change itskeywhen you change its function. - The image of the job (
nodeorbrowser), and thekeyof the cache, when you give one. - The values of the matrix cell, in a job with a matrix.
- The path and the content of each input file.
- Whether the step has
outputs. So the entry of a step with no outputs never restores as the outputs of a step.
With package, the key also has the package folder and the files of the package. See What goes into the key of a package cache.
The env of the step is not in the key.
Choose the inputs
List every file that can change the outputs:
- The source files of the step, like
schema/**orsrc/**. - Its configuration files, like
codegen.tsortsconfig.json. - The lockfile, when the step runs a tool from your dependencies. A new version of the tool can make other outputs.
The rules:
- 1 to 100 paths or globs in the repository (0 to 100 with
package).*matches in one folder,**matches in any number of folders,?matches one character. A folder stands for all the files in it. - No
!patterns, no.., no/at the start, and no~. - Keep a glob in a folder, like
src/**/*.ts. A glob at the root, like**/*.ts, reads every folder of the workspace, alsonode_modules. - When no file matches the inputs, the step runs, and saves nothing. Its log says so.
outputs is optional. Its rules are the rules of the paths of cache(): 0 to 100 files, folders or globs, relative to the workspace or under ~, with no !.
key is optional: 1 to 512 printable ASCII characters. Change it to start over, for example after you change a do step.
What can go wrong
- A wrong
inputslist gives a wrong hit. When the step reads a file that is not ininputs, a change to that file does not run the step. The run uses the old outputs. There is no check for this. Read the Timing card: each step with(cached)after its name did not run in that job. - A skipped step does nothing else. On a hit, only the outputs come back. What the step did besides its files does not happen:
ctx.setOutput,ctx.summary,ctx.addPath,ctx.afterJob, and changes outside the outputs. - A failed step saves nothing. A step that passed saves its outputs, also when a later step of the job fails.
- A save or a restore that fails does not fail the job. The log of the step says why, and the step runs.
Who reads which entry
A step cache entry is a cache entry, so it follows the cache scopes. A pull request from a fork saves its entries in the scope of its pull request, and no trusted or protected run restores them. An untrusted run without a pull request saves none.
A job of a hidden workflow neither restores nor saves a step cache. Its steps always run.
To see the entries, run src ci cache list: their keys start with step-. To delete them, run src ci cache delete, or use Settings > CI > Cache.
Run it on your machine
src ci run uses the step cache too. A local run keeps the entries in the cache folder of your machine, next to the entries of cache() (see Run CI jobs on your machine). The second local run with the same inputs prints --- Generate the API client (cached): passed.