Skip to content
Source
Sign inSign up

Cache your CI steps

Software factory / Pull requests

Get a pull request that caches your CI steps

Your CI runs each test step in each run, also when the files of the step did not change. A step cache or a package cache skips these steps, but you must find the files that each step reads and write each cache yourself.

6 min read

The CI cache agent does this work. It runs each job of your workflows in a sandbox, with a tracer that records the files that each step reads. From that list, it adds cache to your steps and opens one pull request. Nothing is cached until you merge it.

The agent is on by default. You need admin access to the repository to start it by hand or to turn it off.

1. Start the agent

The agent starts by itself after a push to the default branch that changes a file in .source/workflows/. A push that adds your first workflow counts too.

To start it now:

  1. Open the repository, then Settings, then CI.
  2. In the Cache card, click Suggest caches.
  3. Click Open its run to read the log of the run.

From a terminal, run src ci cache suggest. It prints the id of the run.

Note

Only one run of the agent goes at a time. While a run waits or runs, a new start is refused with "A CI cache run is already running."

2. Wait for the run

The run starts in a sandbox, on the newest commit of the default branch:

  1. The agent reads each workflow file.
  2. For each job, it runs the job one time with src ci run. A Node tracer records the files that each step reads, grouped by workspace package.
  3. The agent writes the cache of each step from that list:
    • package for a step that reads one package
    • inputs for files outside the package
    • a function cache for a matrix step whose cells read other files
  4. Code checks the change. Then it pushes the branch factory/ci-cache and opens the pull request "ci: cache the CI steps".

Code makes these checks before the push. The model cannot change them:

  • The change touches only .source/workflows/*.ts.
  • The plan of the workflows (src ci plan --json) is the same before and after the change, except for the cache of steps.
  • No step of a job with secrets or write permissions gets a cache.
  • The push goes only to factory/ci-cache.

If a check fails, nothing is pushed. The run ends with one verdict:

VerdictMeaning
suggestedThe agent opened or updated the pull request.
nothing-to-cacheNo step can get a cache. The verdict gives the reason.
could-not-traceThe jobs failed in the trace. The verdict gives the reason and the end of the output.

3. Review the pull request

Warning

A cache with a missing input gives a wrong pass: the step shows as passed, but it did not run. Read what the agent cached before you merge.

  1. Open the pull request "ci: cache the CI steps". The bot opened it from the branch factory/ci-cache. It goes through screening first, as the other pull requests of the bot do.
  2. Read Cached steps in the body. Each line names a step, what its cache hashes (the package and the inputs), and its outputs. Code writes this list from the plan, not the model.
  3. If the body has Warnings, read them. A step there started a program that is not Node, for example git or bash. The tracer does not see the files that such a program reads. Add these files to the inputs of the step, or remove its cache.
  4. Open Files changed. Only the cache of steps in .source/workflows/*.ts changes.
  5. Wait for CI, then merge the pull request.

What can go wrong lists the other cases that give a wrong pass.

4. See the cached steps

Push a change to one package after the merge. In the new CI run, a step whose files did not change shows (cached) after its name. It did not run.

Done

After each change to your workflows, the agent opens a pull request that caches your CI steps. You review the cached steps and the warnings, and merge. Then the steps whose files did not change show (cached), and CI gets faster.

When the agent runs again

Each push to the default branch that changes a workflow starts a new run. The run pushes its change over the branch factory/ci-cache. It updates the open pull request, or opens a new one. The agent keeps at most one open pull request.

If you push to factory/ci-cache, the agent leaves the branch and its pull request alone:

  • Update branch on the pull request does not count as a push: it only merges the base into the branch.
  • The next runs of the agent are skipped with "Someone else pushed to the branch, so the agent leaves it and its pull request alone."
  • To give the branch back to the agent, merge or close the pull request, then delete the branch.

Turn off the agent

  1. Open the repository, then Agents.
  2. In the sidebar, click Agents under Software factory.
  3. Turn off the switch of CI cache. It saves at once.

From the CLI, an admin runs src factory configure --file change.json, with {"agents": {"ci-cache": {"enabled": false}}} in change.json. See Change the settings with src.

From src, REST or MCP

Coding agents and scripts can start the agent too:

You want tosrcRESTMCP
Start the agent nowsrc ci cache suggestPOST /api/v1/repos/{owner}/{repo}/ci/cache/suggestsuggest_ci_caches
src ci cache suggest
src ci cache suggest --json
  • All three need admin access to the repository.
  • src ci cache suggest prints the id of the run. Read the run with src factory run <run id>.
  • The REST route answers 201 with {"runId": "<run id>"}.
  • When no run starts, the answer is 409 with the reason: the agent is off, a run waits or runs, or a person pushed to factory/ci-cache.

What the agent never does

It never changes more than the caches:

  • It never changes the command, the name, the env or the condition of a step. It never adds or removes a step, a job, a secret or a permission. Code refuses such a change.
  • It never caches a step of a job with secrets or write permissions.
  • It never merges its pull request.

Its sandbox and its runs:

  • The sandbox gets no secret. A job that needs a secret fails in the trace, and the agent gets only the reads before the failure.
  • The sandbox reaches only the forge and the package registries registry.npmjs.org and repo.yarnpkg.com.
  • The runs wait in the same queue as the CI jobs of the account, and the CI limits count them too.