👷 Optimize cache usage in workflows by YuriiMotov · Pull Request #16152 · fastapi/fastapi

YuriiMotov · 2026-08-07T05:43:41Z

Description

After upgrading https://github.com/astral-sh/setup-uv to 9.0.0 it started saving downloaded wheels to cache (prune-cache is now false by default).

But there are currently several things that make caching less efficient:

Some workflows install deps with --no-dev but don't use UV_NO_SYNC: false, so uv run still installs dev dependencies and caches them
~15 jobs shared the same cache key, but installed different set of dependencies. It might introduce a race - different cache content depending on what job finished first
Workflows triggered by pull_request still save cache, but this cache is scoped to merge branch and can't be read by others
regression-test job always has cache miss because it copies project from the base branch into base/ and cache-dependency-glob uses all projects to compute the hash by default

This PR introduces several cache key suffixes with different set of dependencies, and ensures that there is at least one job for each cache key that writes cache to default branch scope, so that other workflows would be able to read it.

Cache key suffixes:

dev-all:
- Content: --group dev --extra all
- Writers: warm-cache.yml (default-branch scoped), pre-commit.yml (PR-branch scoped, only available to this PR)
- Readers: pre-commit.yml, bump-pre-commit-hooks.yml, create-draft-release.yml, prepare-release.yml
- Comment: we need warm-cache.yml because pre-commit.yml runs on pull_request and can only write cache scoped to PR branch (others can't read), and other workflows run not regularly and can't keep cache warm
docs:
- Content: --group docs
- Writers and readers: build-docs.yml (writes to default branch scope on push to master branch, so that all other runs can read it)
github-actions:
- Content: --group github-actions
- Writers and readers: label-approved.yml, notify-translations.yml, smokeshow.yml, sponsors.yml, topic-repos.yml, translate.yml
tests-highest:
- Content: --group tests --extra all
- Writers:: matrix items of test job in test.yml except those that use lowest-direct (writes to default branch scope on push to master branch, so that all other runs can read it)
- Readers: all jobs in test.yml except those that use lowest-direct
tests-lowest-direct:
- Content: --group tests --extra all resolved with UV_RESOLUTION=lowest-direct
- Writers and readers: matrix items of test job in test.yml that use lowest-direct (writes to default branch scope on push to master branch, so that all other runs can read it)
translations:
- Content: --group github-actions --group translations
- Writers: langs job
- Readers: matrix items of translate job

AI Disclaimer

Used Claude Code (Opus 5) to investigate and implement the fix. Checked manually

Checklist

This PR links to a GitHub Discussion for the proposed code change.
I added tests for the change.
The new or updated tests fail on the main branch and pass on this PR.
Coverage stays at 100%.
The documentation explains the change if needed.

codspeed-hq · 2026-08-07T05:46:58Z

Merging this PR will not alter performance

✅ 24 untouched benchmarks

_{Comparing optimize-workflow-cache (ff6a7c0) with master (c567218)¹}

No successful run was found on master (4903347) during the generation of this report, so c567218 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

github-actions · 2026-08-07T05:47:15Z

📝 Docs preview

Last commit ff6a7c0 at: https://9dad2be2.fastapitiangolo.pages.dev

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

YuriiMotov · 2026-08-07T06:50:17Z

+env:
+  UV_NO_SYNC: true


Without this, it would skip installing dev group on uv sync --locked --no-dev --group docs, but still install it later on uv run ./scripts/docs.py build-lang ${{ matrix.lang }} and then cache it.
The same in other workflows

YuriiMotov · 2026-08-07T07:24:49Z

+          cache-dependency-glob: |
+            base/pyproject.toml
+            base/uv.lock


We need to use project from base/. By default it would compute the hash on all projects (root directory and base/ directory)

…-cache

github-actions · 2026-08-25T13:21:37Z

This pull request has a merge conflict that needs to be resolved.

…-cache

This reverts commit ac671da.

YuriiMotov · 2026-08-26T15:43:56Z

+          cache-suffix: dev-all
+          # Disable saving cache as we install narrower set of dependencies than dev-all has.
+          save-cache: false


This workflow only needs prek installed.
We can add a dependency group with just prek, use it here and disable cache. But dev-all is always warm (see warm-cache workflow), so I decided to reuse it instead and just disabled saving.

YuriiMotov · 2026-08-26T15:46:16Z

+      - name: Install dependencies
+        run: uv sync --locked --group dev


Added explicit dependency install steps so that it would be clear what dependencies are used by the job

YuriiMotov · 2026-08-26T15:54:56Z

        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          version: "latest-known"
+          cache-suffix: github-actions


Suggested change

cache-suffix: github-actions

cache-suffix: github-actions

enable-cache: true

Since setup-uv v10.0.0, cache for this workflow is disabled (it's triggered by workflow_run) - see release notes.

I think we can safely enable it - we use workflow_run trigger with caution:

No checkout of untrusted branches

Artifacts used safely (just uploading)

Narrow permissions (only statuses: write)

No unpinned dependencies

We use Zizmor to ensure workflow security

Nothing untrusted can write the cache that this job restores

We can also consider disabling Smokeshow workflow temporary for FastAPI repo as it always fails due to upload limits.

YuriiMotov · 2026-08-26T15:57:06Z

        with:
          version: "latest-known"
          enable-cache: true
+          cache-suffix: tests-${{ matrix.uv-resolution }}


We need to include matrix.uv-resolution into cache key in order to prevent possible future collisions if we have two equal matrix items with only difference in uv-resolution.

See: https://github.com/astral-sh/setup-uv#should-i-include-the-resolution-strategy-in-the-cache-key

YuriiMotov · 2026-08-26T15:59:29Z

+            base/pyproject.toml
+            base/uv.lock
+          # Only ever runs on pull requests, so anything it saved would be PR-scoped and useless.
+          save-cache: false


regression-test only runs on pull requests, so anything it saved would be PR-scoped and useless. But it will still use cache written by other jobs

…-cache

YuriiMotov · 2026-08-26T17:56:19Z

+# Populates the `dev-all` uv cache at default-branch scope so that it could be used by
+# `pre-commit.yml` (it has `pull_request` trigger and can't write cache available across PRs)
+# and some others that use subset of dev dependencies.


Other workflows can't write this cache (for dev-all key) because they are either PR-scoped or run too rarely.
This workflow will run every day to ensure dev-all cache is warm and frequently running pre-commit workflow can use it

YuriiMotov added 9 commits August 6, 2026 21:20

Optimize cache for pre-commit workflow

a6d35b9

Optimize cache for test workflow

546c1d0

Optimize cache for build-docs and deploy-docs workflows

64a1499

Optimize cache for 3 workflows by reading dev-all cache

5d9a14e

Optimize cache for GH-actions-related workflows

938d2e6

Add UV_NO_SYNC: true in publish workflow

ae8a2a7

Bump uv version in workflows

8806a3b

Fix possible cache collision for highest and lowest uv resolutions

fbaaa00

Add .python-version to build-docs workflow's filters

ac671da

YuriiMotov added the internal Internal changes label Aug 7, 2026

YuriiMotov and others added 3 commits August 7, 2026 08:47

Merge branch 'master' into optimize-workflow-cache

e7b7077

Add path filters and if org=fastapi for warm-cache workflow

472429b

Allow pre-commit save cache

79c30a9

YuriiMotov requested a lite review from Copilot August 7, 2026 10:43

Copilot started reviewing on behalf of YuriiMotov August 7, 2026 10:44 View session

This comment was marked as resolved.

Sign in to view

Specify --group dev explicitly in warm-cache.yml

9144490

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

YuriiMotov commented Aug 7, 2026

View reviewed changes

YuriiMotov marked this pull request as ready for review August 7, 2026 10:51

This comment was marked as resolved.

Sign in to view

github-actions Bot added the conflicts Automatically generated when a PR has a merge conflict label Aug 8, 2026

Merge remote-tracking branch 'upstream/master' into optimize-workflow…

10375c0

…-cache

github-actions Bot removed the conflicts Automatically generated when a PR has a merge conflict label Aug 10, 2026

YuriiMotov mentioned this pull request Aug 25, 2026

⬆️ Bump setup-uv action to 10.0.1 #16249

Merged

5 tasks

github-actions Bot added the conflicts Automatically generated when a PR has a merge conflict label Aug 25, 2026

YuriiMotov added 2 commits August 26, 2026 17:04

Merge remote-tracking branch 'upstream/master' into optimize-workflow…

fcfe882

…-cache

Revert "Add .python-version to build-docs workflow's filters"

e803afc

This reverts commit ac671da.

YuriiMotov commented Aug 26, 2026

View reviewed changes

YuriiMotov added 2 commits August 26, 2026 18:30

👷 Give translate workflow its own uv cache suffix

4ebedc9

Bump astral-sh/setup-uv to 10.0.1 in warm-cache

da3bf33

github-actions Bot removed the conflicts Automatically generated when a PR has a merge conflict label Aug 26, 2026

Merge remote-tracking branch 'upstream/master' into optimize-workflow…

ff6a7c0

…-cache

YuriiMotov commented Aug 26, 2026

View reviewed changes

		- name: Install dependencies
		run: uv sync --locked --group dev

	cache-suffix: github-actions
	cache-suffix: github-actions
	enable-cache: true

Uh oh!

Uh oh!

Conversation

YuriiMotov commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

AI Disclaimer

Checklist

Uh oh!

codspeed-hq Bot commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

github-actions Bot commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📝 Docs preview

Uh oh!

This comment was marked as resolved.

Uh oh!

YuriiMotov Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

YuriiMotov Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This comment was marked as resolved.

github-actions Bot commented Aug 25, 2026

Uh oh!

YuriiMotov Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YuriiMotov Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

YuriiMotov Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YuriiMotov Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YuriiMotov Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YuriiMotov Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

YuriiMotov commented Aug 7, 2026 •

edited

Loading

codspeed-hq Bot commented Aug 7, 2026 •

edited

Loading

github-actions Bot commented Aug 7, 2026 •

edited

Loading

YuriiMotov Aug 26, 2026 •

edited

Loading

YuriiMotov Aug 26, 2026 •

edited

Loading

YuriiMotov Aug 26, 2026 •

edited

Loading

YuriiMotov Aug 26, 2026 •

edited

Loading

YuriiMotov Aug 26, 2026 •

edited

Loading