Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

CI: trigger Studio smokes on what they observe, run install matrices as a PR subset, fold Chat UI shards (#10689)

Daniel Han9e8b747b3745
diff --git a/.github/actions/install-unsloth-local/action.yml b/.github/actions/install-unsloth-local/action.yml
index 445de0ac3da..f14ba17848f 100644
--- a/.github/actions/install-unsloth-local/action.yml
+++ b/.github/actions/install-unsloth-local/action.yml
@@ -57,41 +57,15 @@ inputs:
runs:
using: composite
steps:
- # This step is the single largest cost in CI: 92s median across 39 job runs
- # in one sample, which is more total time than any test. All of it is uv
- # resolving and DOWNLOADING the same wheels, in every job, every run, because
- # uv's cache is per-runner and nothing carried it between them.
- #
- # A download cache is the safest kind there is. uv's is content-addressed by
- # URL and hash, so a stale entry cannot serve wrong content -- the worst it can
- # do is miss. Nothing about which packages get installed changes; they just are
- # not fetched twice. That is the difference between this and caching the venv,
- # which would have to reason about an editable overlay, a moving
- # `unsloth-zoo @ git+main`, and absolute paths baked into console scripts.
- #
- # UV_CACHE_DIR is set explicitly rather than relying on ~/.cache/uv, so the
- # path is the same on Linux and macOS and one cache config covers both. It is
- # exported into the environment so install.sh, studio/setup.sh and every uv
- # call underneath inherit it.
- - name: Point uv's cache somewhere cacheable
- shell: bash
- run: |
- echo "UV_CACHE_DIR=${{ github.workspace }}/.uv-cache" >> "$GITHUB_ENV"
- mkdir -p "${{ github.workspace }}/.uv-cache"
-
- # Keyed on what decides the resolution, with a prefix fallback: a near-miss
- # still supplies almost every wheel, which is most of the win. A download cache
- # wants restore-keys for exactly this reason, where a venv cache must not have
- # them.
+ # The uv download cache. Delegated, like the frontend dist below, so the key has
+ # exactly one definition: the Windows jobs run install.ps1 from a hand-written pwsh
+ # step and never come through here, and a second copy would drift silently. The
+ # reasoning lives in .github/actions/uv-cache-restore, which folds the UV_CACHE_DIR
+ # setter and the restore into this one step; tests/studio/test_uv_cache_discipline.py
+ # inlines them again and still checks their order against the install.
- name: Restore the uv download cache
id: uv-cache
- uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
- continue-on-error: true
- with:
- path: ${{ github.workspace }}/.uv-cache
- key: uv-${{ runner.os }}-${{ hashFiles('studio/backend/requirements/**', 'pyproject.toml') }}
- restore-keys: |
- uv-${{ runner.os }}-
+ uses: ./.github/actions/uv-cache-restore
# The frontend build is the other half of this step, and unlike the wheels it is
# not a download at all. Measured over 13 distinct Linux jobs on main, using the
@@ -170,10 +144,7 @@ runs:
# `building frontend` line fails the job) for free, in the same place the eight
# five Windows job-legs get it.
#
- # `uv cache prune --ci` further down: uv keeps built wheels AND unpacked source
- # artifacts, and only the former are worth carrying between runners. Without it
- # that key grows without bound across 39 jobs and re-opens the eviction thrash
- # the GGUF caches were fixed for.
+ # The uv save is delegated the same way, `uv cache prune --ci` included.
- name: Save the built frontend
uses: ./.github/actions/frontend-dist-save
with:
@@ -181,18 +152,7 @@ runs:
key: ${{ steps.fe-dist.outputs.key }}
- name: Save the uv download cache
- if: always() && github.ref == 'refs/heads/main' && steps.uv-cache.outputs.cache-hit != 'true'
- shell: bash
- run: |
- # Best effort: an older uv without `prune --ci` must not fail the install
- # that has already succeeded.
- uv cache prune --ci 2> /dev/null || true
- du -sh "${{ github.workspace }}/.uv-cache" 2> /dev/null || true
-
- - name: Save the uv download cache (upload)
- if: always() && github.ref == 'refs/heads/main' && steps.uv-cache.outputs.cache-hit != 'true'
- uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
- continue-on-error: true
+ uses: ./.github/actions/uv-cache-save
with:
- path: ${{ github.workspace }}/.uv-cache
- key: uv-${{ runner.os }}-${{ hashFiles('studio/backend/requirements/**', 'pyproject.toml') }}
+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}
+ key: ${{ steps.uv-cache.outputs.key }}
diff --git a/.github/actions/uv-cache-restore/action.yml b/.github/actions/uv-cache-restore/action.yml
new file mode 100644
index 00000000000..42bf018574e
--- /dev/null
+++ b/.github/actions/uv-cache-restore/action.yml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+# The uv download cache, restore half. One definition of the key, for the same reason
+# frontend-dist-restore has one: the Windows jobs run install.ps1 from a hand-written pwsh
+# step and never go through install-unsloth-local, so a pasted copy would drift silently.
+# A download cache is the safest kind: uv's is content-addressed by URL and hash, so a
+# stale entry cannot serve wrong content, only miss. Caching the VENV instead would have to
+# reason about an editable overlay, a moving `unsloth-zoo @ git+main` and absolute paths
+# baked into console scripts; tests/studio/test_uv_cache_discipline.py pins that
+# distinction and the cold-install lanes that must never adopt this.
+# UV_CACHE_DIR is set explicitly so one config covers Linux, macOS and Windows, and
+# exported so install.sh, install.ps1 and studio/setup.* inherit it; install.ps1 preserves
+# a custom value. ROOT-CHECKOUT ONLY: the path below is workspace-relative.
+
+name: Restore the uv download cache
+description: >-
+ Point UV_CACHE_DIR at a workspace directory and restore uv's download cache
+ into it, keyed on what decides the resolution. Read-only: the save is a
+ separate action and runs on the default branch only.
+
+outputs:
+ cache-hit:
+ description: "'true' when the exact key was restored."
+ value: ${{ steps.restore.outputs.cache-hit }}
+ key:
+ description: The full cache key, to hand to uv-cache-save.
+ value: ${{ steps.restore.outputs.cache-primary-key }}
+
+runs:
+ using: composite
+ steps:
+ - name: Point uv's cache somewhere cacheable
+ shell: bash
+ run: |
+ echo "UV_CACHE_DIR=${{ github.workspace }}/.uv-cache" >> "$GITHUB_ENV"
+ mkdir -p "${{ github.workspace }}/.uv-cache"
+
+ # Keyed on what decides the resolution, with a prefix fallback: a near-miss still
+ # supplies almost every wheel. A download cache wants restore-keys for exactly that
+ # reason, where a venv cache must not have them. runner.os: wheels differ per platform.
+ - name: Restore the uv download cache
+ id: restore
+ uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+ continue-on-error: true
+ with:
+ path: ${{ github.workspace }}/.uv-cache
+ key: uv-${{ runner.os }}-${{ hashFiles('studio/backend/requirements/**', 'pyproject.toml') }}
+ restore-keys: |
+ uv-${{ runner.os }}-
diff --git a/.github/actions/uv-cache-save/action.yml b/.github/actions/uv-cache-save/action.yml
new file mode 100644
index 00000000000..95dc9e1eee8
--- /dev/null
+++ b/.github/actions/uv-cache-save/action.yml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+# The uv download cache, save half. Paired with uv-cache-restore, which owns the key.
+# Default branch only: a PR-scoped entry is restorable only by re-runs of that same PR,
+# while every PR can restore from main, so saving on PRs spends a near-full budget to evict
+# main's copy, the one everyone reads. A hit is not re-uploaded either.
+# `uv cache prune --ci` first: uv keeps built wheels AND unpacked source artifacts, only the
+# former worth carrying, so without it the entry grows without bound and re-opens the
+# eviction thrash the GGUF caches were fixed for. Best effort: an older uv without `--ci`,
+# or a uv off this step's PATH, must not fail an install that already succeeded.
+
+name: Save the uv download cache
+description: >-
+ Prune uv's download cache to what is worth carrying, then save it under the
+ restore step's key, on the default branch only.
+
+inputs:
+ cache-hit:
+ description: >-
+ uv-cache-restore's `cache-hit` output. 'true' skips the save: the key is
+ already present and re-uploading it is pure cost.
+ required: true
+ key:
+ description: uv-cache-restore's `key` output.
+ required: true
+ save:
+ description: >-
+ 'false' to skip the upload. For a workflow whose triggers cannot routinely
+ put github.ref on refs/heads/main (no `push`, no `schedule`), where the save
+ below could only fire if a human dispatched the workflow from main by hand.
+ Such a workflow consumes the cache the producers fill and declares here that
+ it is not one of them, rather than carrying a save that never runs.
+ required: false
+ default: 'true'
+
+runs:
+ using: composite
+ steps:
+ - name: Prune the uv download cache to what is worth carrying
+ if: >-
+ github.ref == 'refs/heads/main' && inputs.cache-hit != 'true'
+ && inputs.save != 'false'
+ shell: bash
+ run: |
+ uv_bin="$(command -v uv 2> /dev/null || true)"
+ for candidate in "$HOME/.local/bin/uv" "$HOME/.local/bin/uv.exe" "$HOME/.cargo/bin/uv" "$HOME/.cargo/bin/uv.exe"; do
+ [ -n "$uv_bin" ] && break
+ [ -x "$candidate" ] && uv_bin="$candidate"
+ done
+ if [ -n "$uv_bin" ]; then
+ "$uv_bin" cache prune --ci 2> /dev/null || true
+ else
+ echo "uv is not on PATH in this step; saving the cache unpruned"
+ fi
+ du -sh "${{ github.workspace }}/.uv-cache" 2> /dev/null || true
+
+ - name: Save the uv download cache
+ if: >-
+ github.ref == 'refs/heads/main' && inputs.cache-hit != 'true'
+ && inputs.save != 'false'
+ uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+ continue-on-error: true
+ with:
+ path: ${{ github.workspace }}/.uv-cache
+ key: ${{ inputs.key }}
diff --git a/.github/ci-preempt.json b/.github/ci-preempt.json
index 7975a1a773f..f566e7e2142 100644
--- a/.github/ci-preempt.json
+++ b/.github/ci-preempt.json
@@ -15,7 +15,8 @@
"way to reach one leg of a matrix. So a mixed-platform workflow filed under",
"one class only is invisible to a pause naming the others, and its jobs on",
"the class being held keep refilling the pool the pause is paying for.",
- "clean-machine-install-ci.yml alone is 6 linux and 7 windows legs.",
+ "clean-machine-install-ci.yml alone is 6 linux and 7 windows legs on its nightly",
+ "(a PR runs 2 linux and 1 windows; see .github/ci/clean-machine-matrix.yml).",
"",
"The cost of the rule is the converse: a linux pause now also takes that",
"workflow's 7 macOS legs down. That is the right way round. Losing coverage",
diff --git a/.github/ci/clean-machine-matrix.yml b/.github/ci/clean-machine-matrix.yml
new file mode 100644
index 00000000000..150717c20cb
--- /dev/null
+++ b/.github/ci/clean-machine-matrix.yml
@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+# The legs of .github/workflows/clean-machine-install-ci.yml, one list per matrix job.
+# `pr: true` legs run on pull_request; everything runs nightly, on push to main and on
+# workflow_dispatch. The `select` job strips `pr`, so a leg's other keys are exactly what
+# the steps read as `matrix.<key>`. macOS is capped at five concurrent jobs account-wide
+# and the full set (20 jobs, 7 macOS) never once finished on a PR before the next push
+# cancelled it, so the subset keeps one leg per claim and defers OS/arch-only legs.
+# tests/studio/test_install_matrix_selection.py pins the counts and the keys.
+
+macos:
+ # `overlay` decides whether this ref's Python is under test; the pipe legs stay on the
+ # released package on purpose.
+ # The reported failure, in the `curl | sh` shape users run, with torch as a consumer
+ # gets: the only leg that can see a truncated script or a curl: (56) from an early exit.
+ - {os: macos-15, mode: mask, delivery: pipe, flags: '', experimental: false, overlay: false, pr: true}
+ - {os: macos-15, mode: mask, delivery: file, flags: '', experimental: false, overlay: true, pr: true}
+ # What the desktop app runs: no tty, stdin closed, TAURI markers on, legacy ~/.unsloth.
+ - {os: macos-15, mode: mask, delivery: tauri, flags: '', experimental: false, overlay: true, pr: false}
+ # Toolchain present but logged: uv's managed-libpython self-ID patch is the one call
+ # allowed. No overlay: setuptools-scm's editable build would call git itself.
+ - {os: macos-15, mode: trace, delivery: file, flags: '', experimental: false, overlay: false, pr: true}
+ # --no-torch is the one macOS path that can still want a compiler (no guaranteed cp313
+ # arm64 sentencepiece wheel), so probe it apart from the default path.
+ - {os: macos-15, mode: mask, delivery: file, flags: '--no-torch', experimental: true, overlay: true, pr: false}
+ # The next macOS image, same asserts as the macos-15 file leg.
+ - {os: macos-26, mode: mask, delivery: file, flags: '', experimental: true, overlay: true, pr: false}
+ # Intel pins python 3.12 and its /usr/bin/git is not CLT-provided, so it survives
+ # masking. Informational only.
+ - {os: macos-15-intel, mode: mask, delivery: file, flags: '', experimental: true, overlay: true, allow_working: 'git', pr: false}
+
+linux:
+ # Root + apt: _smart_apt_install self-heals from an image with no curl, git, gcc or
+ # cmake. Nightly only: the nonroot leg below proves everything this one does and more.
+ - label: ubuntu2404-root
+ image: ubuntu:24.04
+ runner: ubuntu-latest
+ experimental: false
+ overlay: true
+ pr: false
+ # The arm64 dimension of the root leg.
+ - label: ubuntu2404-arm-root
+ image: ubuntu:24.04
+ runner: ubuntu-24.04-arm
+ experimental: false
+ overlay: true
+ pr: false
+ # No elevation, but WITH the transport the one-liner needs: no elevation path anywhere
+ # on the image, no toolchain, ca-certificates + curl and nothing else. Since #7547 the
+ # optional set never escalates, so this must install end to end off prebuilt llama.cpp.
+ # overlay: true because the RELEASED install_python_stack.py has no "skip triton kernels
+ # when git is missing" guard and would die at the final step on release lag alone.
+ - label: ubuntu2404-nonroot
+ image: ubuntu:24.04
+ runner: ubuntu-latest
+ experimental: false
+ overlay: true
+ nonroot: true
+ pr: true
+ # The same premise with the OTHER transport. install.sh falls back to wget everywhere it
+ # prefers curl (729-738, 1019-1027, 3064-3067) and calls the transport missing only when
+ # BOTH are gone (2077-2079), so a wget-only box (Debian netinst default) is supported on
+ # paper and had never been run: the row above provisions curl, which won every probe.
+ - label: ubuntu2404-nonroot-wget
+ image: ubuntu:24.04
+ runner: ubuntu-latest
+ experimental: false
+ overlay: true
+ nonroot: true
+ wget_only: true
+ pr: false
+ # No elevation AND no transport, so failing is correct: pin the exact message and prove
+ # it actionable rather than a bare `curl: (56)`. No overlay: it never reaches a venv.
+ - label: ubuntu2404-nonroot-notransport
+ image: ubuntu:24.04
+ runner: ubuntu-latest
+ experimental: false
+ overlay: false
+ nonroot: true
+ no_transport: true
+ pr: true
+ # Non-apt: hard-fails at install.sh:2034 today. Tolerate the install STEP, not the job:
+ # job-level continue-on-error would swallow the outcome assertion too.
+ - label: fedora41
+ image: fedora:41
+ runner: ubuntu-latest
+ experimental: false
+ overlay: true
+ tolerate_install_failure: true
+ pr: false
+
+windows:
+ - os: windows-latest
+ winget: 'visible'
+ experimental: false
+ overlay: true
+ pr: true
+ # The no-winget path (LTSC / Server / managed corporate) falls back to python.org +
+ # astral.sh and is where Ensure-VCRedist silently does not run, leaving torch unable to
+ # load: hence the explicit `import torch` assert below. #7549 relaxed setup.ps1's
+ # unconditional git gate (1750-1759), and the assert proves it took the relaxed branch
+ # rather than passing on git leaking back onto PATH.
+ - os: windows-latest
+ winget: 'masked'
+ experimental: false
+ overlay: true
+ pr: false
+ # Windows on ARM gets a native ARM64 CPython and torchaudio publishes no win_arm64 wheel
+ # (nor do pyarrow and hf-transfer), so PyTorch could not resolve until #7549 made the
+ # installer prefer an emulated x64 interpreter (install.ps1:1160-1253, 1335-1353). The
+ # assert below checks that outcome, not the log line announcing it.
+ - os: windows-11-arm
+ winget: 'visible'
+ experimental: false
+ overlay: true
+ pr: false
+
+windows_container_install:
+ # The consumer path: install.ps1 from this ref, unsloth from PyPI, so studio/setup.ps1
+ # comes out of the RELEASED wheel rather than this ref's. Both rows gate.
+ - overlay: false
+ pr: false
+ # This ref's studio/setup.ps1 and install_python_stack.py, via UNSLOTH_CI_SOURCE_OVERLAY
+ # (install.ps1:2643); without it a branch changing setup.ps1 proves nothing. On PRs too:
+ # the only environment with no preinstalled VC++ runtime.
+ - overlay: true
+ pr: true
diff --git a/.github/ci/interrupted-install-matrix.yml b/.github/ci/interrupted-install-matrix.yml
new file mode 100644
index 00000000000..e147f3dfd3f
--- /dev/null
+++ b/.github/ci/interrupted-install-matrix.yml
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+# The legs of .github/workflows/interrupted-install-ci.yml, one list per matrix job.
+# `pr: true` legs run on pull_request; everything runs nightly and on workflow_dispatch.
+# Every leg is a hard gate, with no continue-on-error cell: a leg allowed to fail is a
+# warning wearing a red icon, and the claim here is that a killed install cannot report
+# itself healthy. The PR subset (10 legs, 6 macOS, five concurrent macOS jobs account-wide)
+# takes one leg per verdict family on different operating systems: `studio-deps`, a partial
+# venv that reports HEALTHY, and `torch`, a complete venv with nothing in it where the
+# re-run must repair rather than short-circuit on the version fast path.
+# tests/studio/test_install_matrix_selection.py pins the counts and the keys.
+
+interrupt:
+ # A marker, never a delay: every label prints BEFORE its work, so the kill lands inside
+ # the phase, while a timed wait bets on phase duration and twice turned a leg into a
+ # duplicate of the next one. This one is the reported case, killed installing structlog.
+ - {os: macos-15, label: studio-deps, marker: 'studio deps', pr: true}
+ # Coarse phases, earliest to latest, each leaving a different partial venv. No venv leg:
+ # "Creating virtual environment" runs ~0.1s, shorter than any poll, so its kill always
+ # landed in the NEXT phase and the leg duplicated this one.
+ - {os: macos-15, label: torch, marker: '\[TAURI:STEP\] Installing PyTorch', pr: false}
+ - {os: macos-15, label: unsloth, marker: '\[TAURI:STEP\] Installing Unsloth', pr: false}
+ # The latest phase, the closest to a complete-looking install.
+ - {os: macos-15, label: setup, marker: '\[TAURI:STEP\] Running Unsloth setup', pr: false}
+ # Other dependency-pass sub-steps around the named one. No pip-bootstrap leg (over before
+ # a poll can see it) and no base-packages leg (--local sets skip_base, so it never prints
+ # and the leg ran to completion, proving nothing).
+ - {os: macos-15, label: unsloth-extras, marker: 'unsloth extras', pr: false}
+ # Killed before install_python_stack.py writes the manifest.
+ - {os: macos-15, label: data-designer, marker: 'data designer deps', pr: false}
+ # Linux: same teardown path, different package manager and process semantics.
+ - {os: ubuntu-latest, label: studio-deps, marker: 'studio deps', pr: false}
+ - {os: ubuntu-latest, label: torch, marker: '\[TAURI:STEP\] Installing PyTorch', pr: true}
+
+# Windows has no process groups, so the kill path differs. Both legs are nightly only:
+# the verdict families are covered on PRs by the POSIX legs.
+interrupt_windows:
+ # install.ps1:121 parses `--no-torch`; `-SkipTorch` matches no case there and is
+ # silently dropped. The torch leg must NOT skip torch or its marker never appears.
+ - {label: studio-deps, marker: 'studio deps', installArgs: '--tauri --no-torch --local', pr: false}
+ - {label: torch, marker: 'Installing PyTorch', installArgs: '--tauri --local', pr: false}
diff --git a/.github/scripts/select_install_matrix.py b/.github/scripts/select_install_matrix.py
new file mode 100644
index 00000000000..d05cfff2b3b
--- /dev/null
+++ b/.github/scripts/select_install_matrix.py
@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""Pick the legs of an install workflow for the event that triggered it.
+
+Reads a matrix file (`.github/ci/*-matrix.yml`: one list of legs per matrix job, each
+leg carrying a `pr` flag) and prints one `<job>={"include": [...]}` line plus a
+`<job>_count=<n>` line per job, in the form `$GITHUB_OUTPUT` takes. On `pull_request` only the `pr: true` legs are
+emitted; on every other event (schedule, push, workflow_dispatch) all of them are. The
+`pr` key never reaches the workflow: what a job sees through `matrix.<key>` is exactly
+what the leg declares, so the steps are unchanged by the selection.
+
+The output is JSON on one line per job, which is what `fromJSON()` in the consuming
+`strategy.matrix` needs, and it is a mapping with a single `include` key rather than a
+bare list because `matrix:` must be a mapping.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import yaml
+
+
+def select(legs_by_job: dict, event_name: str) -> dict[str, dict]:
+ """The `{"include": [...]}` mapping per job, `pr` stripped, for one event."""
+ subset = event_name == "pull_request"
+ picked: dict[str, dict] = {}
+ for job, legs in legs_by_job.items():
+ if not isinstance(legs, list):
+ raise SystemExit(f"{job}: expected a list of legs, got {type(legs).__name__}")
+ include = []
+ for leg in legs:
+ if not isinstance(leg, dict) or "pr" not in leg:
+ raise SystemExit(f"{job}: every leg needs a `pr` flag: {leg!r}")
+ if subset and not leg["pr"]:
+ continue
+ include.append({k: v for k, v in leg.items() if k != "pr"})
+ picked[job] = {"include": include}
+ return picked
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description = __doc__.splitlines()[0])
+ parser.add_argument("--file", required = True, type = Path, help = "the matrix file")
+ parser.add_argument("--event", required = True, help = "github.event_name")
+ args = parser.parse_args(argv)
+ legs_by_job = yaml.safe_load(args.file.read_text(encoding = "utf-8"))
+ if not isinstance(legs_by_job, dict):
+ raise SystemExit(f"{args.file}: expected a mapping of job -> legs")
+ for job, matrix in select(legs_by_job, args.event).items():
+ # One line per output: a newline inside the JSON would end the value early.
+ print(f"{job}={json.dumps(matrix, separators = (',', ':'))}")
+ # An empty matrix is a workflow error, so an all-nightly job gates on this count.
+ print(f"{job}_count={len(matrix['include'])}")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/.github/workflows/clean-machine-install-ci.yml b/.github/workflows/clean-machine-install-ci.yml
index 8c8893d7ef4..7faa05c7644 100644
--- a/.github/workflows/clean-machine-install-ci.yml
+++ b/.github/workflows/clean-machine-install-ci.yml
@@ -37,6 +37,14 @@
name: Clean machine install
+# The legs live in .github/ci/clean-machine-matrix.yml, each with a `pr` flag: a
+# pull_request runs the `pr: true` subset (8 of 20), while the nightly schedule, a push to
+# main and workflow_dispatch run all 20, picked by the `select` job below, so a leg's keys
+# are the same on both paths. Installers only: pyproject.toml and requirements/** were
+# dropped from the trigger because they are the two highest-churn files in the repo and
+# every push touching them queued 20 jobs, 7 on the five-slot macOS pool. The nightly keeps
+# that coverage, and the Update, Backend and Core workflows install this ref anyway.
+
on:
pull_request:
paths:
@@ -44,22 +52,18 @@ on:
- 'install.ps1'
- 'studio/setup.sh'
- 'studio/setup.ps1'
+ - 'studio/setup.bat'
- 'studio/install_python_stack.py'
# setup.sh (727) and setup.ps1 (2343, 3630, 3916) call these directly and the
# overlay makes them THIS ref's code, so they decide whether a clean machine gets
# a native prebuilt or a toolchain-dependent fallback.
- 'studio/install_*_prebuilt.py'
- 'studio/prebuilt_core.py'
+ - 'studio/install_manifest.py'
- 'studio/node_prebuilt_pins.json'
- # The overlay exists so a constraints or requirements change is exercised here
- # (see the header). update-smoke cannot stand in: it starts from a preinstalled
- # Python and full developer tooling.
- - 'studio/backend/requirements/**'
- # The overlay builds pyproject.toml and then reaches setup.sh / setup.ps1 through
- # unsloth_cli/commands/studio.py (install.sh:4254, install.ps1:2801), so a change
- # to either decides whether these legs install at all. No toolchain-equipped
- # workflow covers that.
- - 'pyproject.toml'
+ # The overlay reaches setup.sh / setup.ps1 through unsloth_cli/commands/studio.py
+ # (install.sh:4254, install.ps1:2801), so a change there decides whether these
+ # legs install at all. No toolchain-equipped workflow covers that.
- 'unsloth_cli/commands/studio.py'
- '.github/scripts/clean-machine-*.sh'
- '.github/scripts/assert-llama-loads.sh'
@@ -67,6 +71,8 @@ on:
- '.github/scripts/virgin-windows-*.ps1'
- '.github/scripts/ensure-docker-daemon.ps1'
- '.github/scripts/assert-nobuild.ps1'
+ - '.github/scripts/select_install_matrix.py'
+ - '.github/ci/clean-machine-matrix.yml'
- '.github/workflows/clean-machine-install-ci.yml'
push:
branches: [main]
@@ -77,19 +83,25 @@ on:
- 'install.ps1'
- 'studio/setup.sh'
- 'studio/setup.ps1'
+ - 'studio/setup.bat'
- 'studio/install_python_stack.py'
- 'studio/install_*_prebuilt.py'
- 'studio/prebuilt_core.py'
+ - 'studio/install_manifest.py'
- 'studio/node_prebuilt_pins.json'
- - 'studio/backend/requirements/**'
- - 'pyproject.toml'
- 'unsloth_cli/commands/studio.py'
- '.github/scripts/clean-machine-*.sh'
- '.github/scripts/assert-llama-loads.sh'
- '.github/scripts/virgin-windows-*.ps1'
- '.github/scripts/ensure-docker-daemon.ps1'
- '.github/scripts/assert-nobuild.ps1'
+ - '.github/scripts/select_install_matrix.py'
+ - '.github/ci/clean-machine-matrix.yml'
- '.github/workflows/clean-machine-install-ci.yml'
+ schedule:
+ # Nightly, all 20 legs, on this ref's installers: `inputs.installer_source` is empty
+ # on schedule exactly as on pull_request and push, so the tree is under test.
+ - cron: '23 9 * * *'
workflow_dispatch:
inputs:
installer_source:
@@ -99,7 +111,10 @@ on:
default: tree
concurrency:
- group: ${{ github.workflow }}-${{ github.ref }}-${{ github.ref == 'refs/heads/main' && github.sha || '' }}
+ # The event is in the group so a scheduled run and a push to main, which share a ref,
+ # cannot coalesce: only one run stays pending per group, and cancel-in-progress protects
+ # the running run, never the pending one, so a merge burst would drop the nightly.
+ group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}-${{ github.ref == 'refs/heads/main' && github.sha || '' }}
# Latest-only on a PR branch. On main this does less than it reads like: it stops
# a RUNNING main job being killed, but GitHub cancels any PENDING run in the group
# the moment a newer one is queued, so a merge burst still leaves only the tip.
@@ -119,9 +134,47 @@ env:
UNSLOTH_VERBOSE: '1'
jobs:
+ select:
+ name: select legs
+ # arm64, not ubuntu-latest: this job fronts every leg, so its queue wait is added to
+ # all of them, and the arm pool starts in minutes where ubuntu-latest queues for hours.
+ runs-on: ubuntu-24.04-arm
+ timeout-minutes: 5
+ outputs:
+ macos: ${{ steps.pick.outputs.macos }}
+ linux: ${{ steps.pick.outputs.linux }}
+ windows: ${{ steps.pick.outputs.windows }}
+ windows_container_install: ${{ steps.pick.outputs.windows_container_install }}
+ # The consumer container leg is nightly-only, and an empty matrix is a workflow error
+ # rather than an empty job, so the probe and the install both gate on this count.
+ windows_container_install_count: ${{ steps.pick.outputs.windows_container_install_count }}
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: '3.12'
+
+ # Pinned to the PyYAML the workflow guards run under, so the file parses the same
+ # way here as in tests/studio/test_install_matrix_selection.py.
+ - name: Install PyYAML
+ run: pip install pyyaml==6.0.2
+
+ - name: Pick the legs for this event
+ id: pick
+ env:
+ MATRIX_FILE: .github/ci/clean-machine-matrix.yml
+ EVENT_NAME: ${{ github.event_name }}
+ run: |
+ python3 .github/scripts/select_install_matrix.py \
+ --file "$MATRIX_FILE" --event "$EVENT_NAME" | tee -a "$GITHUB_OUTPUT"
+
# ── macOS: the reported failure ────────────────────────────────────────────
macos:
name: mac ${{ matrix.os }} / ${{ matrix.mode }} / ${{ matrix.delivery }}${{ matrix.flags && format(' {0}', matrix.flags) || '' }}
+ needs: select
runs-on: ${{ matrix.os }}
timeout-minutes: 40
continue-on-error: ${{ matrix.experimental }}
@@ -132,32 +185,11 @@ jobs:
UV_CACHE_DIR: ${{ github.workspace }}/.clean-machine/uv-cache
UV_PYTHON_INSTALL_DIR: ${{ github.workspace }}/.clean-machine/uv-python
# Explicit legs, not a full cross-product: the interesting dimensions are (does
- # the toolchain exist) x (how the script is delivered), not every pairing.
+ # the toolchain exist) x (how the script is delivered), not every pairing. The legs
+ # themselves are in .github/ci/clean-machine-matrix.yml.
strategy:
fail-fast: false
- matrix:
- include:
- # `overlay` decides whether this ref's Python is under test at all; see the
- # header. The pipe legs stay on the released package on purpose.
- #
- # The reported failure, in the shape users run it, with torch because that is
- # what a consumer gets.
- - {os: macos-15, mode: mask, delivery: pipe, flags: '', experimental: false, overlay: false}
- - {os: macos-15, mode: mask, delivery: file, flags: '', experimental: false, overlay: true}
- # What the desktop app runs: no tty, stdin closed, TAURI markers on.
- - {os: macos-15, mode: mask, delivery: tauri, flags: '', experimental: false, overlay: true}
- # Toolchain present but logged: uv may make exactly one kind of developer-tool
- # call, its managed-libpython self-ID patch. No overlay: the editable build calls
- # git itself (setuptools-scm), planting evidence unrelated to the consumer path.
- - {os: macos-15, mode: trace, delivery: file, flags: '', experimental: false, overlay: false}
- # --no-torch is the one macOS path that can still want a compiler
- # (sentencepiece has no guaranteed cp313 arm64 wheel), so probe it apart from
- # the default path rather than let it hide the gate under test.
- - {os: macos-15, mode: mask, delivery: file, flags: '--no-torch', experimental: true, overlay: true}
- - {os: macos-26, mode: mask, delivery: file, flags: '', experimental: true, overlay: true}
- # Intel pins python 3.12 and its /usr/bin/git is not CLT-provided, so it
- # survives masking. Informational only.
- - {os: macos-15-intel, mode: mask, delivery: file, flags: '', experimental: true, overlay: true, allow_working: 'git'}
+ matrix: ${{ fromJSON(needs.select.outputs.macos) }}
steps:
# checkout FIRST: it needs a working git, which masking then takes away.
@@ -433,6 +465,7 @@ jobs:
# ── Linux: genuinely clean, via containers ────────────────────────────────
linux:
name: linux ${{ matrix.label }}
+ needs: select
runs-on: ${{ matrix.runner }}
container: ${{ matrix.image }}
timeout-minutes: 40
@@ -444,76 +477,7 @@ jobs:
shell: bash
strategy:
fail-fast: false
- matrix:
- include:
- # Root + apt: install.sh's _smart_apt_install should self-heal from a base
- # image with no curl, git, gcc or cmake at all.
- - label: ubuntu2404-root
- image: ubuntu:24.04
- runner: ubuntu-latest
- experimental: false
- overlay: true
- - label: ubuntu2404-arm-root
- image: ubuntu:24.04
- runner: ubuntu-24.04-arm
- experimental: false
- overlay: true
- # No elevation, but WITH the transport the advertised one-liner needs: not
- # root, no sudo anywhere on the image, no toolchain, ca-certificates + curl and
- # nothing else. Since #7547 the optional set (cmake, git, build-essential,
- # libcurl4-openssl-dev) never escalates, so this must install end to end off
- # prebuilt llama.cpp, and until now nothing proved it.
- #
- # Gating, and overlay: true for the reason fedora41 is: the RELEASED
- # install_python_stack.py has no "skip triton kernels when git is missing"
- # guard, so without the overlay the run reaches the final step and dies there
- # on pure release lag (staging run 30421021166: venv, frontend, torch and
- # extras all fine, then `Installing triton kernels (pip) failed`).
- - label: ubuntu2404-nonroot
- image: ubuntu:24.04
- runner: ubuntu-latest
- experimental: false
- overlay: true
- nonroot: true
- # The same premise with the OTHER transport. install.sh's download() prefers
- # curl and falls back to wget (729-738), _http_get does the same for the
- # connectivity probe (1019-1027), the Radeon listing repeats it (3064-3067),
- # and _check_linux_deps calls the transport missing only when BOTH are gone
- # (2077-2079). So a box with wget and no curl -- a Debian netinst default, and
- # every image where curl was deliberately removed -- is supported on paper and
- # had never been run: the nonroot row above provisions ca-certificates AND
- # curl, so curl won every probe and the wget branch was only ever reasoned from
- # the code. This row asserts everything that one does, plus curl proved absent
- # for the whole run rather than merely unused.
- - label: ubuntu2404-nonroot-wget
- image: ubuntu:24.04
- runner: ubuntu-latest
- experimental: false
- overlay: true
- nonroot: true
- wget_only: true
- # No elevation AND no transport. apt is the only way to get curl and reaching
- # apt needs elevation, so failing is correct; the point is to pin the exact
- # message and prove it is actionable rather than a bare `curl: (56)`. No
- # overlay: it never reaches a venv to overlay into.
- - label: ubuntu2404-nonroot-notransport
- image: ubuntu:24.04
- runner: ubuntu-latest
- experimental: false
- overlay: false
- nonroot: true
- no_transport: true
- # Non-apt: today this hard-fails at install.sh:2034. Expected; forces the
- # decision on whether dnf/pacman/zypper get supported. Tolerate the install
- # step, not the job, exactly as the no-transport row does: job-level
- # continue-on-error would swallow the outcome assertion too, leaving it
- # unable to fail the run.
- - label: fedora41
- image: fedora:41
- runner: ubuntu-latest
- experimental: false
- overlay: true
- tolerate_install_failure: true
+ matrix: ${{ fromJSON(needs.select.outputs.linux) }}
steps:
- name: Describe the container's starting state
@@ -939,8 +903,12 @@ jobs:
# Gating, deliberately: the only job that runs the real WSL branch, and the only one that
# can catch a piped install being truncated (WSL shells out to Windows interop mid-script
# and interop relays the stdin it inherited). #7548 is in main, so nothing to absorb.
+ #
+ # Off pull_request: a 50-minute windows-latest slot per push is too much for a branch
+ # that changes rarely. Not a matrix job, so it gates here, not in the matrix file.
wsl:
name: wsl ubuntu-24.04
+ if: github.event_name != 'pull_request'
runs-on: windows-latest
timeout-minutes: 50
@@ -1065,41 +1033,13 @@ jobs:
# ── Windows ───────────────────────────────────────────────────────────────
windows:
name: win ${{ matrix.os }} / winget=${{ matrix.winget }}
+ needs: select
runs-on: ${{ matrix.os }}
timeout-minutes: 45
continue-on-error: ${{ matrix.experimental }}
strategy:
fail-fast: false
- matrix:
- include:
- - os: windows-latest
- winget: 'visible'
- experimental: false
- overlay: true
- # The no-winget path (LTSC / Server / managed corporate machines) falls back to
- # python.org + astral.sh and is untested today. It is also where Ensure-VCRedist
- # silently does not run, leaving torch unable to load, hence the explicit
- # `import torch` assert below. It used to stop at setup.ps1's unconditional "Git
- # is required but could not be installed automatically" gate -- no winget, no way
- # to fetch git -- and was a pinned known failure until #7549 relaxed that gate to
- # the --local and llama.cpp source paths that really use git (setup.ps1:1750-1759).
- # The row now gates like any other; the assert below proves it took the relaxed
- # branch rather than passing on git leaking back onto PATH.
- - os: windows-latest
- winget: 'masked'
- experimental: false
- overlay: true
- # Windows on ARM gets a native ARM64 CPython, and torchaudio has never published a
- # win_arm64 wheel (nor have pyarrow and hf-transfer, which datasets pulls in), so
- # the PyTorch step could not resolve and install.ps1 stopped at "Failed to install
- # PyTorch". Pinned until #7549 made the installer prefer an x64 interpreter on an
- # ARM64 host and bootstrap one when only ARM64 exists (install.ps1:1160-1253,
- # 1335-1353); x64 wheels run fine emulated. The row now gates, and the assert
- # below checks the outcome that fix must produce, not the log line announcing it.
- - os: windows-11-arm
- winget: 'visible'
- experimental: false
- overlay: true
+ matrix: ${{ fromJSON(needs.select.outputs.windows) }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -1467,6 +1407,9 @@ jobs:
# and caches no Windows images).
windows_container_probe:
name: virgin win container / probe
+ needs: select
+ # Only a gate for the install rows: skipped with them when none is selected.
+ if: needs.select.outputs.windows_container_install_count != '0'
runs-on: windows-2022
timeout-minutes: 30
env:
@@ -1544,24 +1487,15 @@ jobs:
windows_container_install:
name: virgin win container / overlay=${{ matrix.overlay }}
- needs: windows_container_probe
+ needs: [select, windows_container_probe]
+ if: needs.select.outputs.windows_container_install_count != '0'
runs-on: windows-2022
timeout-minutes: 90
env:
IMAGE: mcr.microsoft.com/windows/servercore:ltsc2022
strategy:
fail-fast: false
- matrix:
- include:
- # The consumer path: install.ps1 from this ref, unsloth from PyPI, so
- # studio/setup.ps1 comes out of the RELEASED wheel rather than this ref's. That is
- # the difference from the overlay row below; both are expected to install end to
- # end and both gate.
- - overlay: false
- # This ref's studio/setup.ps1 and install_python_stack.py, via
- # UNSLOTH_CI_SOURCE_OVERLAY (install.ps1:2643). Without it a branch changing
- # setup.ps1 gets a green run proving nothing about the change.
- - overlay: true
+ matrix: ${{ fromJSON(needs.select.outputs.windows_container_install) }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
diff --git a/.github/workflows/interrupted-install-ci.yml b/.github/workflows/interrupted-install-ci.yml
index 523468373ed..974b9514546 100644
--- a/.github/workflows/interrupted-install-ci.yml
+++ b/.github/workflows/interrupted-install-ci.yml
@@ -16,6 +16,15 @@
name: Interrupted install recovery
+# The legs live in .github/ci/interrupted-install-matrix.yml, each with a `pr` flag: a
+# pull_request runs the `pr: true` subset (2 of 10), while a push to main, the nightly
+# schedule and workflow_dispatch run all 10, picked by the `select` job below. 6 of the 10
+# are macOS on an account capped at five concurrent macOS jobs, and on every PR audited
+# before the split the full set was cancelled by the next push before its macOS legs had
+# started. Installers plus the ready/stale predicate the probes call: pyproject.toml and
+# the Tauri preflight sources were dropped because neither is an installer and both change
+# far more often than the kill path does.
+
on:
pull_request:
paths:
@@ -24,16 +33,8 @@ on:
- 'studio/setup.sh'
- 'studio/setup.ps1'
- 'studio/install_python_stack.py'
- - 'studio/src-tauri/src/install.rs'
- - 'studio/src-tauri/src/preflight.rs'
- - 'studio/src-tauri/src/preflight/**'
- 'unsloth_cli/commands/studio.py'
- # Every leg installs the checkout with `--local`, so this file decides the console
- # script and the core deps: `-h` and `desktop-capabilities` only survive a torn
- # install because typer/click/rich are declared here, not in an extra.
- - 'pyproject.toml'
- # studio_install_ok and verify-install, the decisions the probe asserts on, live here,
- # so an install_state() accepting a missing manifest would merge unrun.
+ # install_state() decides ready vs stale for every probe (commands/studio.py:501).
- 'unsloth_cli/_studio_deps.py'
- 'studio/install_manifest.py'
# The requirement files are the phases: studio.txt declares structlog, whose absence
@@ -45,13 +46,45 @@ on:
- '.github/scripts/interrupt-install.sh'
- '.github/scripts/interrupt-install.ps1'
- '.github/scripts/interrupted_install_probe.py'
+ - '.github/scripts/select_install_matrix.py'
+ - '.github/ci/interrupted-install-matrix.yml'
- '.github/workflows/interrupted-install-ci.yml'
- '.github/scripts/retry-with-apt-lock.sh'
+ # Every push to main that touches an installer runs the full set, so a merge is
+ # covered at merge time and not only by the nightly.
+ push:
+ branches: [main]
+ paths:
+ - 'install.sh'
+ - 'install.ps1'
+ - 'studio/setup.sh'
+ - 'studio/setup.ps1'
+ - 'studio/install_python_stack.py'
+ - 'unsloth_cli/commands/studio.py'
+ # install_state() decides ready vs stale for every probe (commands/studio.py:501).
+ - 'unsloth_cli/_studio_deps.py'
+ - 'studio/install_manifest.py'
+ - 'studio/backend/requirements/**'
+ - '.github/scripts/interrupt-install.sh'
+ - '.github/scripts/interrupt-install.ps1'
+ - '.github/scripts/interrupted_install_probe.py'
+ - '.github/scripts/select_install_matrix.py'
+ - '.github/ci/interrupted-install-matrix.yml'
+ - '.github/workflows/interrupted-install-ci.yml'
+ - '.github/scripts/retry-with-apt-lock.sh'
+ schedule:
+ # Nightly, all 10 legs. Offset from clean-machine-install-ci.yml's 09:23 so the two
+ # do not race for the five macOS slots.
+ - cron: '41 10 * * *'
workflow_dispatch:
concurrency:
- group: ${{ github.workflow }}-${{ github.ref }}
- cancel-in-progress: true
+ # The event is in the group so a scheduled run and a push to main, which share a ref,
+ # cannot cancel each other; the sha makes it unique per commit on main so a merge burst
+ # cannot cancel a pending run (see studio-backend-ci.yml). On a PR branch the group is
+ # the ref, so a new push cancels the run for the previous one.
+ group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}-${{ github.ref == 'refs/heads/main' && github.sha || '' }}
+ cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
permissions:
contents: read
@@ -60,9 +93,45 @@ env:
UNSLOTH_STUDIO_DISABLE_PUBLIC_CHECK: '1'
jobs:
+ select:
+ name: select legs
+ # arm64, not ubuntu-latest: this job fronts every leg, so its queue wait is added to
+ # all of them, and the arm pool starts in minutes where ubuntu-latest queues for hours.
+ runs-on: ubuntu-24.04-arm
+ timeout-minutes: 5
+ outputs:
+ interrupt: ${{ steps.pick.outputs.interrupt }}
+ interrupt_windows: ${{ steps.pick.outputs.interrupt_windows }}
+ # Both Windows legs are nightly-only, and an empty matrix is a workflow error rather
+ # than an empty job, so the Windows job gates on this count.
+ interrupt_windows_count: ${{ steps.pick.outputs.interrupt_windows_count }}
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: '3.12'
+
+ # Pinned to the PyYAML the workflow guards run under, so the file parses the same way
+ # here as in tests/studio/test_install_matrix_selection.py.
+ - name: Install PyYAML
+ run: pip install pyyaml==6.0.2
+
+ - name: Pick the legs for this event
+ id: pick
+ env:
+ MATRIX_FILE: .github/ci/interrupted-install-matrix.yml
+ EVENT_NAME: ${{ github.event_name }}
+ run: |
+ python3 .github/scripts/select_install_matrix.py \
+ --file "$MATRIX_FILE" --event "$EVENT_NAME" | tee -a "$GITHUB_OUTPUT"
+
# ── macOS + Linux: kill at each phase ─────────────────────────────────────
interrupt:
name: ${{ matrix.os }} kill@${{ matrix.label }}
+ needs: select
runs-on: ${{ matrix.os }}
# Above the deadlines this leg actually configures, or a slow runner is cancelled
# mid-assertion and the leg proves nothing: 25 min to the marker
@@ -70,46 +139,10 @@ jobs:
# --help checks, two 300s deep checks, a 300s backend wait) around a repair
# install. Legs land in 6-10 min in practice; this is the ceiling, not the target.
timeout-minutes: 90
+ # The legs are in .github/ci/interrupted-install-matrix.yml; every one is a hard gate.
strategy:
fail-fast: false
- matrix:
- include:
- # Only a marker: the driver signals the moment that line appears, and no leg waits
- # first. Every label prints BEFORE its work, so the kill is inside the phase at
- # detection, and a delay only bets on how long the phase runs. The bet lost twice,
- # both times turning a leg into a duplicate of the next one: a flat 3s wait moved
- # 5 of the 12 legs of staging run 30419729244, and in 30426111484 it carried the
- # macOS torch leg into "Installing Unsloth" because the PyTorch step, called
- # minutes long here, finished in under three seconds.
- #
- # Every leg is a hard gate, with no continue-on-error cell: a leg allowed to fail
- # is a warning wearing a red icon, and this workflow's whole claim is that a
- # killed install cannot report itself healthy.
- #
- # The exact reported case: killed during the sub-step that installs structlog.
- - {os: macos-15, label: studio-deps, marker: 'studio deps'}
- # Coarse phases, earliest to latest -- each leaves a different partial venv.
- # No venv cell: "Creating virtual environment" ran 0.107s in staging run
- # 30419729244 (03:31:07.371 -> 07.478 to "Installing PyTorch"), shorter than any
- # poll watching the log, so the kill landed in the NEXT phase every time it was
- # tried (30423181897 and 30424366953 both) and the leg was the torch leg under a
- # different label. Lost with it: a venv caught half-written, not reachable by
- # interruption at this resolution, and the only loss -- the torch leg lands at the
- # top of the PyTorch step, so it leaves a complete venv with nothing in it.
- - {os: macos-15, label: torch, marker: '\[TAURI:STEP\] Installing PyTorch'}
- - {os: macos-15, label: unsloth, marker: '\[TAURI:STEP\] Installing Unsloth'}
- - {os: macos-15, label: setup, marker: '\[TAURI:STEP\] Running Unsloth setup'}
- # Other dependency-pass sub-steps around the named one. No pip-bootstrap cell, same
- # reason as venv: "1/10 pip bootstrap" is over before a poll can see it, so in both
- # 30419729244 and 30424366953 the signal landed in "2/10 unsloth extras", the next
- # cell down. No base-packages cell either: --local sets skip_base, so
- # install_python_stack returns before "base packages" prints and that leg ran to
- # completion, proving nothing.
- - {os: macos-15, label: unsloth-extras, marker: 'unsloth extras'}
- - {os: macos-15, label: data-designer, marker: 'data designer deps'}
- # Linux: same teardown path, different package manager and process semantics.
- - {os: ubuntu-latest, label: studio-deps, marker: 'studio deps'}
- - {os: ubuntu-latest, label: torch, marker: '\[TAURI:STEP\] Installing PyTorch'}
+ matrix: ${{ fromJSON(needs.select.outputs.interrupt) }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -287,16 +320,13 @@ jobs:
# different root resolution, no bundled-file overlay). Worse, "Installing PyTorch" is
# only printed by Write-TauriLog (install.ps1:2440), so the torch leg's marker could
# never appear. The runner is ephemeral, so the default root is safe to install into.
+ needs: select
+ if: needs.select.outputs.interrupt_windows_count != '0'
runs-on: windows-latest
timeout-minutes: 90
strategy:
fail-fast: false
- matrix:
- include:
- # install.ps1:121 parses `--no-torch`; `-SkipTorch` matches no case there and is
- # silently dropped. The torch leg must NOT skip torch or its marker never appears.
- - {label: studio-deps, marker: 'studio deps', installArgs: '--tauri --no-torch --local'}
- - {label: torch, marker: 'Installing PyTorch', installArgs: '--tauri --local'}
+ matrix: ${{ fromJSON(needs.select.outputs.interrupt_windows) }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
diff --git a/.github/workflows/local-agent-guides-ci.yml b/.github/workflows/local-agent-guides-ci.yml
index 871026a7bfb..035ab6dc027 100644
--- a/.github/workflows/local-agent-guides-ci.yml
+++ b/.github/workflows/local-agent-guides-ci.yml
@@ -47,8 +47,14 @@ on:
push:
branches: [main]
paths:
- - 'unsloth_cli/**'
- - 'studio/backend/routes/**'
+ # The import closure of `unsloth run` (studio.py:31-33, __init__.py:70-77) plus the
+ # recipe files at the package root; only unsloth_cli/tests/** is left out.
+ - 'unsloth_cli/*'
+ - 'unsloth_cli/commands/*.py'
+ # inference.py declares every endpoint the preflight curls (/v1/models,
+ # /v1/chat/completions, /v1/messages, /v1/responses); routes/** made the other
+ # twenty route modules pay the full matrix for edits never requested here.
+ - 'studio/backend/routes/inference.py'
- 'studio/backend/main.py'
- 'studio/backend/core/inference/llama_cpp.py'
- 'studio/backend/models/**'
@@ -58,22 +64,25 @@ on:
# The install step in this workflow is `uses:` on that composite action,
# so an edit to the action changes what this workflow actually runs.
- '.github/actions/install-unsloth-local/action.yml'
- # The dist cache moved out of install-unsloth-local so the Windows jobs could
- # share one definition of its key; a change to it still has to re-run the jobs
- # that depend on it.
+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.
- '.github/actions/frontend-dist-restore/action.yml'
- '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
- '.github/scripts/serve-unsloth-run.sh'
- '.github/scripts/assert-prompt-cache.sh'
- '.github/scripts/agent-guides-install.sh'
- '.github/scripts/agent-guides-drive.sh'
+ # Every GGUF download in every job goes through it.
+ - '.github/scripts/hf-download-with-retry.sh'
- '.github/scripts/ci-connect-prompt.txt'
- '.github/scripts/ci-min-system-prompt.txt'
pull_request:
paths:
- - 'unsloth_cli/**'
- - 'studio/backend/routes/**'
- # Contracts this workflow asserts that live outside routes/**: the
+ - 'unsloth_cli/*'
+ - 'unsloth_cli/commands/*.py'
+ - 'studio/backend/routes/inference.py'
+ # Contracts this workflow asserts that live outside routes/: the
# /api/health endpoint, the llama-server KV-cache log behavior, and the
# request/response schemas the agent dialects depend on.
- 'studio/backend/main.py'
@@ -83,15 +92,16 @@ on:
- '.github/workflows/local-agent-guides-ci.yml'
- '.github/scripts/retry-with-apt-lock.sh'
- '.github/actions/install-unsloth-local/action.yml'
- # The dist cache moved out of install-unsloth-local so the Windows jobs could
- # share one definition of its key; a change to it still has to re-run the jobs
- # that depend on it.
+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.
- '.github/actions/frontend-dist-restore/action.yml'
- '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
- '.github/scripts/serve-unsloth-run.sh'
- '.github/scripts/assert-prompt-cache.sh'
- '.github/scripts/agent-guides-install.sh'
- '.github/scripts/agent-guides-drive.sh'
+ - '.github/scripts/hf-download-with-retry.sh'
- '.github/scripts/ci-connect-prompt.txt'
- '.github/scripts/ci-min-system-prompt.txt'
diff --git a/.github/workflows/startup-profile-ci.yml b/.github/workflows/startup-profile-ci.yml
index 5fa3af2a52f..9084c33be99 100644
--- a/.github/workflows/startup-profile-ci.yml
+++ b/.github/workflows/startup-profile-ci.yml
@@ -55,6 +55,8 @@ on:
- 'install.ps1'
- '.github/actions/frontend-dist-restore/action.yml'
- '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
- 'pyproject.toml'
# --local also runs the checkout's setup scripts (install.sh picks
# $_REPO_ROOT/studio/setup.sh, the editable install resolves setup.ps1 to the
@@ -128,6 +130,12 @@ jobs:
# tests/studio/test_frontend_dist_cache.py derives this from the `on:` block rather
# than allowlisting the filename, so adding `push:` here without adding the save --
# or adding the save without the trigger -- goes red.
+ # The uv download cache the producers fill on main. No push and no schedule here,
+ # so this workflow only ever consumes it (as the dist restore below argues).
+ - name: Restore the uv download cache
+ id: uv-cache
+ uses: ./.github/actions/uv-cache-restore
+
- name: Restore the built frontend
id: fe-dist
uses: ./.github/actions/frontend-dist-restore
@@ -159,6 +167,14 @@ jobs:
key: ${{ steps.fe-dist.outputs.key }}
save: 'false'
+ # No upload, for the reason the dist save above gives: nothing here runs on main.
+ - name: Declare this job a uv cache consumer, not a producer
+ uses: ./.github/actions/uv-cache-save
+ with:
+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}
+ key: ${{ steps.uv-cache.outputs.key }}
+ save: 'false'
+
- name: Profile startup
shell: bash
run: |
diff --git a/.github/workflows/studio-api-smoke.yml b/.github/workflows/studio-api-smoke.yml
index ad2fb97aaae..7984aea5d93 100644
--- a/.github/workflows/studio-api-smoke.yml
+++ b/.github/workflows/studio-api-smoke.yml
@@ -20,12 +20,24 @@ name: Unsloth API CI
on:
pull_request:
paths:
- - 'studio/**'
- - 'unsloth/**'
+ # What the test boots: the FastAPI backend, the installer that lays it down and
+ # the CLI that launches it. Not studio/** plus unsloth/**, which fired the job for
+ # edits it cannot observe: the install is --no-torch, so nothing under unsloth/**
+ # is importable here, the frontend is built but never served (UNSLOTH_API_ONLY),
+ # and src-tauri never enters the picture.
+ - 'studio/backend/**'
+ - 'studio/setup.sh'
+ - 'studio/install_*.py'
+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).
+ - 'studio/node_prebuilt_pins.json'
+ - 'studio/prebuilt_core.py'
+ - 'studio/install_manifest.py'
- 'unsloth_cli/**'
- 'install.sh'
- 'pyproject.toml'
- - 'tests/studio/**'
+ # Named, not globbed: the rest of tests/studio is Playwright drivers this
+ # workflow never runs.
+ - 'tests/studio/studio_api_smoke.py'
- '.github/workflows/studio-api-smoke.yml'
- '.github/scripts/retry-with-apt-lock.sh'
# Every server boot in this workflow shells out to that script, so an edit
@@ -33,14 +45,16 @@ on:
- '.github/scripts/boot-studio-api-only.sh'
# Same for the /api/health wait that runs after a boot.
- '.github/scripts/wait-for-health.sh'
+ # And for the GGUF download that primes HF_HOME.
+ - '.github/scripts/hf-download-with-retry.sh'
# The install step in this workflow is `uses:` on that composite action,
# so an edit to the action changes what this workflow actually runs.
- '.github/actions/install-unsloth-local/action.yml'
- # The dist cache moved out of install-unsloth-local so the Windows jobs could
- # share one definition of its key; a change to it still has to re-run the jobs
- # that depend on it.
+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.
- '.github/actions/frontend-dist-restore/action.yml'
- '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
push:
branches: [main]
workflow_dispatch:
diff --git a/.github/workflows/studio-inference-smoke.yml b/.github/workflows/studio-inference-smoke.yml
index 9acf500645a..5f0c4aa8214 100644
--- a/.github/workflows/studio-inference-smoke.yml
+++ b/.github/workflows/studio-inference-smoke.yml
@@ -35,8 +35,18 @@ name: Unsloth GGUF CI
on:
pull_request:
paths:
- - 'studio/**'
- - 'unsloth/**'
+ # What the three phases exercise: the backend's OpenAI and Anthropic surfaces over
+ # a llama.cpp prebuilt, the installer that lays them down and the CLI that boots
+ # them. Not studio/** plus unsloth/**: the install is --no-torch so the training
+ # library is not importable here, the frontend is never served (UNSLOTH_API_ONLY),
+ # and src-tauri is never touched.
+ - 'studio/backend/**'
+ - 'studio/setup.sh'
+ - 'studio/install_*.py'
+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).
+ - 'studio/node_prebuilt_pins.json'
+ - 'studio/prebuilt_core.py'
+ - 'studio/install_manifest.py'
- 'unsloth_cli/**'
- 'install.sh'
- 'pyproject.toml'
@@ -47,14 +57,18 @@ on:
- '.github/scripts/boot-studio-api-only.sh'
# Same for the /api/health wait that runs after a boot.
- '.github/scripts/wait-for-health.sh'
+ # Every model download in every phase goes through it.
+ - '.github/scripts/hf-download-with-retry.sh'
+ # Phase 1 drives both SDKs through this script.
+ - '.github/scripts/studio_smoke/multi_turn_chat.py'
# The install step in this workflow is `uses:` on that composite action,
# so an edit to the action changes what this workflow actually runs.
- '.github/actions/install-unsloth-local/action.yml'
- # The dist cache moved out of install-unsloth-local so the Windows jobs could
- # share one definition of its key; a change to it still has to re-run the jobs
- # that depend on it.
+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.
- '.github/actions/frontend-dist-restore/action.yml'
- '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
push:
branches: [main]
# Manual trigger for pre-warming HF_HOME caches on main, or re-running
diff --git a/.github/workflows/studio-mac-install-matrix.yml b/.github/workflows/studio-mac-install-matrix.yml
index 0ef6e88bd30..2f8e817be37 100644
--- a/.github/workflows/studio-mac-install-matrix.yml
+++ b/.github/workflows/studio-mac-install-matrix.yml
@@ -19,6 +19,9 @@ on:
# The install step in this workflow is `uses:` on that composite action,
# so an edit to the action changes what this workflow actually runs.
- '.github/actions/install-unsloth-local/action.yml'
+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
# The dist cache moved out of install-unsloth-local so the Windows jobs could
# share one definition of its key; a change to it still has to re-run the jobs
# that depend on it.
@@ -55,6 +58,9 @@ on:
# The install step in this workflow is `uses:` on that composite action,
# so an edit to the action changes what this workflow actually runs.
- '.github/actions/install-unsloth-local/action.yml'
+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
# The dist cache moved out of install-unsloth-local so the Windows jobs could
# share one definition of its key; a change to it still has to re-run the jobs
# that depend on it.
diff --git a/.github/workflows/studio-mac-ui-smoke.yml b/.github/workflows/studio-mac-ui-smoke.yml
index 32804639c57..68235a247f8 100644
--- a/.github/workflows/studio-mac-ui-smoke.yml
+++ b/.github/workflows/studio-mac-ui-smoke.yml
@@ -27,11 +27,22 @@ name: Mac Unsloth UI + API + Update + Inference CI
on:
pull_request:
paths:
- - 'studio/**'
- - 'unsloth/**'
+ # The two halves Playwright drives, the backend and the React bundle, plus the
+ # installer and CLI that put them on the box. Not studio/** and unsloth/**: the
+ # install is --no-torch, so unsloth/** cannot reach the venv under test, and
+ # studio/src-tauri is never built here, and this pool is capped at five jobs.
+ - 'studio/backend/**'
+ - 'studio/frontend/**'
+ - 'studio/setup.sh'
+ - 'studio/install_*.py'
+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).
+ - 'studio/node_prebuilt_pins.json'
+ - 'studio/prebuilt_core.py'
+ - 'studio/install_manifest.py'
- 'unsloth_cli/**'
- 'install.sh'
- 'pyproject.toml'
+ # The Playwright drivers and studio_api_smoke.py the phases run.
- 'tests/studio/**'
- '.github/scripts/run-studio-permission-browser.sh'
- '.github/scripts/run-studio-indicator-browser.sh'
@@ -45,17 +56,14 @@ on:
# The install step in this workflow is `uses:` on that composite action,
# so an edit to the action changes what this workflow actually runs.
- '.github/actions/install-unsloth-local/action.yml'
- # The dist cache moved out of install-unsloth-local so the Windows jobs could
- # share one definition of its key; a change to it still has to re-run the jobs
- # that depend on it.
+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.
- '.github/actions/frontend-dist-restore/action.yml'
- '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
# The absorbed update phase round-trips scripts/uninstall.sh, which none
# of the entries above cover.
- 'scripts/uninstall.sh'
- # No new entries needed for the absorbed API phase: every path
- # studio-mac-api-smoke.yml watched is already covered above, and
- # tests/studio/** covers studio_api_smoke.py itself.
# Executed directly by this workflow: the load assertion and every model
# download.
- '.github/scripts/assert-llama-loads.sh'
@@ -73,8 +81,14 @@ on:
# this workflow tests has nothing here to back up.
# clean-machine-install-ci.yml and mlx-ci.yml already do exactly this.
paths:
- - 'studio/**'
- - 'unsloth/**'
+ - 'studio/backend/**'
+ - 'studio/frontend/**'
+ - 'studio/setup.sh'
+ - 'studio/install_*.py'
+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).
+ - 'studio/node_prebuilt_pins.json'
+ - 'studio/prebuilt_core.py'
+ - 'studio/install_manifest.py'
- 'unsloth_cli/**'
- 'install.sh'
- 'pyproject.toml'
@@ -91,17 +105,14 @@ on:
# The install step in this workflow is `uses:` on that composite action,
# so an edit to the action changes what this workflow actually runs.
- '.github/actions/install-unsloth-local/action.yml'
- # The dist cache moved out of install-unsloth-local so the Windows jobs could
- # share one definition of its key; a change to it still has to re-run the jobs
- # that depend on it.
+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.
- '.github/actions/frontend-dist-restore/action.yml'
- '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
# The absorbed update phase round-trips scripts/uninstall.sh, which none
# of the entries above cover.
- 'scripts/uninstall.sh'
- # No new entries needed for the absorbed API phase: every path
- # studio-mac-api-smoke.yml watched is already covered above, and
- # tests/studio/** covers studio_api_smoke.py itself.
# Executed directly by this workflow: the load assertion and every model
# download.
- '.github/scripts/assert-llama-loads.sh'
diff --git a/.github/workflows/studio-ui-smoke.yml b/.github/workflows/studio-ui-smoke.yml
index 32db4d3075f..b52b8ffeeef 100644
--- a/.github/workflows/studio-ui-smoke.yml
+++ b/.github/workflows/studio-ui-smoke.yml
@@ -19,13 +19,24 @@ name: Unsloth UI CI
on:
pull_request:
paths:
- - 'studio/**'
- - 'unsloth/**'
+ # The two halves Playwright drives, the backend and the React bundle, plus the
+ # installer and CLI that put them on the box. Not studio/** and unsloth/**: the
+ # install is --no-torch, so unsloth/** cannot reach the venv under test, and
+ # studio/src-tauri is never built here.
+ - 'studio/backend/**'
+ - 'studio/frontend/**'
+ - 'studio/setup.sh'
+ - 'studio/install_*.py'
+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).
+ - 'studio/node_prebuilt_pins.json'
+ - 'studio/prebuilt_core.py'
+ - 'studio/install_manifest.py'
- 'unsloth_cli/**'
- 'install.sh'
- 'pyproject.toml'
# The Playwright test files themselves -- a PR that ONLY edits
- # the test must still trigger UI CI.
+ # the test must still trigger UI CI. Kept as a directory glob, which
+ # test_stt_model_search_locator_contract.py asserts.
- 'tests/studio/**'
- '.github/scripts/run-studio-permission-browser.sh'
- '.github/scripts/run-studio-indicator-browser.sh'
@@ -35,17 +46,19 @@ on:
- '.github/scripts/boot-studio-api-only.sh'
# Same for the /api/health wait that runs after a boot.
- '.github/scripts/wait-for-health.sh'
+ # And for the GGUF download that primes HF_HOME in every shard.
+ - '.github/scripts/hf-download-with-retry.sh'
# Both apt steps in this workflow shell out to it, so an edit to it changes
# what this workflow actually runs.
- '.github/scripts/retry-with-apt-lock.sh'
# The install step in this workflow is `uses:` on that composite action,
# so an edit to the action changes what this workflow actually runs.
- '.github/actions/install-unsloth-local/action.yml'
- # The dist cache moved out of install-unsloth-local so the Windows jobs could
- # share one definition of its key; a change to it still has to re-run the jobs
- # that depend on it.
+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.
- '.github/actions/frontend-dist-restore/action.yml'
- '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
push:
branches: [main]
workflow_dispatch:
@@ -73,7 +86,7 @@ jobs:
ui-smoke:
name: Chat UI Tests (${{ matrix.shard }})
runs-on: ubuntu-latest
- # Left at 30 even though each shard now carries a quarter of the work.
+ # Left at 30 even though each shard carries about half of the work.
#
# It was briefly cut to 20 on the reasoning that a quarter of the job needs a quarter
# of the budget. Staging then cancelled three shards at 20m0s inside "Linux deps", an
@@ -83,21 +96,22 @@ jobs:
# catch a hang, not to police the mean.
timeout-minutes: 30
strategy:
- # Four shards, split where the job already split itself.
+ # Two shards, split where the job already split itself.
#
# This is 11 Playwright scripts run one after another against four Unsloth instances booted
# one after another, and at 22.1 minutes on average it was the largest job in the
# repo. The setup every shard has to repeat is small -- checkout, Linux deps,
- # Install Unsloth, Playwright browsers, about 2.6 minutes -- so splitting it is
- # nearly all profit in wall-clock, which is the thing being optimised. Runner
- # minutes go up. That is the trade, taken deliberately.
+ # Install Unsloth, Playwright browsers, about 2.6 minutes -- so splitting it was
+ # nearly all profit in wall-clock. Four shards went too far: the queue wait for an
+ # ubuntu-latest runner dwarfs a six-minute shard, so `banner` is folded into `chat`
+ # (both install the three engines) and `picker` into `extra` (both chromium only).
#
# The boundaries are the Unsloth instances, not an even division of scripts: a
# Unsloth boot, its health wait, its bootstrap password and the scripts that drive
# it have to stay on one machine. So `chat` takes 18892 and the cross-browser
- # permission pass, `extra` and `banner` each boot their own 18894 (the two banner
- # engines alone were 7.25 of the 17.6 minutes, which is why they are a shard), and
- # `picker` takes 18898 and 18896, which are small and adjacent.
+ # permission pass, then boots 18894 for the two banner passes once 18892 is down;
+ # `extra` boots its own 18894, then 18898 and 18896 for the picker suites. One
+ # Unsloth at a time on each runner, on its own port.
#
# In-machine parallelism is deliberately NOT used here. These are separate runners,
# so each still boots one Unsloth at a time and nothing competes for RAM.
@@ -106,35 +120,29 @@ jobs:
# The shard list stays a list: test_chat_ui_shards_cover_everything reads it
# to prove every Playwright step lands on some shard, and an include-only
# matrix hides it from that guard.
- shard: [chat, extra, banner, picker]
+ shard: [chat, extra]
# include: entries that match an existing combination ADD fields to it rather
# than creating new jobs, which is how each shard gets the engines it drives
# without changing the shard set.
#
- # `extra` and `picker` name no engine but chromium anywhere in their steps.
- # Installing webkit's system libraries for them is 181 packages and 102 MB of
- # apt, which is what timed this job out on 2026-08-19:
+ # `extra` names no engine but chromium anywhere in its steps. Installing webkit's
+ # system libraries for it is 181 packages and 102 MB of apt, which is what timed
+ # this job out on 2026-08-19:
#
# 0 upgraded, 181 newly installed
# Need to get 102 MB/114 MB of archives
# Get:2 .../fonts-wqy-zenhei [7472 kB] -> 4m51s, then the attempt died
#
- # Fonts, X fonts and a soundfont, fetched so that two shards which never
- # launch webkit could fail to fetch them. test_ui_shard_engines.py keeps this
- # honest against the steps rather than against this comment.
+ # Fonts, X fonts and a soundfont, fetched so that a shard which never launches
+ # webkit could fail to fetch them. test_ui_shard_engines.py keeps this honest
+ # against the steps rather than against this comment.
include:
- - shard: chat # Cross-browser permission controls drives all three
- engines: chromium firefox webkit
- engine_key: cfw
- - shard: banner # "other engines" step drives firefox and webkit
+ - shard: chat # permission controls + banner "other engines" drive all three
engines: chromium firefox webkit
engine_key: cfw
- shard: extra
engines: chromium
engine_key: c
- - shard: picker
- engines: chromium
- engine_key: c
env:
GGUF_REPO: unsloth/gemma-3-270m-it-GGUF
GGUF_VARIANT: UD-Q4_K_XL
@@ -515,19 +523,19 @@ jobs:
# second one on a different port. Boot is fast (~3-5s on the
# warm install we already did) so this adds little wall time.
- name: Reset auth + boot Unsloth for extra UI tests (port 18894)
- if: matrix.shard == 'extra' || matrix.shard == 'banner'
+ if: matrix.shard == 'extra' || matrix.shard == 'chat'
run: |
bash .github/scripts/boot-studio-api-only.sh \
--port 18894 --log logs/studio_extra.log --pid-var STUDIO_EXTRA_PID
- name: Wait for /api/health on 18894
- if: matrix.shard == 'extra' || matrix.shard == 'banner'
+ if: matrix.shard == 'extra' || matrix.shard == 'chat'
run: |
bash .github/scripts/wait-for-health.sh \
--port 18894 --log logs/studio_extra.log --tmp /tmp/health2.json
- name: Pass bootstrap pw for extra UI test
- if: matrix.shard == 'extra' || matrix.shard == 'banner'
+ if: matrix.shard == 'extra' || matrix.shard == 'chat'
run: |
OLD=$(cat ~/.unsloth/studio/auth/.bootstrap_password)
NEW="CIUiExtra-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
@@ -586,7 +594,7 @@ jobs:
python tests/studio/playwright_ui_font_scale.py
- name: Update banner layout regression (Playwright)
- if: matrix.shard == 'banner'
+ if: matrix.shard == 'chat'
env:
BASE_URL: http://127.0.0.1:18894
STUDIO_OLD_PW: ${{ env.STUDIO_EXTRA_OLD_PW }}
@@ -603,7 +611,7 @@ jobs:
# this runner gets to Safari. Cut down to `spot` because a third full
# pass would spend minutes re-answering the first pass's questions.
- name: Update banner layout, other engines (Playwright)
- if: matrix.shard == 'banner'
+ if: matrix.shard == 'chat'
env:
BASE_URL: http://127.0.0.1:18894
STUDIO_OLD_PW: ${{ env.STUDIO_EXTRA_OLD_PW }}
@@ -684,7 +692,7 @@ jobs:
python tests/studio/playwright_declared_polls.py
- name: Stop second Unsloth
- if: (always()) && (matrix.shard == 'extra' || matrix.shard == 'banner')
+ if: (always()) && (matrix.shard == 'extra' || matrix.shard == 'chat')
run: |
kill "${STUDIO_EXTRA_PID}" 2>/dev/null || true
sleep 2
@@ -695,26 +703,26 @@ jobs:
# Reset clears the stored override (never pins it), and the infra models
# (RAG embedder + llama.cpp probe) stay hidden from the picker.
- name: Reset auth + boot Unsloth for model-config tests (port 18898)
- if: matrix.shard == 'picker'
+ if: matrix.shard == 'extra'
run: |
bash .github/scripts/boot-studio-api-only.sh \
--port 18898 --log logs/studio_modelcfg.log --pid-var STUDIO_MODELCFG_PID
- name: Wait for /api/health on 18898
- if: matrix.shard == 'picker'
+ if: matrix.shard == 'extra'
run: |
bash .github/scripts/wait-for-health.sh \
--port 18898 --log logs/studio_modelcfg.log --tmp /tmp/health4.json
- name: Pass bootstrap pw for model-config test
- if: matrix.shard == 'picker'
+ if: matrix.shard == 'extra'
run: |
NEW="CIModelCfg-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
echo "::add-mask::$NEW"
echo "STUDIO_MODELCFG_NEW_PW=$NEW" >> "$GITHUB_ENV"
- name: Drive model-picker per-model-config with Playwright
- if: matrix.shard == 'picker'
+ if: matrix.shard == 'extra'
env:
BASE_URL: http://127.0.0.1:18898
STUDIO_NEW_PW: ${{ env.STUDIO_MODELCFG_NEW_PW }}
@@ -741,7 +749,7 @@ jobs:
# /change-password itself: the bootstrap password on this instance has already been
# rotated by then, so there is no first-boot flow left to drive.
- name: Estimated Memory Usage row (Playwright)
- if: matrix.shard == 'picker'
+ if: matrix.shard == 'extra'
env:
BASE_URL: http://127.0.0.1:18898
STUDIO_LOGIN_PW: ${{ env.STUDIO_MODELCFG_NEW_PW }}
@@ -754,7 +762,7 @@ jobs:
python tests/studio/playwright_memory_estimate.py
- name: Stop fourth Unsloth
- if: (always()) && (matrix.shard == 'picker')
+ if: (always()) && (matrix.shard == 'extra')
run: |
kill "${STUDIO_MODELCFG_PID}" 2>/dev/null || true
sleep 2
@@ -763,19 +771,19 @@ jobs:
# Third Unsloth on its own port so a hang here cannot poison the
# earlier UI tests. No GGUF -- the bug surface is the composer.
- name: Reset auth + boot Unsloth for IME / i18n tests (port 18896)
- if: matrix.shard == 'picker'
+ if: matrix.shard == 'extra'
run: |
bash .github/scripts/boot-studio-api-only.sh \
--port 18896 --log logs/studio_ime.log --pid-var STUDIO_IME_PID
- name: Wait for /api/health on 18896
- if: matrix.shard == 'picker'
+ if: matrix.shard == 'extra'
run: |
bash .github/scripts/wait-for-health.sh \
--port 18896 --log logs/studio_ime.log --tmp /tmp/health3.json
- name: Pass bootstrap pw for IME / i18n test
- if: matrix.shard == 'picker'
+ if: matrix.shard == 'extra'
# IME smoke does the change-password against the bootstrap that
# Unsloth's frontend injects into the page, so it only needs the
# NEW password.
@@ -785,7 +793,7 @@ jobs:
echo "STUDIO_IME_NEW_PW=$NEW" >> "$GITHUB_ENV"
- name: Drive IME + multilingual paste regression with Playwright
- if: matrix.shard == 'picker'
+ if: matrix.shard == 'extra'
env:
BASE_URL: http://127.0.0.1:18896
STUDIO_NEW_PW: ${{ env.STUDIO_IME_NEW_PW }}
@@ -796,7 +804,7 @@ jobs:
python tests/studio/playwright_chat_ime_i18n.py
- name: Stop third Unsloth
- if: (always()) && (matrix.shard == 'picker')
+ if: (always()) && (matrix.shard == 'extra')
run: |
kill "${STUDIO_IME_PID}" 2>/dev/null || true
sleep 2
diff --git a/.github/workflows/studio-update-smoke.yml b/.github/workflows/studio-update-smoke.yml
index 674ee163e40..6bc144d1af8 100644
--- a/.github/workflows/studio-update-smoke.yml
+++ b/.github/workflows/studio-update-smoke.yml
@@ -29,11 +29,11 @@ on:
# The install step in this workflow is `uses:` on that composite action,
# so an edit to the action changes what this workflow actually runs.
- '.github/actions/install-unsloth-local/action.yml'
- # The dist cache moved out of install-unsloth-local so the Windows jobs could
- # share one definition of its key; a change to it still has to re-run the jobs
- # that depend on it.
+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.
- '.github/actions/frontend-dist-restore/action.yml'
- '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
push:
branches: [main]
workflow_dispatch:
diff --git a/.github/workflows/studio-windows-api-smoke.yml b/.github/workflows/studio-windows-api-smoke.yml
index d964ee83aec..94ae8d848bb 100644
--- a/.github/workflows/studio-windows-api-smoke.yml
+++ b/.github/workflows/studio-windows-api-smoke.yml
@@ -15,20 +15,36 @@ name: Windows Unsloth API CI
on:
pull_request:
paths:
- - 'studio/**'
- - 'unsloth/**'
+ # What the test boots: the backend, the Windows installer chain and the CLI.
+ # studio/frontend/** stays because install.ps1 builds the bundle and the dist cache
+ # key hashes it. Not unsloth/** or studio/src-tauri/**: the install is --no-torch
+ # and never touches the Tauri shell.
+ - 'studio/backend/**'
+ - 'studio/frontend/**'
+ - 'studio/setup.ps1'
+ - 'studio/install_*.py'
+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).
+ - 'studio/node_prebuilt_pins.json'
+ - 'studio/prebuilt_core.py'
+ - 'studio/install_manifest.py'
- 'unsloth_cli/**'
- 'install.ps1'
- '.github/actions/frontend-dist-restore/action.yml'
- '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
- 'pyproject.toml'
- - 'tests/studio/**'
+ # Named, not globbed: the rest of tests/studio is Playwright drivers and
+ # PowerShell units this workflow never runs.
+ - 'tests/studio/studio_api_smoke.py'
- '.github/workflows/studio-windows-api-smoke.yml'
# Every server boot in this workflow shells out to that script, so an edit
# to it changes what this workflow actually runs.
- '.github/scripts/boot-studio-api-only.sh'
# Same for the /api/health wait that runs after a boot.
- '.github/scripts/wait-for-health.sh'
+ # And for the GGUF download that primes HF_HOME.
+ - '.github/scripts/hf-download-with-retry.sh'
push:
branches: [main]
workflow_dispatch:
@@ -158,6 +174,13 @@ jobs:
# inputs are byte-identical; the action's own reasoning, and the assertion that
# a hit was actually REUSED rather than rebuilt, live in
# .github/actions/frontend-dist-restore and -save.
+ # The uv download cache, which install-unsloth-local restores for the Linux and
+ # macOS jobs and this hand-written pwsh install never had. install.ps1 preserves the
+ # UV_CACHE_DIR the action exports; the key lives in .github/actions/uv-cache-restore.
+ - name: Restore the uv download cache
+ id: uv-cache
+ uses: ./.github/actions/uv-cache-restore
+
- name: Restore the built frontend
id: fe-dist
uses: ./.github/actions/frontend-dist-restore
@@ -200,6 +223,13 @@ jobs:
cache-hit: ${{ steps.fe-dist.outputs.cache-hit }}
key: ${{ steps.fe-dist.outputs.key }}
+ # Paired with the uv restore above: pruned to built wheels, saved on main only.
+ - name: Save the uv download cache
+ uses: ./.github/actions/uv-cache-save
+ with:
+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}
+ key: ${{ steps.uv-cache.outputs.key }}
+
- name: Assert install.ps1 used the Windows llama.cpp prebuilt
run: |
# Filesystem-based check: it does not depend on which process
diff --git a/.github/workflows/studio-windows-inference-smoke.yml b/.github/workflows/studio-windows-inference-smoke.yml
index 16e86b23388..df03369edbc 100644
--- a/.github/workflows/studio-windows-inference-smoke.yml
+++ b/.github/workflows/studio-windows-inference-smoke.yml
@@ -24,12 +24,26 @@ name: Windows Unsloth GGUF CI
on:
pull_request:
paths:
- - 'studio/**'
- - 'unsloth/**'
+ # What the phases exercise: the backend's OpenAI and Anthropic surfaces over the
+ # Windows llama.cpp prebuilt, the installer chain and the CLI. studio/frontend/**
+ # stays because install.ps1 builds the bundle and the dist cache key hashes it. Not
+ # unsloth/** or studio/src-tauri: --no-torch, and the Tauri shell is never built.
+ - 'studio/backend/**'
+ - 'studio/frontend/**'
+ - 'studio/setup.ps1'
+ - 'studio/install_*.py'
+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).
+ - 'studio/node_prebuilt_pins.json'
+ - 'studio/prebuilt_core.py'
+ - 'studio/install_manifest.py'
- 'unsloth_cli/**'
- 'install.ps1'
+ # The pre-install gate parses it and runs its uninstall unit test.
+ - 'scripts/uninstall.ps1'
- '.github/actions/frontend-dist-restore/action.yml'
- '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
- 'pyproject.toml'
- 'tests/studio_setup_ps1/**'
# The PowerShell unit tests this workflow runs live here. Without this a
@@ -37,12 +51,18 @@ on:
# runs them. Scoped to *.ps1 so python-only changes under tests/studio do
# not pull in the GGUF smoke jobs.
- 'tests/studio/*.ps1'
+ # The Pester phase runs this guard by name.
+ - 'tests/studio/test_pester_bootstrap_hardening.py'
- '.github/workflows/studio-windows-inference-smoke.yml'
# Every server boot in this workflow shells out to that script, so an edit
# to it changes what this workflow actually runs.
- '.github/scripts/boot-studio-api-only.sh'
# Same for the /api/health wait that runs after a boot.
- '.github/scripts/wait-for-health.sh'
+ # Every model download in every phase goes through it.
+ - '.github/scripts/hf-download-with-retry.sh'
+ # Phase 1 drives both SDKs through this script.
+ - '.github/scripts/studio_smoke/multi_turn_chat.py'
push:
branches: [main]
workflow_dispatch:
@@ -207,6 +227,13 @@ jobs:
# inputs are byte-identical; the action's own reasoning, and the assertion that
# a hit was actually REUSED rather than rebuilt, live in
# .github/actions/frontend-dist-restore and -save.
+ # The uv download cache, which install-unsloth-local restores for the Linux and
+ # macOS jobs and this hand-written pwsh install never had. install.ps1 preserves the
+ # UV_CACHE_DIR the action exports; the key lives in .github/actions/uv-cache-restore.
+ - name: Restore the uv download cache
+ id: uv-cache
+ uses: ./.github/actions/uv-cache-restore
+
- name: Restore the built frontend
id: fe-dist
uses: ./.github/actions/frontend-dist-restore
@@ -251,6 +278,13 @@ jobs:
cache-hit: ${{ steps.fe-dist.outputs.cache-hit }}
key: ${{ steps.fe-dist.outputs.key }}
+ # Paired with the uv restore above: pruned to built wheels, saved on main only.
+ - name: Save the uv download cache
+ uses: ./.github/actions/uv-cache-save
+ with:
+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}
+ key: ${{ steps.uv-cache.outputs.key }}
+
- name: Assert install.ps1 used the Windows llama.cpp prebuilt
id: assert-prebuilt
if: ${{ !cancelled() && steps.install.outcome == 'success' }}
diff --git a/.github/workflows/studio-windows-ui-smoke.yml b/.github/workflows/studio-windows-ui-smoke.yml
index 4412b73266b..4f3c4cd72b5 100644
--- a/.github/workflows/studio-windows-ui-smoke.yml
+++ b/.github/workflows/studio-windows-ui-smoke.yml
@@ -13,13 +13,25 @@ name: Windows Unsloth UI CI
on:
pull_request:
paths:
- - 'studio/**'
- - 'unsloth/**'
+ # The two halves the lanes drive, the backend and the React bundle, plus the
+ # Windows installer chain and the CLI. Not unsloth/** or studio/src-tauri: the
+ # install is --no-torch and never builds the Tauri shell.
+ - 'studio/backend/**'
+ - 'studio/frontend/**'
+ - 'studio/setup.ps1'
+ - 'studio/install_*.py'
+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).
+ - 'studio/node_prebuilt_pins.json'
+ - 'studio/prebuilt_core.py'
+ - 'studio/install_manifest.py'
- 'unsloth_cli/**'
- 'install.ps1'
- '.github/actions/frontend-dist-restore/action.yml'
- '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
- 'pyproject.toml'
+ # The Playwright drivers the two lanes run.
- 'tests/studio/**'
- '.github/scripts/run-studio-permission-browser.sh'
- '.github/scripts/run-studio-indicator-browser.sh'
@@ -30,6 +42,8 @@ on:
- '.github/scripts/run-studio-ui-lane.sh'
# Same for the /api/health wait that runs after a boot.
- '.github/scripts/wait-for-health.sh'
+ # And for the GGUF download that primes HF_HOME.
+ - '.github/scripts/hf-download-with-retry.sh'
push:
branches: [main]
workflow_dispatch:
@@ -191,6 +205,13 @@ jobs:
# inputs are byte-identical; the action's own reasoning, and the assertion that
# a hit was actually REUSED rather than rebuilt, live in
# .github/actions/frontend-dist-restore and -save.
+ # The uv download cache, which install-unsloth-local restores for the Linux and
+ # macOS jobs and this hand-written pwsh install never had. install.ps1 preserves the
+ # UV_CACHE_DIR the action exports; the key lives in .github/actions/uv-cache-restore.
+ - name: Restore the uv download cache
+ id: uv-cache
+ uses: ./.github/actions/uv-cache-restore
+
- name: Restore the built frontend
id: fe-dist
uses: ./.github/actions/frontend-dist-restore
@@ -242,6 +263,13 @@ jobs:
cache-hit: ${{ steps.fe-dist.outputs.cache-hit }}
key: ${{ steps.fe-dist.outputs.key }}
+ # Paired with the uv restore above: pruned to built wheels, saved on main only.
+ - name: Save the uv download cache
+ uses: ./.github/actions/uv-cache-save
+ with:
+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}
+ key: ${{ steps.uv-cache.outputs.key }}
+
- name: Assert install.ps1 used the Windows llama.cpp prebuilt
run: |
# The filesystem is the authority here: setup.ps1's "prebuilt
diff --git a/.github/workflows/studio-windows-update-smoke.yml b/.github/workflows/studio-windows-update-smoke.yml
index 7cf3c2e96fd..6b2416fd269 100644
--- a/.github/workflows/studio-windows-update-smoke.yml
+++ b/.github/workflows/studio-windows-update-smoke.yml
@@ -25,6 +25,8 @@ on:
- 'install.ps1'
- '.github/actions/frontend-dist-restore/action.yml'
- '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
- 'scripts/uninstall.ps1'
- 'tests/studio/test_uninstall_*.ps1'
- 'tests/studio/test_psmodulepath_normalization.ps1'
@@ -171,6 +173,13 @@ jobs:
# inputs are byte-identical; the action's own reasoning, and the assertion that
# a hit was actually REUSED rather than rebuilt, live in
# .github/actions/frontend-dist-restore and -save.
+ # The uv download cache, which install-unsloth-local restores for the Linux and
+ # macOS jobs and this hand-written pwsh install never had. install.ps1 preserves the
+ # UV_CACHE_DIR the action exports; the key lives in .github/actions/uv-cache-restore.
+ - name: Restore the uv download cache
+ id: uv-cache
+ uses: ./.github/actions/uv-cache-restore
+
- name: Restore the built frontend
id: fe-dist
uses: ./.github/actions/frontend-dist-restore
@@ -213,6 +222,13 @@ jobs:
cache-hit: ${{ steps.fe-dist.outputs.cache-hit }}
key: ${{ steps.fe-dist.outputs.key }}
+ # Paired with the uv restore above: pruned to built wheels, saved on main only.
+ - name: Save the uv download cache
+ uses: ./.github/actions/uv-cache-save
+ with:
+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}
+ key: ${{ steps.uv-cache.outputs.key }}
+
- name: Assert install.ps1 used the Windows llama.cpp prebuilt
run: |
# Filesystem-based check: it does not depend on which process
diff --git a/.github/workflows/studiobench-ci.yml b/.github/workflows/studiobench-ci.yml
index df7c2b040d5..b3d2baa3998 100644
--- a/.github/workflows/studiobench-ci.yml
+++ b/.github/workflows/studiobench-ci.yml
@@ -44,6 +44,11 @@ on:
- 'install.sh'
- 'pyproject.toml'
- '.github/actions/install-unsloth-local/action.yml'
+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.
+ - '.github/actions/frontend-dist-restore/action.yml'
+ - '.github/actions/frontend-dist-save/action.yml'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
- '.github/scripts/boot-studio-api-only.sh'
- '.github/scripts/wait-for-health.sh'
# The Chromium install step shells out to this, so an edit to it changes what
diff --git a/.github/workflows/studiobench-ui-parity.yml b/.github/workflows/studiobench-ui-parity.yml
index eb74e82eef4..6e8421bbbeb 100644
--- a/.github/workflows/studiobench-ui-parity.yml
+++ b/.github/workflows/studiobench-ui-parity.yml
@@ -171,6 +171,8 @@ on:
- '.github/scripts/boot-studio-api-only.sh'
- '.github/scripts/wait-for-health.sh'
- '.github/scripts/retry-with-apt-lock.sh'
+ - '.github/actions/uv-cache-restore/action.yml'
+ - '.github/actions/uv-cache-save/action.yml'
# No `push:` trigger. This job compares a merge base against a head; a push to
# main has no such pair. It therefore never SAVES a cache either, and does not
@@ -289,23 +291,12 @@ jobs:
git worktree add --detach "$RUNNER_TEMP/side_a" "${{ steps.refs.outputs.merge_base }}"
git worktree add --detach "$RUNNER_TEMP/side_b" "${{ steps.refs.outputs.side_b }}"
- # Same key and the same reasoning as .github/actions/install-unsloth-local,
- # so this job starts from the entry main already saved. A download cache is
- # content-addressed by URL and hash, so the worst a stale entry can do is
- # miss. Restore only: this workflow never runs on main and so never writes.
- - name: Point uv's cache somewhere cacheable
- run: |
- echo "UV_CACHE_DIR=${{ github.workspace }}/.uv-cache" >> "$GITHUB_ENV"
- mkdir -p "${{ github.workspace }}/.uv-cache"
-
+ # The same uv download cache install-unsloth-local restores, through the action
+ # that owns its key, so this job starts from the entry main saved. An inline copy
+ # of that key is the drift tests/studio/test_uv_cache_discipline.py exists to stop.
- name: Restore the uv download cache
- uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
- continue-on-error: true
- with:
- path: ${{ github.workspace }}/.uv-cache
- key: uv-${{ runner.os }}-${{ hashFiles('studio/backend/requirements/**', 'pyproject.toml') }}
- restore-keys: |
- uv-${{ runner.os }}-
+ id: uv-cache
+ uses: ./.github/actions/uv-cache-restore
# No frontend-dist cache here, and that is not an oversight. Its key hashes
# the ROOT checkout's frontend, and the two sides of this job are two
@@ -327,6 +318,14 @@ jobs:
HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
run: bash .github/scripts/parity-install-side.sh "$RUNNER_TEMP/side_b" "$HOME_B" logs/install_b.log
+ # No upload: nothing here runs on main, so this job only declares itself a consumer.
+ - name: Declare this job a uv cache consumer, not a producer
+ uses: ./.github/actions/uv-cache-save
+ with:
+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}
+ key: ${{ steps.uv-cache.outputs.key }}
+ save: 'false'
+
- name: Pin the Playwright version so the browser cache has a key
id: pw
run: |
diff --git a/.github/workflows/workflow-trigger-lint.yml b/.github/workflows/workflow-trigger-lint.yml
index 97251cc7942..5a9799decd0 100644
--- a/.github/workflows/workflow-trigger-lint.yml
+++ b/.github/workflows/workflow-trigger-lint.yml
@@ -146,6 +146,7 @@ jobs:
tests/studio/test_gguf_smoke_phases_stay_independent.py \
tests/studio/test_indicator_browsers_run_in_parallel.py \
tests/studio/test_inference_smoke_http_diagnostics.py \
+ tests/studio/test_install_matrix_selection.py \
tests/studio/test_install_phase_timing.py \
tests/studio/test_installer_av_shapes.py \
tests/studio/test_mac_bundled_job_phases.py \
@@ -160,6 +161,7 @@ jobs:
tests/studio/test_short_job_absorption.py \
tests/studio/test_smoke_workflows_share_one_script.py \
tests/studio/test_stt_model_search_locator_contract.py \
+ tests/studio/test_studio_smokes_do_not_trigger_on_the_training_library.py \
tests/studio/test_uv_cache_discipline.py \
tests/studio/test_version_compat_bundle.py \
tests/studio/test_windows_small_checks_stay_on_their_image.py \
diff --git a/tests/studio/test_cache_budget_discipline.py b/tests/studio/test_cache_budget_discipline.py
index 0d94dca90f8..d1d9bed8757 100644
--- a/tests/studio/test_cache_budget_discipline.py
+++ b/tests/studio/test_cache_budget_discipline.py
@@ -732,9 +732,9 @@ def _matrix_rows(job) -> list[dict]:
"""One substitution map per job the matrix can actually produce.
The base lists are expanded, not just `include`. `ui-smoke` declares its shards in a
- base `shard: [chat, extra, banner, picker]` and uses `include` only to attach
+ base `shard: [chat, extra]` and uses `include` only to attach
`engines`/`engine_key` to each, so reading `include` alone happens to give the right
- four rows today -- and would silently skip a shard added to the base list without a
+ rows today -- and would silently skip a shard added to the base list without a
matching include entry, which GitHub still runs, with those fields empty. The empty
engine set then trips the assertion in the caller, which is the point.
diff --git a/tests/studio/test_chat_ui_shards_cover_everything.py b/tests/studio/test_chat_ui_shards_cover_everything.py
index 7903301e07d..3d9a379cc1f 100644
--- a/tests/studio/test_chat_ui_shards_cover_everything.py
+++ b/tests/studio/test_chat_ui_shards_cover_everything.py
@@ -4,12 +4,14 @@
"""Every Playwright script in Chat UI Tests belongs to exactly one shard.
The job used to run 11 scripts in sequence against four Unsloth instances, at 22.1 minutes on
-average, the largest single job in the repo. It is now four shards split on the Unsloth
-boundaries.
+average, the largest single job in the repo. It was split into four shards on the Unsloth
+boundaries, and is now two: `banner` folded into `chat` and `picker` into `extra`, because
+four cells of 3 to 9 minutes each queued about two hours for a runner while the account ran
+30 to 35 jobs at once. Two cells of about 12 minutes take half the slots.
The failure mode that matters is not a broken shard, which is loud. It is a step whose
`if:` names no shard, or names one that does not exist, or is dropped from the matrix: the
-step then runs nowhere, the job is green on all four shards, and a Playwright regression
+step then runs nowhere, the job is green on every shard, and a Playwright regression
suite has silently stopped existing. Nothing else in CI would notice, because a test that
does not run cannot fail.
diff --git a/tests/studio/test_install_matrix_selection.py b/tests/studio/test_install_matrix_selection.py
new file mode 100644
index 00000000000..fb1abbe6e82
--- /dev/null
+++ b/tests/studio/test_install_matrix_selection.py
@@ -0,0 +1,240 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The install workflows run a PR subset of their legs and the whole set nightly.
+
+clean-machine-install-ci.yml (20 legs, 7 on macOS) and interrupted-install-ci.yml (10
+legs, 6 on macOS) used to run every leg on every pull_request that touched an installer,
+against an account capped at five concurrent macOS jobs. On the 20 PRs audited before
+the split not one of those runs finished: each was cancelled by the next push while its
+macOS legs were still queued, and while they queued they held the macOS pool against
+every other job in the org.
+
+The legs now live in .github/ci/*-matrix.yml with a `pr` flag each, and a `select` job
+hands every matrix job the `include` list for the event
+(.github/scripts/select_install_matrix.py). This file pins what that split relies on:
+
+* the matrix files parse and every leg has the keys its job's steps read, because a
+ leg missing a key no longer fails at YAML time but at `matrix.<key>` time on a runner;
+* the PR subset per job is what the workflow header says it is, and the clean-machine
+ subset keeps a macOS leg, so tests/studio/test_macos_slots_per_commit.py still counts
+ the file as a macOS workflow;
+* the `select` job is the only producer, every matrix job takes its legs from it, and a
+ job whose PR subset is empty gates on the `_count` output rather than expanding an
+ empty matrix, which is a workflow error;
+* the emitted JSON never carries the `pr` key, so what a job sees is exactly the leg.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+import yaml
+
+REPO = Path(__file__).resolve().parents[2]
+WORKFLOWS = REPO / ".github" / "workflows"
+SELECTOR = REPO / ".github" / "scripts" / "select_install_matrix.py"
+
+# workflow -> (matrix file, {job: (all legs, PR legs)})
+EXPECTED = {
+ "clean-machine-install-ci.yml": (
+ ".github/ci/clean-machine-matrix.yml",
+ {"macos": (7, 3), "linux": (6, 2), "windows": (3, 1), "windows_container_install": (2, 1)},
+ ),
+ "interrupted-install-ci.yml": (
+ ".github/ci/interrupted-install-matrix.yml",
+ {"interrupt": (8, 2), "interrupt-windows": (2, 0)},
+ ),
+}
+
+# Keys every leg of a job must carry, stated here rather than derived from the legs: a
+# leg that drops `overlay` renders `${{ matrix.overlay }}` empty and quietly tests the
+# released package, so the list that catches that cannot be computed from the legs.
+# Anything else a job reads (`nonroot`, `wget_only`, `allow_working`, ...) is an optional
+# flag read with a truthiness test.
+REQUIRED_KEYS = {
+ "macos": {"os", "mode", "delivery", "flags", "experimental", "overlay"},
+ "linux": {"label", "image", "runner", "experimental", "overlay"},
+ "windows": {"os", "winget", "experimental", "overlay"},
+ "windows_container_install": {"overlay"},
+ "interrupt": {"os", "label", "marker"},
+ "interrupt-windows": {"label", "marker", "installArgs"},
+}
+
+_SELECTED = re.compile(r"^\$\{\{\s*fromJSON\(needs\.select\.outputs\.([\w-]+)\)\s*\}\}$")
+_MATRIX_KEY = re.compile(r"matrix\.([\w-]+)")
+
+
+def _key(jid: str) -> str:
+ """The matrix-file key and select output for a job id: outputs cannot carry `-`."""
+ return jid.replace("-", "_")
+
+
+def _doc(name: str) -> dict:
+ return yaml.safe_load((WORKFLOWS / name).read_text(encoding = "utf-8"))
+
+
+def _legs(matrix_file: str) -> dict:
+ legs = yaml.safe_load((REPO / matrix_file).read_text(encoding = "utf-8"))
+ assert isinstance(legs, dict), f"{matrix_file}: expected a mapping of job -> legs"
+ return legs
+
+
+def _select(matrix_file: str, event: str) -> dict[str, str]:
+ """Run the selector the way the `select` job does and return its output lines."""
+ out = subprocess.run(
+ [sys.executable, str(SELECTOR), "--file", matrix_file, "--event", event],
+ cwd = REPO,
+ capture_output = True,
+ text = True,
+ check = True,
+ ).stdout
+ return dict(line.split("=", 1) for line in out.splitlines() if line)
+
+
[email protected]("name", sorted(EXPECTED))
+def test_the_matrix_file_is_the_one_the_select_job_reads(name):
+ matrix_file, jobs = EXPECTED[name]
+ doc = _doc(name)
+ select = doc["jobs"]["select"]
+ files = [
+ (s.get("env") or {}).get("MATRIX_FILE") for s in select["steps"] if isinstance(s, dict)
+ ]
+ assert matrix_file in files, f"{name}: the select job does not read {matrix_file}"
+ assert set(_legs(matrix_file)) == {_key(j) for j in jobs}, (
+ f"{name}: {matrix_file} lists jobs {sorted(_legs(matrix_file))}, "
+ f"this test expects {sorted(jobs)}"
+ )
+
+
[email protected]("name", sorted(EXPECTED))
+def test_every_matrix_job_takes_its_legs_from_select_and_nothing_else_does(name):
+ matrix_file, jobs = EXPECTED[name]
+ doc = _doc(name)
+ for jid, job in doc["jobs"].items():
+ matrix = (job.get("strategy") or {}).get("matrix")
+ if matrix is None:
+ continue
+ match = _SELECTED.match(str(matrix))
+ assert match, f"{name}:{jid} carries a literal matrix; the legs belong in {matrix_file}"
+ assert match.group(1) == _key(jid), (
+ f"{name}:{jid} reads needs.select.outputs.{match.group(1)}; the output is "
+ f"named after the job so the file and the workflow cannot drift"
+ )
+ assert jid in jobs, f"{name}:{jid} is a matrix job this test does not know"
+ needs = job.get("needs")
+ needs = needs if isinstance(needs, list) else [needs]
+ assert "select" in needs, f"{name}:{jid} does not depend on the select job"
+ for jid in jobs:
+ assert jid in doc["jobs"], f"{name}: matrix job {jid} is gone but its legs are not"
+
+
[email protected]("name", sorted(EXPECTED))
+def test_every_leg_has_the_keys_its_job_reads(name):
+ """A key a step reads through `matrix.<key>` must be on every leg, or be optional.
+
+ Keys the workflow reads with a truthiness test (`matrix.nonroot && ...`) are optional
+ by construction; those read into a name, a label or an env value must be present,
+ because an absent key renders as the empty string and the job runs with it.
+ """
+ matrix_file, jobs = EXPECTED[name]
+ doc = _doc(name)
+ legs = _legs(matrix_file)
+ for jid in jobs:
+ job = doc["jobs"][jid]
+ read = set(_MATRIX_KEY.findall(json.dumps(job)))
+ required = REQUIRED_KEYS[jid]
+ assert required <= read, f"{name}:{jid} never reads {sorted(required - read)}"
+ declared = [set(leg) - {"pr"} for leg in legs[_key(jid)]]
+ for leg in legs[_key(jid)]:
+ assert "pr" in leg and isinstance(
+ leg["pr"], bool
+ ), f"{matrix_file}:{jid}: {leg} has no bool `pr`"
+ missing = required - set(leg)
+ assert not missing, f"{matrix_file}:{jid}: {leg} lacks {sorted(missing)}"
+ unknown = read - {k for leg in declared for k in leg}
+ assert not unknown, f"{name}:{jid} reads matrix keys no leg declares: {sorted(unknown)}"
+
+
[email protected]("name", sorted(EXPECTED))
+def test_the_pr_subset_and_the_full_set_are_the_sizes_the_headers_claim(name):
+ matrix_file, jobs = EXPECTED[name]
+ legs = _legs(matrix_file)
+ for jid, (total, on_pr) in jobs.items():
+ rows = legs[_key(jid)]
+ assert len(rows) == total, f"{matrix_file}:{jid}: {len(rows)} legs, expected {total}"
+ picked = [leg for leg in rows if leg["pr"]]
+ assert len(picked) == on_pr, f"{matrix_file}:{jid}: {len(picked)} PR legs, expected {on_pr}"
+
+
+def test_the_clean_machine_pr_subset_keeps_a_macos_leg():
+ """test_macos_slots_per_commit.py must keep counting the file as a macOS workflow."""
+ legs = _legs(EXPECTED["clean-machine-install-ci.yml"][0])
+ assert any(leg["pr"] and str(leg.get("os", "")).startswith("macos-") for leg in legs["macos"])
+
+
[email protected]("name", sorted(EXPECTED))
+def test_a_job_whose_pr_subset_is_empty_gates_on_the_count(name):
+ """An empty `include` is a workflow error, not a job with no legs."""
+ matrix_file, jobs = EXPECTED[name]
+ doc = _doc(name)
+ outputs = doc["jobs"]["select"].get("outputs") or {}
+ for jid, (_, on_pr) in jobs.items():
+ if on_pr:
+ continue
+ job = doc["jobs"][jid]
+ gate = f"needs.select.outputs.{_key(jid)}_count != '0'"
+ assert gate in str(job.get("if", "")), f"{name}:{jid} has no PR legs and no `if: {gate}`"
+ assert (
+ f"{_key(jid)}_count" in outputs
+ ), f"{name}: the select job does not expose {_key(jid)}_count"
+ # The container probe exists only to gate the container install rows.
+ if name == "clean-machine-install-ci.yml":
+ probe = doc["jobs"]["windows_container_probe"]
+ assert "windows_container_install_count != '0'" in str(probe.get("if", ""))
+
+
[email protected]("name", sorted(EXPECTED))
[email protected]("event", ["pull_request", "schedule", "push", "workflow_dispatch"])
+def test_the_selector_emits_the_legs_without_the_pr_flag(name, event):
+ matrix_file, jobs = EXPECTED[name]
+ out = _select(matrix_file, event)
+ for jid, (total, on_pr) in jobs.items():
+ matrix = json.loads(out[_key(jid)])
+ assert list(matrix) == [
+ "include"
+ ], f"{jid}: the matrix must be a mapping with only `include`"
+ expected = on_pr if event == "pull_request" else total
+ assert (
+ len(matrix["include"]) == expected
+ ), f"{jid} on {event}: {len(matrix['include'])} legs"
+ assert out[f"{_key(jid)}_count"] == str(expected)
+ for leg in matrix["include"]:
+ assert "pr" not in leg, f"{jid}: the `pr` flag leaked into the matrix: {leg}"
+ assert "\n" not in out[_key(jid)], f"{jid}: multi-line JSON would truncate in GITHUB_OUTPUT"
+
+
+def test_the_wsl_leg_is_off_on_pull_requests():
+ """Not a matrix job, so it gates on the event itself; the header says why."""
+ doc = _doc("clean-machine-install-ci.yml")
+ assert doc["jobs"]["wsl"].get("if") == "github.event_name != 'pull_request'"
+
+
[email protected]("name", sorted(EXPECTED))
+def test_the_nightly_and_the_matrix_file_are_wired_into_the_trigger(name):
+ """The full set has to run somewhere, and a matrix edit has to run the workflow."""
+ matrix_file, _ = EXPECTED[name]
+ doc = _doc(name)
+ on = doc.get(True) if True in doc else doc.get("on")
+ assert on.get("schedule"), f"{name}: no schedule, so the nightly-only legs never run"
+ for trigger in ("pull_request", "push"):
+ paths = (on.get(trigger) or {}).get("paths")
+ if paths is None:
+ continue
+ for needed in (matrix_file, ".github/scripts/select_install_matrix.py"):
+ assert needed in paths, f"{name}: {trigger} paths do not list {needed}"
diff --git a/tests/studio/test_macos_slots_per_commit.py b/tests/studio/test_macos_slots_per_commit.py
index ffba76b06ef..f89222ffc73 100644
--- a/tests/studio/test_macos_slots_per_commit.py
+++ b/tests/studio/test_macos_slots_per_commit.py
@@ -43,7 +43,35 @@ def _on(doc):
return doc.get(True) if True in doc else doc.get("on")
-def _job_runs_on_macos(job) -> bool:
+_SELECTED_MATRIX = re.compile(r"fromJSON\(\s*needs\.([\w-]+)\.outputs\.([\w-]+)\s*\)")
+
+
+def _matrix(job, doc) -> dict:
+ """The matrix ``job`` expands, as a mapping, wherever its legs are written down.
+
+ A literal `strategy.matrix` is returned as is. The install workflows instead take
+ `matrix: ${{ fromJSON(needs.select.outputs.<job>) }}` from a `select` job that reads
+ `.github/ci/*-matrix.yml` (see .github/scripts/select_install_matrix.py), so the legs
+ are resolved from that file: the `MATRIX_FILE` env of the producing job's steps names
+ it, and the output name is the key. Every leg is returned, PR subset or not, because
+ this file asks which images a job CAN allocate.
+ """
+ matrix = (job.get("strategy") or {}).get("matrix") or {}
+ if isinstance(matrix, dict):
+ return matrix
+ match = _SELECTED_MATRIX.search(str(matrix))
+ if not match or not isinstance(doc, dict):
+ return {}
+ producer = (doc.get("jobs") or {}).get(match.group(1)) or {}
+ for step in producer.get("steps") or []:
+ matrix_file = ((step.get("env") or {}) if isinstance(step, dict) else {}).get("MATRIX_FILE")
+ if matrix_file:
+ legs = yaml.safe_load((REPO / matrix_file).read_text(encoding = "utf-8")) or {}
+ return {"include": list(legs.get(match.group(2)) or [])}
+ return {}
+
+
+def _job_runs_on_macos(job, doc = None) -> bool:
"""Whether ``job`` schedules a macOS runner.
Reads `runs-on` and, when that is a matrix expression, the matrix values it selects
@@ -61,7 +89,7 @@ def _job_runs_on_macos(job) -> bool:
return True
# `runs-on: ${{ matrix.os }}` -- resolve against the matrix it names.
for key in re.findall(r"matrix\.([\w-]+)", value):
- matrix = (job.get("strategy") or {}).get("matrix") or {}
+ matrix = _matrix(job, doc)
candidates = list(matrix.get(key) or [])
for entry in matrix.get("include") or []:
if isinstance(entry, dict) and key in entry:
@@ -78,7 +106,7 @@ def _macos_workflows():
doc = yaml.safe_load(text)
if not isinstance(doc, dict) or not isinstance(doc.get("jobs"), dict):
continue
- if any(_job_runs_on_macos(j) for j in doc["jobs"].values() if isinstance(j, dict)):
+ if any(_job_runs_on_macos(j, doc) for j in doc["jobs"].values() if isinstance(j, dict)):
yield path.name, doc, text
@@ -315,8 +343,7 @@ def _macos_labels():
# runs-on plus the matrix it may select from: a retired image hides in an `include:`
# list just as easily as in a literal runs-on.
blob = str(job.get("runs-on", ""))
- strategy = job.get("strategy") or {}
- blob += str((strategy.get("matrix") or {}) if isinstance(strategy, dict) else "")
+ blob += str(_matrix(job, doc) if isinstance(job.get("strategy"), dict) else "")
# Only things shaped like a GitHub image name. The loose MACOS pattern used elsewhere
# in this file also matches build targets that merely contain "macos":
# release-desktop's matrix carries `macos-aarch64`, which is a Rust triple's nickname
diff --git a/tests/studio/test_studio_smokes_do_not_trigger_on_the_training_library.py b/tests/studio/test_studio_smokes_do_not_trigger_on_the_training_library.py
new file mode 100644
index 00000000000..82ba54ed08b
--- /dev/null
+++ b/tests/studio/test_studio_smokes_do_not_trigger_on_the_training_library.py
@@ -0,0 +1,276 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The Studio smoke workflows trigger on what they can observe, and nothing else.
+
+Every Studio smoke in this repo installs with `--local --no-torch`: the venv under test
+cannot import the training library, so an edit under `unsloth/**` cannot change what the
+job sees. Seven of the nine smokes nonetheless listed `unsloth/**` in their `pull_request`
+filter, and all nine listed `studio/**`, which also matches `studio/src-tauri` (never built
+by a smoke) and `studio/docs`. Measured over the last 20 PRs, a push that touched only
+`studio/backend` fired 19 to 25 workflows and 50 to 90 jobs against an account that runs
+about 30 to 35 jobs at once, and a training-only PR paid every Studio runner, macOS
+included, for nothing. The queue waits that produced (p50 128 minutes on ubuntu-latest,
+213 on macos-15) were the whole cost of the CI, the tests themselves finish in minutes.
+
+Three rules, each cheap to break silently and expensive to leave broken:
+
+1. No Studio smoke lists `unsloth/**` or a bare `studio/**`. The narrow set is spelled out
+ per workflow (`studio/backend/**`, `studio/frontend/**` where Playwright drives the
+ bundle, the installer entry points) and the comment above each list says why.
+2. A filter lists every `.github/scripts` and `.github/actions` path the workflow executes,
+ and nothing under those directories that it does not. The second half is what retired
+ the `frontend-dist-*` entries from six workflows that never `uses:` them: a listed
+ action the job never runs is a trigger for nothing, and it hid the fact that the list
+ was copied rather than derived.
+3. `local-agent-guides-ci.yml` names the route modules that serve the endpoints its
+ preflight curls, not `studio/backend/routes/**`. Its connection matrix is nine
+ ubuntu-latest cells of up to 16 minutes, and it fired for every edit to the training,
+ export and dataset routes it never requests.
+
+`tests/studio/test_macos_slots_per_commit.py` already pins `push.paths == pull_request.paths`
+for the macOS workflows; this module does not repeat that.
+"""
+
+import re
+from pathlib import Path
+
+import pytest
+import yaml
+
+REPO = Path(__file__).resolve().parents[2]
+WORKFLOWS = REPO / ".github" / "workflows"
+
+# Every workflow that installs Studio with --no-torch and boots it. The Update smokes are
+# included because their filters were already narrow and must stay that way.
+STUDIO_SMOKES = (
+ "studio-api-smoke.yml",
+ "studio-inference-smoke.yml",
+ "studio-ui-smoke.yml",
+ "studio-update-smoke.yml",
+ "studio-windows-api-smoke.yml",
+ "studio-windows-inference-smoke.yml",
+ "studio-windows-ui-smoke.yml",
+ "studio-windows-update-smoke.yml",
+ "studio-mac-ui-smoke.yml",
+)
+
+AGENT_GUIDES = "local-agent-guides-ci.yml"
+
+# Rule 2 applies to these on top of the smokes: they have the same shape of filter.
+DERIVED_FILTERS = STUDIO_SMOKES + (AGENT_GUIDES,)
+
+FORBIDDEN = {"unsloth/**", "studio/**"}
+
+# A path under .github/scripts or .github/actions that a step runs, sources or `uses:`.
+# `./.github/actions/x` and `.github/actions/x/action.yml` normalise to the same thing.
+EXECUTED = re.compile(r"(?:\./)?(\.github/(?:scripts|actions)/[A-Za-z0-9_./-]+)")
+
+
+def _on(doc):
+ """The `on:` mapping, which PyYAML parses as the boolean True."""
+ return doc.get(True) if True in doc else doc.get("on")
+
+
+def _load(name: str):
+ return yaml.safe_load((WORKFLOWS / name).read_text(encoding = "utf-8"))
+
+
+def _paths(doc, event: str) -> list[str]:
+ trigger = _on(doc).get(event)
+ if not isinstance(trigger, dict):
+ return []
+ return list(trigger.get("paths") or [])
+
+
+def _step_text(doc) -> str:
+ """Everything a step can execute: run bodies, `uses:` targets, and `with:` values."""
+ chunks = []
+ for job in doc["jobs"].values():
+ for step in job.get("steps") or []:
+ for key in ("run", "uses"):
+ if step.get(key):
+ chunks.append(str(step[key]))
+ for value in (step.get("with") or {}).values():
+ chunks.append(str(value))
+ for value in (step.get("env") or {}).values():
+ chunks.append(str(value))
+ return "\n".join(chunks)
+
+
+def _normalise(path: str) -> str:
+ path = path.removeprefix("./")
+ path = path.rstrip(".,;:)'\"")
+ if path.startswith(".github/actions/") and not path.endswith(".yml"):
+ path = path.rstrip("/") + "/action.yml"
+ return path
+
+
+# A helper script reaching a sibling: `$SCRIPT_DIR/x.sh`, `"$(dirname "$0")/x.txt"`, or
+# the repo-relative `.github/scripts/x.sh` form.
+SIBLING = re.compile(
+ r"(?:\$SCRIPT_DIR|\$\{SCRIPT_DIR\}|\$\(dirname \"?\$0\"?\)|\.github/scripts)/([A-Za-z0-9_.-]+)"
+)
+
+
+def _executed_github_paths(doc) -> set[str]:
+ """The .github/scripts and .github/actions files the steps reach.
+
+ Indirection is followed: run-studio-ui-lane.sh boots Studio and drives the
+ permission and indicator browsers through sibling scripts, agent-guides-drive.sh
+ reads its prompts from sibling text files, and install-unsloth-local `uses:` the
+ dist and uv cache actions. An edit to any of those changes what the job runs just
+ as surely as an edit to the script or action the step names, so the filter has to
+ list them too.
+ """
+ found = set()
+ for match in EXECUTED.findall(_step_text(doc)):
+ path = _normalise(match)
+ if (REPO / path).is_file():
+ found.add(path)
+ # A local composite action that `uses:` another local action pulls that one in.
+ pending = [p for p in found if p.startswith(".github/actions/")]
+ while pending:
+ text = (REPO / pending.pop()).read_text(encoding = "utf-8", errors = "replace")
+ for match in EXECUTED.findall(text):
+ nested = _normalise(match)
+ if (
+ nested.startswith(".github/actions/")
+ and (REPO / nested).is_file()
+ and nested not in found
+ ):
+ found.add(nested)
+ pending.append(nested)
+ for path in sorted(found):
+ if not path.startswith(".github/scripts/"):
+ continue
+ text = (REPO / path).read_text(encoding = "utf-8", errors = "replace")
+ for name in SIBLING.findall(text):
+ sibling = f".github/scripts/{name}"
+ if (REPO / sibling).is_file():
+ found.add(sibling)
+ return found
+
+
+def _listed_github_paths(paths: list[str]) -> set[str]:
+ return {
+ p for p in paths if p.startswith(".github/scripts/") or p.startswith(".github/actions/")
+ }
+
+
[email protected]("name", STUDIO_SMOKES)
+def test_no_studio_smoke_triggers_on_the_training_library_or_all_of_studio(name):
+ doc = _load(name)
+ for event in ("pull_request", "push"):
+ offending = FORBIDDEN & set(_paths(doc, event))
+ assert not offending, (
+ f"{name} {event}.paths lists {sorted(offending)}. The install is --no-torch, so "
+ "unsloth/** cannot reach the venv under test, and studio/** also matches the "
+ "Tauri shell and docs the smoke never touches. Name the directories the job "
+ "observes instead."
+ )
+ assert "studio/backend/**" in _paths(doc, "pull_request") or name.endswith(
+ "update-smoke.yml"
+ ), f"{name} must still trigger on the backend it boots"
+
+
[email protected]("name", STUDIO_SMOKES)
+def test_every_smoke_still_names_the_workflow_file_and_the_apt_helper_it_runs(name):
+ doc = _load(name)
+ paths = set(_paths(doc, "pull_request"))
+ assert f".github/workflows/{name}" in paths, f"{name} must re-run when it is edited"
+ text = _step_text(doc)
+ if "retry-with-apt-lock.sh" in text:
+ assert (
+ ".github/scripts/retry-with-apt-lock.sh" in paths
+ ), f"{name} calls retry-with-apt-lock.sh but would not re-run when it changes"
+
+
[email protected]("name", DERIVED_FILTERS)
+def test_the_filter_lists_exactly_the_github_paths_the_steps_execute(name):
+ doc = _load(name)
+ executed = _executed_github_paths(doc)
+ for event in ("pull_request", "push"):
+ paths = _paths(doc, event)
+ if not paths:
+ continue
+ listed = _listed_github_paths(paths) - {f".github/workflows/{name}"}
+ missing = sorted(executed - listed)
+ assert not missing, (
+ f"{name} {event}.paths does not list {missing}, which its steps execute; an edit "
+ "to any of them changes what the job runs without running it"
+ )
+ dead = sorted(listed - executed)
+ assert not dead, (
+ f"{name} {event}.paths lists {dead}, which no step in the workflow runs, sources "
+ "or `uses:`; a trigger for nothing means the list was copied, not derived"
+ )
+
+
+def test_executed_path_detection_is_not_vacuous():
+ """The scanner must find the helpers every smoke is known to call."""
+ doc = _load("studio-ui-smoke.yml")
+ executed = _executed_github_paths(doc)
+ assert ".github/scripts/boot-studio-api-only.sh" in executed
+ assert ".github/actions/install-unsloth-local/action.yml" in executed
+ # Reached through install-unsloth-local, which `uses:` the dist and uv cache pairs.
+ assert ".github/actions/frontend-dist-restore/action.yml" in executed
+ assert ".github/actions/uv-cache-restore/action.yml" in executed
+ windows = _executed_github_paths(_load("studio-windows-ui-smoke.yml"))
+ assert ".github/actions/frontend-dist-restore/action.yml" in windows
+
+
+def _endpoints_curled(doc) -> set[str]:
+ """The /v1 endpoints the workflow's own steps request."""
+ return set(re.findall(r"/v1/(chat/completions|messages|responses|models)\b", _step_text(doc)))
+
+
+def _route_decorators(module: Path) -> set[str]:
+ """The route suffixes a module declares, e.g. chat/completions for /v1/chat/completions."""
+ text = module.read_text(encoding = "utf-8")
+ found = set()
+ for path in re.findall(r"@router\.(?:get|post|api_route)\(\s*\"/?([A-Za-z0-9_/{}:]+)\"", text):
+ found.add(path.strip("/").removeprefix("v1/"))
+ return found
+
+
+def test_agent_guides_lists_the_route_modules_that_serve_what_it_curls():
+ doc = _load(AGENT_GUIDES)
+ curled = _endpoints_curled(doc)
+ assert {"chat/completions", "messages", "responses", "models"} <= curled, curled
+ for event in ("pull_request", "push"):
+ paths = _paths(doc, event)
+ assert "studio/backend/routes/**" not in paths, (
+ f"{AGENT_GUIDES} {event}.paths matches every route module; the preflight only "
+ "requests the OpenAI and Anthropic surfaces"
+ )
+ routes = sorted(p for p in paths if p.startswith("studio/backend/routes/"))
+ assert routes, f"{AGENT_GUIDES} {event}.paths names no route module at all"
+ serving = set()
+ for entry in routes:
+ module = REPO / entry
+ assert module.is_file(), f"{AGENT_GUIDES} lists {entry}, which does not exist"
+ declared = _route_decorators(module)
+ served = {e for e in curled if e in declared or e.rstrip("/") + "/" in declared}
+ assert served, (
+ f"{AGENT_GUIDES} lists {entry} but it declares none of {sorted(curled)}; "
+ "either the endpoint moved or the entry is stale"
+ )
+ serving |= served
+ assert curled <= serving, (
+ f"{AGENT_GUIDES} {event}.paths covers {sorted(serving)} but the preflight also "
+ f"requests {sorted(curled - serving)}; add the module that serves it"
+ )
+ # The contracts outside routes/ the docstring names must stay.
+ for required in (
+ "studio/backend/main.py",
+ "studio/backend/core/inference/llama_cpp.py",
+ "studio/backend/models/**",
+ "unsloth_cli/*",
+ "unsloth_cli/commands/*.py",
+ ):
+ assert required in paths, f"{AGENT_GUIDES} {event}.paths lost {required}"
+ assert "unsloth_cli/**" not in paths, (
+ f"{AGENT_GUIDES} {event}.paths matches the whole CLI package; the cells never run "
+ "unsloth_cli/tests/**"
+ )
diff --git a/tests/studio/test_ui_shard_engines.py b/tests/studio/test_ui_shard_engines.py
index 9adb973d8a6..7e04b65e74c 100644
--- a/tests/studio/test_ui_shard_engines.py
+++ b/tests/studio/test_ui_shard_engines.py
@@ -3,18 +3,26 @@
"""
Each Chat UI shard must install exactly the browser engines its own steps drive.
-The four shards used to install all three engines each. Two of them -- `extra` and
-`picker` -- never open anything but chromium, and installing webkit's system
-libraries for them is an apt transaction of 181 packages and 102 MB:
+The shards used to install all three engines each. The chromium-only ones (`extra`,
+which now also carries the former `picker` suites) never open anything but chromium,
+and installing webkit's system libraries for them is an apt transaction of 181
+packages and 102 MB:
0 upgraded, 181 newly installed, 0 to remove
Need to get 102 MB/114 MB of archives
Get:2 .../noble/universe amd64 fonts-wqy-zenhei all 0.9.45-8 [7472 kB]
-> 4m51s later: attempt 2/2 did not finish within 300s
-Fonts, X fonts and a soundfont, fetched so that two shards which never launch webkit
+Fonts, X fonts and a soundfont, fetched so that a shard which never launches webkit
could time out fetching them. That is what this file exists to stop coming back.
+Two shards rather than four since the fold of `banner` into `chat` and `picker` into
+`extra`: the four cells ran 5.3, 8.9, 6.5 and 2.8 minutes and each waited about two
+hours for an ubuntu-latest runner, so two cells of about 12 minutes take half the
+slots for the same wall-clock. The engine sets did not change, which is why the fold
+was possible at all: `banner` already installed the three engines `chat` installs, and
+`picker` was chromium-only like `extra`.
+
It is enforced in BOTH directions, and the second one is the dangerous one:
* installing an engine no step drives is waste, and waste on a degraded mirror is
@@ -24,7 +32,7 @@ It is enforced in BOTH directions, and the second one is the dangerous one:
green, which reads as a flaky test rather than a missing package.
Derived from the workflow, never from a hardcoded list: the whole point is that
-adding a webkit step to `picker` fails HERE, at the edit, rather than in CI.
+adding a webkit step to `extra` fails HERE, at the edit, rather than in CI.
"""
from __future__ import annotations
@@ -135,8 +143,8 @@ def test_the_detector_sees_the_cross_browser_steps() -> None:
f"the chat shard drives {sorted(chat)}; it runs Cross-browser permission "
f"controls, so the step scan is not seeing engine names any more"
)
- picker = _engines_driven_by("picker")
- assert "webkit" not in picker, (
- f"the picker shard now appears to drive {sorted(picker)}; if that is real the "
+ extra = _engines_driven_by("extra")
+ assert "webkit" not in extra, (
+ f"the extra shard now appears to drive {sorted(extra)}; if that is real the "
f"matrix needs updating, and if it is not the scan is over-matching"
)
diff --git a/tests/studio/test_uv_cache_discipline.py b/tests/studio/test_uv_cache_discipline.py
index 87a9ac2bad8..05aa379b267 100644
--- a/tests/studio/test_uv_cache_discipline.py
+++ b/tests/studio/test_uv_cache_discipline.py
@@ -205,3 +205,208 @@ def test_the_action_is_actually_used() -> None:
if "install-unsloth-local" in p.read_text(encoding = "utf-8")
]
assert len(users) >= 5, f"only {len(users)} workflows use the action: {users}"
+
+
+# The Windows jobs run install.ps1 from a hand-written pwsh step and never come through
+# install-unsloth-local, so the restore and the save are their own composite actions,
+# which that composite delegates to and the Windows jobs call directly. What follows
+# holds that shape: one key, every warm installer job restoring it, every restore paired
+# with a save that reads its outputs, and the cold lanes untouched.
+
+ACTIONS = REPO_ROOT / ".github" / "actions"
+UV_RESTORE = ACTIONS / "uv-cache-restore" / "action.yml"
+UV_SAVE = ACTIONS / "uv-cache-save" / "action.yml"
+
+# Cold at JOB level, inside a workflow whose other jobs legitimately use the cache; the
+# same list tests/studio/test_frontend_dist_cache.py keeps for the dist.
+COLD_INSTALL_JOBS = (("studio-windows-inference-smoke.yml", "no-vs-cpu"),)
+
+# An INVOCATION, not a mention: mlx-ci.yml explains in a comment why it does NOT run
+# `install.sh --local`, and a bare substring match called that an uncached install.
+_INSTALLER = re.compile(r"(?m)^\s*[^#\n]*?(?:^|[\s/&'\"])install\.(?:ps1|sh) --local")
+_HELPER = re.compile(r"\.github/scripts/([A-Za-z0-9_.-]+\.sh)")
+
+
+def _runs_installer(step: dict) -> bool:
+ """Whether ``step`` runs the installer itself or through a helper under .github/scripts.
+
+ studiobench-ui-parity installs each side through parity-install-side.sh, so the
+ invocation is one file away from the workflow; followed one level, like the smoke
+ trigger guard does for its helpers.
+ """
+ run = str(step.get("run", ""))
+ if _INSTALLER.search(run):
+ return True
+ for helper in _HELPER.findall(run):
+ path = REPO_ROOT / ".github" / "scripts" / helper
+ if path.is_file() and _INSTALLER.search(path.read_text(encoding = "utf-8", errors = "replace")):
+ return True
+ return False
+
+
+def _jobs():
+ for f in sorted(WORKFLOWS.glob("*.yml")):
+ doc = yaml.safe_load(f.read_text(encoding = "utf-8"))
+ if isinstance(doc, dict) and isinstance(doc.get("jobs"), dict):
+ for jid, job in doc["jobs"].items():
+ if isinstance(job, dict):
+ yield f.name, jid, job
+
+
+def _produces_on_main(name: str) -> bool:
+ """Same rule as the dist guard: `push` to main or `schedule`, never `workflow_dispatch`."""
+ doc = yaml.safe_load((WORKFLOWS / name).read_text(encoding = "utf-8"))
+ on = doc.get("on", doc.get(True)) or {}
+ if isinstance(on, str):
+ on = {on: None}
+ elif isinstance(on, list):
+ on = dict.fromkeys(on)
+ if "schedule" in on:
+ return True
+ if "push" not in on:
+ return False
+ push = on.get("push")
+ branches = push.get("branches") if isinstance(push, dict) else None
+ return branches is None or "main" in branches
+
+
+def test_the_uv_cache_key_has_exactly_one_definition() -> None:
+ """A second copy agrees today and drifts silently, with the cache still hitting."""
+ definers = []
+ for path in sorted(list(ACTIONS.rglob("action.yml")) + list(WORKFLOWS.glob("*.yml"))):
+ if re.search(r"key:\s*uv-\$\{\{", path.read_text(encoding = "utf-8")):
+ definers.append(str(path.relative_to(REPO_ROOT)))
+ assert definers == [
+ ".github/actions/uv-cache-restore/action.yml"
+ ], f"the uv cache key is defined in {definers}; it must have exactly one definition"
+
+
+def test_install_unsloth_local_delegates_the_uv_cache() -> None:
+ uses = [str(s.get("uses", "")) for s in _own_steps()]
+ assert "./.github/actions/uv-cache-restore" in uses, uses
+ assert "./.github/actions/uv-cache-save" in uses, uses
+ assert not any("actions/cache" in u for u in uses), (
+ "install-unsloth-local carries its own cache step again; the key must stay in "
+ "uv-cache-restore"
+ )
+
+
+def test_the_uv_actions_nest_nothing() -> None:
+ """`uses: ./...` inside a composite resolves from GITHUB_WORKSPACE and takes no expressions.
+
+ install-unsloth-local nests these two and is root-checkout-only for it. The leaf
+ actions must stay leaves, so a nested-checkout job can still call them directly.
+ """
+ for action in (UV_RESTORE, UV_SAVE):
+ nested = [
+ str(s.get("uses", ""))
+ for s in _own_steps(action)
+ if str(s.get("uses", "")).startswith("./")
+ ]
+ assert not nested, f"{action.relative_to(REPO_ROOT)} nests {nested}"
+
+
+def test_every_warm_installer_job_restores_the_uv_cache() -> None:
+ """A job that runs the installer without the cache pays the full download every run.
+
+ The cold lanes are the deliberate exception, named in COLD_INSTALL_WORKFLOWS and
+ COLD_INSTALL_JOBS, and a new installer call site has to either restore the cache or
+ be added to one of those lists in a diff someone reads.
+ """
+ offenders = []
+ for name, jid, job in _jobs():
+ if name in COLD_INSTALL_WORKFLOWS or (name, jid) in COLD_INSTALL_JOBS:
+ continue
+ steps = job.get("steps") or []
+ runs_installer = any(_runs_installer(s) for s in steps)
+ if not runs_installer:
+ continue
+ restores = any(
+ "uv-cache-restore" in str(s.get("uses", ""))
+ or "install-unsloth-local" in str(s.get("uses", ""))
+ for s in steps
+ )
+ if not restores:
+ offenders.append(f"{name}:{jid}")
+ assert not offenders, (
+ "these jobs run the installer with no uv download cache, so every run downloads "
+ "every wheel again:\n " + "\n ".join(offenders)
+ )
+
+
+def test_every_uv_restore_is_paired_with_a_save_wired_to_it() -> None:
+ """A restore with no save fills nothing; a save reading the wrong id saves nothing.
+
+ The upload half is derived from the workflow's triggers rather than allowlisted, as
+ for the dist: a consumer-only lane (no `push`, no `schedule`) passes `save: 'false'`
+ and a producer must not.
+ """
+ offenders = []
+ for name, jid, job in _jobs():
+ steps = job.get("steps") or []
+ restore = next((s for s in steps if "uv-cache-restore" in str(s.get("uses", ""))), None)
+ save = next((s for s in steps if "uv-cache-save" in str(s.get("uses", ""))), None)
+ if restore is None and save is None:
+ continue
+ if restore is None or save is None:
+ offenders.append(f"{name}:{jid}: restore={restore is not None} save={save is not None}")
+ continue
+ ident = restore.get("id")
+ if not ident:
+ offenders.append(f"{name}:{jid}: the restore step has no id")
+ continue
+ with_ = save.get("with") or {}
+ for field in ("cache-hit", "key"):
+ if f"steps.{ident}.outputs.{field}" not in str(with_.get(field, "")):
+ offenders.append(f"{name}:{jid}: save does not take {field} from steps.{ident}")
+ installs = [i for i, s in enumerate(steps) if _runs_installer(s)]
+ if not installs:
+ offenders.append(f"{name}:{jid}: restores the uv cache but never runs an installer")
+ continue
+ if steps.index(restore) > min(installs):
+ offenders.append(f"{name}:{jid}: the restore runs after the install")
+ if steps.index(save) < max(installs):
+ offenders.append(f"{name}:{jid}: the save runs before the install")
+ uploads = str(with_.get("save", "true")) != "false"
+ if uploads and not _produces_on_main(name):
+ offenders.append(
+ f"{name}:{jid}: saves, but {name} never runs on main; pass save: 'false'"
+ )
+ if not uploads and _produces_on_main(name):
+ offenders.append(f"{name}:{jid}: passes save: 'false', but {name} runs on main")
+ assert not offenders, "\n ".join(["broken uv cache wiring:"] + offenders)
+
+
[email protected]("name", COLD_INSTALL_WORKFLOWS)
+def test_cold_install_lanes_never_adopt_the_uv_actions(name: str) -> None:
+ path = WORKFLOWS / name
+ if not path.exists():
+ pytest.skip(f"{name} no longer exists")
+ assert "uv-cache-" not in path.read_text(
+ encoding = "utf-8"
+ ), f"{name} restores a warm uv cache; a cached cold-install test proves nothing"
+
+
[email protected]("name,jid", COLD_INSTALL_JOBS)
+def test_cold_install_jobs_never_adopt_the_uv_actions(name: str, jid: str) -> None:
+ doc = yaml.safe_load((WORKFLOWS / name).read_text(encoding = "utf-8"))
+ job = (doc.get("jobs") or {}).get(jid)
+ assert job is not None, f"{name} no longer has job {jid}; update COLD_INSTALL_JOBS"
+ offenders = [
+ str(s.get("uses", ""))
+ for s in job.get("steps") or []
+ if "uv-cache-" in str(s.get("uses", ""))
+ ]
+ assert not offenders, f"{name}:{jid} is a deliberate cold-install lane: {offenders}"
+
+
+def test_the_uv_actions_are_actually_used_directly() -> None:
+ """The Windows jobs are the reason the pair exists; if none calls it, it is dead code."""
+ direct = [
+ p.name
+ for p in WORKFLOWS.glob("*.yml")
+ if "uv-cache-restore" in p.read_text(encoding = "utf-8")
+ ]
+ assert (
+ len(direct) >= 4
+ ), f"only {len(direct)} workflows call uv-cache-restore directly: {direct}"