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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Docker publish: keep the tag list to core, latest, studio, releases and dated nightly pins
Daniel Hancc0cdab40eef
diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.ymlindex bbd1bcea3a7..c083fc07549 100644--- a/.github/workflows/docker-publish.yml+++ b/.github/workflows/docker-publish.yml@@ -56,12 +56,7 @@ env:# at all. The accepted cost is that two main commits can race to retag :core/:latest,# which is self-correcting on the next push, where a cancelled run leaves that commit# with no image at all. Each published image is still internally coherent: the digest-# handoff and the smoke test resolve a :core-sha-/:sha- tag rather than tags[0], and-# then verify that the manifest behind it holds the arches THIS run pushed. That last-# step is the load-bearing one, because the sha tag is only immutable across COMMITS:-# a branch push and a lightweight v* tag push at one commit produce the same short-# sha, and the concurrency group is keyed on the ref, so those two runs never wait for-# each other and both write that name.+# handoff and the smoke test resolve this run's own tag, not tags[0], and verify it.# tests/studio/test_main_runs_survive_merge_bursts.py enforces this shape.concurrency:group: docker-publish-${{ github.ref }}-${{ github.ref == 'refs/heads/main' && github.sha || '' }}@@ -78,12 +73,29 @@ jobs:timeout-minutes: 5permissions:contents: read+ actions: readoutputs:+ # computed once, so a rerun of failed jobs keeps the same date+ pin_date: ${{ steps.pin.outputs.date }}llama_tag: ${{ steps.llama.outputs.tag }}unsloth_ref: ${{ steps.unsloth_ref.outputs.ref }}zoo_ref: ${{ steps.zoo_ref.outputs.ref }}notebooks_commit: ${{ steps.notebooks.outputs.commit }}steps:+ - name: Date of this run, for the nightly pins+ id: pin+ env:+ GH_TOKEN: ${{ github.token }}+ run: |+ # created_at is fixed at the first attempt: a late rerun cannot claim today's pin.+ created="$(gh api "repos/${{ github.repository }}/actions/runs/${{ github.run_id }}" --jq .created_at || true)"+ case "$created" in+ [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]T*) ;;+ *) echo "::error::Could not read this run's creation time (got '${created}')"; exit 1 ;;+ esac+ day="${created%%T*}"+ echo "date=${day//-/.}" >> "$GITHUB_OUTPUT"+- name: Resolve llama.cpp prebuilt tagid: llamaenv:@@ -272,7 +284,7 @@ jobs:merge:runs-on: ubuntu-latest- needs: build+ needs: [prepare, build]timeout-minutes: 15permissions:contents: read@@ -306,14 +318,33 @@ jobs:# dispatch, else a feature ref overwrites :core with non-main bitstype=raw,value=core,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.event.inputs.unsloth_ref == '' && (github.event.inputs.unsloth_zoo_ref == '' || github.event.inputs.unsloth_zoo_ref == 'main') && (github.event.inputs.notebooks_ref == '' || github.event.inputs.notebooks_ref == 'main') && github.event.inputs.llama_prebuilt_tag == '' }}type=ref,event=tag,prefix=core-- type=schedule,pattern=core-nightly- type=sha,prefix=core-sha-,format=short+ type=schedule,pattern=core-nightly-${{ needs.prepare.outputs.pin_date }}+ type=raw,value=core-build-${{ github.run_id }}- name: Create multi-arch manifestworking-directory: /tmp/digestsrun: |- docker buildx imagetools create \- $(jq -cr '.tags | map("-t " + .) | join(" ")' <<<"$DOCKER_METADATA_OUTPUT_JSON") \+ # A dated pin is immutable: a rerun must not replace an existing one.+ TAGS=""+ for t in $(jq -r '.tags[]' <<<"$DOCKER_METADATA_OUTPUT_JSON"); do+ name="${t##*:}"+ case "$name" in+ nightly-[0-9]*|core-nightly-[0-9]*)+ # Only 404 frees the name; 000/429/5xx must not become an overwrite.+ for i in 1 2 3 4 5; do+ code="$(curl -sS -o /dev/null -w '%{http_code}' "https://hub.docker.com/v2/repositories/${{ env.IMAGE_NAME }}/tags/${name}" || true)"+ case "$code" in 200|404) break ;; esac+ echo "probe of ${t} returned HTTP ${code} (attempt $i)"; sleep 15+ done+ case "$code" in+ 200) echo "::notice::${t} already exists and stays as it is"; continue ;;+ 404) ;;+ *) echo "::error::Cannot tell whether ${t} exists (HTTP ${code}); not risking an overwrite"; exit 1 ;;+ esac ;;+ esac+ TAGS="${TAGS} -t ${t}"+ done+ docker buildx imagetools create ${TAGS} \$(printf '${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@sha256:%s ' *)- name: Inspect the result@@ -327,19 +358,11 @@ jobs:id: manifest_digestworking-directory: /tmp/digestsrun: |- # NOT tags[0]: metadata-action sorts by priority (raw=200 above sha=100), so- # on a main push that is the mutable :core, which an unserialised second run- # can retag between the manifest creation and this inspection.- TAG="$(jq -r '([.tags[] | select(contains(":core-sha-"))] | first) // .tags[0]' <<<"$DOCKER_METADATA_OUTPUT_JSON")"+ # NOT tags[0]: on a main push that is the mutable :core, retagged by racing runs.+ TAG="$(jq -r '([.tags[] | select(contains(":core-build-"))] | first) // .tags[0]' <<<"$DOCKER_METADATA_OUTPUT_JSON")"DIGEST="$(docker buildx imagetools inspect "$TAG" --format '{{json .Manifest.Digest}}' | tr -d '"')"test -n "$DIGEST"- # :core-sha- is immutable across COMMITS, which is the only case the tag- # choice above defends against. It is NOT unique across REFS: a branch push- # and a lightweight v* tag push at the same commit produce the same short- # sha, and the concurrency group is keyed on the ref, so the two runs are- # never serialised against each other and both write this name. Confirm the- # manifest we are about to hand to build-studio really is the one this run- # pushed, because baking another run's base image is silent otherwise.+ # Confirm it holds what this run pushed: baking another run's base is silent.REF="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${DIGEST}"CHILDREN="$(docker buildx imagetools inspect --raw "$REF" | jq -r '.manifests[]?.digest')"# A build leg does not push a bare image manifest: with provenance and SBOM@@ -444,7 +467,7 @@ jobs:merge-studio:runs-on: ubuntu-latest- needs: build-studio+ needs: [prepare, build-studio]timeout-minutes: 15permissions:contents: read@@ -478,14 +501,33 @@ jobs:type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.event.inputs.unsloth_ref == '' && (github.event.inputs.unsloth_zoo_ref == '' || github.event.inputs.unsloth_zoo_ref == 'main') && (github.event.inputs.notebooks_ref == '' || github.event.inputs.notebooks_ref == 'main') && github.event.inputs.llama_prebuilt_tag == '' }}type=raw,value=studio,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.event.inputs.unsloth_ref == '' && (github.event.inputs.unsloth_zoo_ref == '' || github.event.inputs.unsloth_zoo_ref == 'main') && (github.event.inputs.notebooks_ref == '' || github.event.inputs.notebooks_ref == 'main') && github.event.inputs.llama_prebuilt_tag == '' }}type=ref,event=tag- type=schedule,pattern=nightly- type=sha,prefix=sha-,format=short+ type=schedule,pattern=nightly-${{ needs.prepare.outputs.pin_date }}+ type=raw,value=build-${{ github.run_id }}- name: Create multi-arch manifestworking-directory: /tmp/digestsrun: |- docker buildx imagetools create \- $(jq -cr '.tags | map("-t " + .) | join(" ")' <<<"$DOCKER_METADATA_OUTPUT_JSON") \+ # A dated pin is immutable: a rerun must not replace an existing one.+ TAGS=""+ for t in $(jq -r '.tags[]' <<<"$DOCKER_METADATA_OUTPUT_JSON"); do+ name="${t##*:}"+ case "$name" in+ nightly-[0-9]*|core-nightly-[0-9]*)+ # Only 404 frees the name; 000/429/5xx must not become an overwrite.+ for i in 1 2 3 4 5; do+ code="$(curl -sS -o /dev/null -w '%{http_code}' "https://hub.docker.com/v2/repositories/${{ env.IMAGE_NAME }}/tags/${name}" || true)"+ case "$code" in 200|404) break ;; esac+ echo "probe of ${t} returned HTTP ${code} (attempt $i)"; sleep 15+ done+ case "$code" in+ 200) echo "::notice::${t} already exists and stays as it is"; continue ;;+ 404) ;;+ *) echo "::error::Cannot tell whether ${t} exists (HTTP ${code}); not risking an overwrite"; exit 1 ;;+ esac ;;+ esac+ TAGS="${TAGS} -t ${t}"+ done+ docker buildx imagetools create ${TAGS} \$(printf '${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@sha256:%s ' *)- name: Inspect the result@@ -499,10 +541,7 @@ jobs:id: studio_manifest_digestworking-directory: /tmp/digestsrun: |- # Same reasoning as the base merge: :sha- is shared by every ref sitting on- # this commit, so resolve it once here and hand the smoke test an immutable- # digest rather than a name another run can retag under it.- TAG="$(jq -r '([.tags[] | select(contains(":sha-"))] | first) // .tags[0]' <<<"$DOCKER_METADATA_OUTPUT_JSON")"+ TAG="$(jq -r '([.tags[] | select(contains(":build-"))] | first) // .tags[0]' <<<"$DOCKER_METADATA_OUTPUT_JSON")"DIGEST="$(docker buildx imagetools inspect "$TAG" --format '{{json .Manifest.Digest}}' | tr -d '"')"test -n "$DIGEST"REF="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${DIGEST}"@@ -592,11 +631,7 @@ jobs:# with the merge jobs' gates.- name: Pull and smoke-test the base imagerun: |- # By digest, not by name. Every ref sitting on this commit publishes the- # same :core-sha- tag, and those runs are in different concurrency groups,- # so a name resolved here can be another run's image. merge already had to- # resolve this digest to hand build-studio a base, and it verified that the- # manifest is the one it pushed.+ # By digest: the handle tag is gone once cleanup ran.REF="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.merge.outputs.digest }}"echo "smoke-testing $REF"docker pull "$REF"@@ -621,3 +656,55 @@ jobs:[ "$ok_studio" = 1 ] || { echo "Studio /api/health never went healthy"; exit 1; }[ "$ok_jupyter" = 1 ] || { echo "Jupyter /login never responded"; exit 1; }echo "Studio + Jupyter healthy"++ # Namespace-scoped route: the legacy /v2/repositories path rejects the organization+ # token. A dispatch with an overridden input keeps its handles, its only names.+ cleanup:+ needs: [merge, merge-studio, hub-readme, smoke-test]+ if: ${{ always() && (github.event_name != 'workflow_dispatch' || (github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.event.inputs.unsloth_ref == '' && (github.event.inputs.unsloth_zoo_ref == '' || github.event.inputs.unsloth_zoo_ref == 'main') && (github.event.inputs.notebooks_ref == '' || github.event.inputs.notebooks_ref == 'main') && github.event.inputs.llama_prebuilt_tag == '')) }}+ runs-on: ubuntu-latest+ timeout-minutes: 10+ permissions:+ contents: read+ steps:+ - name: Remove this run's handle tags, prune old nightly pins+ env:+ NIGHTLY_KEEP_DAYS: "60"+ run: |+ HUB="https://hub.docker.com/v2/namespaces/${IMAGE_NAME%%/*}/repositories/${IMAGE_NAME#*/}"+ TOKEN="$(curl -sS -X POST https://hub.docker.com/v2/auth/token \+ -H 'Content-Type: application/json' \+ -d "{\"identifier\": \"${{ env.REGISTRY_USERNAME }}\", \"secret\": \"${{ secrets.DOCKER_API_KEY }}\"}" \+ | python3 -c 'import json,sys; print(json.load(sys.stdin).get("access_token",""))')"+ if [ -z "$TOKEN" ]; then+ echo "::error::Could not exchange DOCKER_API_KEY for a Hub API token; handle tags of run ${{ github.run_id }} were not removed."+ exit 1+ fi+ failed=0+ drop() {+ code="$(curl -sS -o /dev/null -w '%{http_code}' -X DELETE "${HUB}/tags/$1" -H "Authorization: Bearer ${TOKEN}")"+ case "$code" in+ 204|404) echo "removed ${IMAGE_NAME}:$1 (HTTP ${code})" ;;+ *) echo "::error::${IMAGE_NAME}:$1 not removed (HTTP ${code})"; failed=1 ;;+ esac+ }+ drop "core-build-${{ github.run_id }}"+ drop "build-${{ github.run_id }}"+ if [ "${{ github.event_name }}" = "schedule" ]; then+ cutoff="$(date -u -d "-${NIGHTLY_KEEP_DAYS} days" +%Y.%m.%d)"+ url="${HUB}/tags?page_size=100"+ names=""+ while [ -n "$url" ]; do+ page="$(curl -sS "$url" -H "Authorization: Bearer ${TOKEN}")"+ names="${names} $(jq -r '.results[]?.name' <<<"$page")"+ url="$(jq -r '.next // empty' <<<"$page")"+ done+ for name in $names; do+ case "$name" in+ nightly-[0-9][0-9][0-9][0-9].[0-9][0-9].[0-9][0-9]|core-nightly-[0-9][0-9][0-9][0-9].[0-9][0-9].[0-9][0-9])+ stamp="${name##*nightly-}"+ if [ "$stamp" \< "$cutoff" ]; then drop "$name"; fi ;;+ esac+ done+ fi+ test "$failed" = 0diff --git a/docker/DOCKERHUB.md b/docker/DOCKERHUB.mdindex 070cca211fc..c7bd1bb38e7 100644--- a/docker/DOCKERHUB.md+++ b/docker/DOCKERHUB.md@@ -10,7 +10,7 @@ Source: [`docker/`](https://github.com/unslothai/unsloth/tree/main/docker) in th|---|---|---|| `latest`, `studio` | Unsloth Studio web UI + JupyterLab + notebooks + key-only SSH | Most users. Train and chat in the browser. || `core` | Training stack + JupyterLab + notebooks, no Studio | Notebooks, scripts, CI, slimmer pulls. |-| `sha-<commit>`, `core-sha-<commit>` | The same two images, pinned to one commit of `main` | Reproducible runs. |+| `nightly-<YYYY.MM.DD>`, `core-nightly-<YYYY.MM.DD>` | The same two images, one immutable pin per daily rebuild, kept 60 days | Reproducible runs. || `<version>`, `core-<version>` | Release builds | Pin a release. |`latest` and `core` move with every push to `main` and on a daily rebuild. Both images are multi-arch: `linux/amd64` and `linux/arm64` (GH200, DGX Spark).diff --git a/tests/python/test_docker_publish_ref_freeze.py b/tests/python/test_docker_publish_ref_freeze.pyindex adac2550cf2..7344b0a6c70 100644--- a/tests/python/test_docker_publish_ref_freeze.py+++ b/tests/python/test_docker_publish_ref_freeze.py@@ -352,7 +352,7 @@ def test_the_exported_digest_comes_from_this_runs_tag(manifest_digest_step: str,bin_dir,'case "$4" in\n'f' --raw) printf "{_raw_index()}" ;;\n'- f" *core-sha-*) printf '\"{THIS_RUN_DIGEST}\"' ;;\n"+ f" *core-build-*) printf '\"{THIS_RUN_DIGEST}\"' ;;\n"f" *) printf '\"{OTHER_RUN_DIGEST}\"' ;;\n""esac\n",)@@ -362,7 +362,7 @@ def test_the_exported_digest_comes_from_this_runs_tag(manifest_digest_step: str,env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]env["GITHUB_OUTPUT"] = str(out)env["DOCKER_METADATA_OUTPUT_JSON"] = (- '{"tags":["' + IMAGE + ':core","' + IMAGE + ':core-sha-abc1234"]}'+ '{"tags":["' + IMAGE + ':core","' + IMAGE + ':core-build-123"]}')path = tmp_path / "digest_step.sh"path.write_text(_expand(manifest_digest_step), encoding = "utf-8")@@ -382,7 +382,9 @@ def test_the_exported_digest_comes_from_this_runs_tag(manifest_digest_step: str,@pytest.mark.skipif(shutil.which("jq") is None, reason = "needs jq")-def test_the_digest_export_still_works_without_a_sha_tag(manifest_digest_step: str, tmp_path: Path):+def test_the_digest_export_still_works_without_a_handle_tag(+ manifest_digest_step: str, tmp_path: Path+):bin_dir = tmp_path / "bin"_docker_stub(bin_dir,@@ -413,11 +415,7 @@ def test_the_digest_export_still_works_without_a_sha_tag(manifest_digest_step: s@pytest.mark.skipif(shutil.which("jq") is None, reason = "needs jq")def test_the_digest_export_refuses_another_runs_manifest(manifest_digest_step: str, tmp_path: Path):- """:core-sha- is immutable across COMMITS but not across REFS: a branch push and a- lightweight v* tag push at one commit produce the same short sha and land in- different concurrency groups, so both write this name and neither waits. If the- tag resolves to a manifest that does not contain the per-arch digests this run- pushed, the step has to fail rather than hand build-studio another run's base."""+ """Even under this run's own name, a manifest without the per-arch digests this run pushed must fail rather than hand build-studio another run's base."""bin_dir = tmp_path / "bin"# the tag now resolves to a manifest built from somebody else's arches, while# this run's own per-arch indexes still answer with their real children@@ -434,7 +432,7 @@ def test_the_digest_export_refuses_another_runs_manifest(manifest_digest_step: senv["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]env["GITHUB_OUTPUT"] = str(out)env["DOCKER_METADATA_OUTPUT_JSON"] = (- '{"tags":["' + IMAGE + ':core","' + IMAGE + ':core-sha-abc1234"]}'+ '{"tags":["' + IMAGE + ':core","' + IMAGE + ':core-build-123"]}')path = tmp_path / "digest_step.sh"path.write_text(_expand(manifest_digest_step), encoding = "utf-8")@@ -477,7 +475,7 @@ def test_the_digest_export_accepts_the_flattened_per_arch_indexes(env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]env["GITHUB_OUTPUT"] = str(out)env["DOCKER_METADATA_OUTPUT_JSON"] = (- '{"tags":["' + IMAGE + ':core","' + IMAGE + ':core-sha-abc1234"]}'+ '{"tags":["' + IMAGE + ':core","' + IMAGE + ':core-build-123"]}')path = tmp_path / "digest_step.sh"path.write_text(_expand(manifest_digest_step), encoding = "utf-8")diff --git a/tests/python/test_docker_publish_tag_scheme.py b/tests/python/test_docker_publish_tag_scheme.pynew file mode 100644index 00000000000..fcaaa1e55d8--- /dev/null+++ b/tests/python/test_docker_publish_tag_scheme.py@@ -0,0 +1,409 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0++"""The published tag list must stay short: :core, :latest, :studio, the release tags,+and one dated nightly pin per image. Per-run handles are removed by cleanup."""++from __future__ import annotations++import os+import subprocess+from pathlib import Path++import pytest+import yaml++REPO_ROOT = Path(__file__).resolve().parents[2]+WORKFLOW = REPO_ROOT / ".github" / "workflows" / "docker-publish.yml"+HUB_README = REPO_ROOT / "docker" / "DOCKERHUB.md"++[email protected](scope = "module")+def doc() -> dict:+ return yaml.safe_load(WORKFLOW.read_text(encoding = "utf-8"))+++def _tag_rules(doc: dict, job: str) -> list[str]:+ steps = [s for s in doc["jobs"][job]["steps"] if s.get("id") == "meta"]+ assert len(steps) == 1+ return [+ l.strip()+ for l in steps[0]["with"]["tags"].splitlines()+ if l.strip() and not l.strip().startswith("#")+ ]+++def test_no_per_commit_tags_are_published(doc: dict):+ text = WORKFLOW.read_text(encoding = "utf-8")+ assert "type=sha" not in text, "sha-<commit> tags are back on every push"+ for job in ("merge", "merge-studio"):+ assert not any(+ "nightly" in r and "pin_date" not in r for r in _tag_rules(doc, job)+ ), f"{job} still writes a mutable nightly tag"+++ ("job", "handle", "pin"),+ [+ (+ "merge",+ "type=raw,value=core-build-${{ github.run_id }}",+ "type=schedule,pattern=core-nightly-${{ needs.prepare.outputs.pin_date }}",+ ),+ (+ "merge-studio",+ "type=raw,value=build-${{ github.run_id }}",+ "type=schedule,pattern=nightly-${{ needs.prepare.outputs.pin_date }}",+ ),+ ],+)+def test_each_image_has_a_per_run_handle_and_a_dated_pin(+ doc: dict, job: str, handle: str, pin: str+):+ rules = _tag_rules(doc, job)+ assert handle in rules, f"{job} lost the per-run handle the digest handoff resolves"+ assert pin in rules, f"{job} lost its dated nightly pin"+ assert "prepare" in doc["jobs"][job]["needs"]+ assert doc["jobs"]["prepare"]["outputs"]["pin_date"] == "${{ steps.pin.outputs.date }}"+++def _pin_step(doc: dict) -> dict:+ return [s for s in doc["jobs"]["prepare"]["steps"] if s.get("id") == "pin"][0]+++def _run_pin(step: dict, tmp_path: Path, *, gh: str) -> tuple[subprocess.CompletedProcess, str]:+ bin_dir = tmp_path / "bin"+ bin_dir.mkdir()+ (bin_dir / "gh").write_text("#!/usr/bin/env bash\n" + gh + "\n", encoding = "utf-8")+ (bin_dir / "gh").chmod(0o755)+ out = tmp_path / "output"+ out.write_text("", encoding = "utf-8")+ script = (+ step["run"]+ .replace("${{ github.repository }}", "unslothai/unsloth")+ .replace("${{ github.run_id }}", "424242")+ )+ assert "${{" not in script+ env = dict(os.environ)+ env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]+ env["GITHUB_OUTPUT"] = str(out)+ res = subprocess.run(+ ["bash", "-e", "-c", script], capture_output = True, text = True, env = env, timeout = 60+ )+ return res, out.read_text(encoding = "utf-8")+++def test_the_pin_date_is_the_run_creation_date(doc: dict, tmp_path: Path):+ """created_at is fixed at the first attempt, unlike run_started_at and the clock, so a late rerun cannot claim today's pin with an older commit."""+ step = _pin_step(doc)+ assert doc["jobs"]["prepare"]["permissions"].get("actions") == "read"+ assert step["env"]["GH_TOKEN"] == "${{ github.token }}"+ assert "actions/runs/${{ github.run_id }}" in step["run"]+ assert "date -u" not in step["run"]+ res, out = _run_pin(+ step,+ tmp_path,+ gh = "echo \"$*\" >&2; printf '2026-09-05T18:17:03Z\\n'",+ )+ assert res.returncode == 0, res.stdout + res.stderr+ assert out == "date=2026.09.05\n"+ assert "repos/unslothai/unsloth/actions/runs/424242 --jq .created_at" in res.stderr++[email protected]("gh", ["exit 1", "printf ''", "printf 'null'"])+def test_an_unreadable_creation_time_fails_prepare(doc: dict, tmp_path: Path, gh: str):+ res, out = _run_pin(_pin_step(doc), tmp_path, gh = gh)+ assert res.returncode != 0+ assert "::error::" in res.stdout+ assert out == ""+++def test_the_digest_export_resolves_the_handle(doc: dict):+ for job, needle in (("merge", ":core-build-"), ("merge-studio", ":build-")):+ step = [s for s in doc["jobs"][job]["steps"] if s.get("name") == "Export manifest digest"][+ 0+ ]["run"]+ assert f'select(contains("{needle}"))' in step+++def test_the_hub_readme_lists_the_pins_not_the_handles():+ text = HUB_README.read_text(encoding = "utf-8")+ assert "core-nightly-<YYYY.MM.DD>" in text+ for stale in ("sha-<commit>", "core-sha-", "build-<run_id>"):+ assert stale not in text++[email protected](scope = "module")+def cleanup_job(doc: dict) -> dict:+ assert "cleanup" in doc["jobs"], "the handle cleanup job is missing"+ return doc["jobs"]["cleanup"]+++def test_cleanup_runs_after_everything_except_an_overridden_dispatch(cleanup_job: dict, doc: dict):+ """A default-input dispatch on the default branch publishes the stable tags, so its handles are not its only names and must go like a push's."""+ assert set(cleanup_job["needs"]) == {"merge", "merge-studio", "hub-readme", "smoke-test"}+ cond = cleanup_job["if"]+ assert cond.startswith("${{ always() && (github.event_name != 'workflow_dispatch' || (")+ gate = doc["jobs"]["hub-readme"]["if"].strip().removeprefix("${{").removesuffix("}}").strip()+ assert gate in cond, "the dispatch exception must be the stable-tag gate itself"+++def _manifest_step(doc: dict, job: str) -> str:+ return [s for s in doc["jobs"][job]["steps"] if s.get("name") == "Create multi-arch manifest"][+ 0+ ]["run"]+++def _run_manifest(+ step: str,+ tmp_path: Path,+ *,+ existing: list[str],+ tags: list[str],+ probe_code: str = "404",+) -> tuple[subprocess.CompletedProcess, str]:+ bin_dir = tmp_path / "bin"+ bin_dir.mkdir()+ log = tmp_path / "docker.log"+ (bin_dir / "sleep").write_text("#!/usr/bin/env bash\n", encoding = "utf-8")+ (bin_dir / "sleep").chmod(0o755)+ (bin_dir / "docker").write_text(+ "#!/usr/bin/env bash\n" + f"printf '%s\\n' \"$*\" >> {log}\n", encoding = "utf-8"+ )+ (bin_dir / "docker").chmod(0o755)+ probes = tmp_path / "curl.log"+ (bin_dir / "curl").write_text(+ "#!/usr/bin/env bash\n"+ f'echo "$*" >> {probes}\n'+ 'case "$*" in\n'+ + "".join(f" */tags/{e}) printf '200' ;;\n" for e in existing)+ # curl prints 000 and exits 7 when the connection fails+ + (+ " *) printf '000'; exit 7 ;;\n"+ if probe_code == "000"+ else f" *) printf '{probe_code}' ;;\n"+ )+ + "esac\n",+ encoding = "utf-8",+ )+ (bin_dir / "curl").chmod(0o755)+ digests = tmp_path / "digests"+ digests.mkdir()+ (digests / ("a" * 64)).write_text("", encoding = "utf-8")+ script = step.replace("${{ env.REGISTRY }}", "docker.io").replace(+ "${{ env.IMAGE_NAME }}", "unsloth/unsloth"+ )+ assert "${{" not in script+ env = dict(os.environ)+ env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]+ env["DOCKER_METADATA_OUTPUT_JSON"] = (+ '{"tags": [' + ", ".join(f'"docker.io/unsloth/unsloth:{t}"' for t in tags) + "]}"+ )+ res = subprocess.run(+ ["bash", "-e", "-c", script],+ capture_output = True,+ text = True,+ env = env,+ cwd = str(digests),+ timeout = 60,+ )+ return res, log.read_text(encoding = "utf-8") if log.exists() else ""+++def _probes(tmp_path: Path) -> list[str]:+ path = tmp_path / "curl.log"+ return path.read_text(encoding = "utf-8").splitlines() if path.exists() else []++[email protected]("job", ["merge", "merge-studio"])+def test_an_existing_dated_pin_is_never_replaced(doc: dict, job: str, tmp_path: Path):+ step = _manifest_step(doc, job)+ res, log = _run_manifest(+ step,+ tmp_path,+ existing = ["core-nightly-2026.09.06"],+ tags = ["core", "core-nightly-2026.09.06", "core-build-777"],+ )+ assert res.returncode == 0, res.stdout + res.stderr+ assert "-t docker.io/unsloth/unsloth:core " in log+ assert "-t docker.io/unsloth/unsloth:core-build-777 " in log+ assert "core-nightly-2026.09.06" not in log+ assert "already exists" in res.stdout++[email protected]("job", ["merge", "merge-studio"])+def test_a_new_dated_pin_is_created(doc: dict, job: str, tmp_path: Path):+ step = _manifest_step(doc, job)+ res, log = _run_manifest(+ step,+ tmp_path,+ existing = [],+ tags = ["latest", "nightly-2026.09.06", "build-777"],+ )+ assert res.returncode == 0, res.stdout + res.stderr+ for t in ("latest", "nightly-2026.09.06", "build-777"):+ assert f"-t docker.io/unsloth/unsloth:{t} " in log+ assert len(_probes(tmp_path)) == 1, "only the dated pin is probed, once"++[email protected]("job", ["merge", "merge-studio"])[email protected]("code", ["000", "429", "503"])+def test_an_unanswered_probe_stops_the_merge(doc: dict, job: str, code: str, tmp_path: Path):+ """Anything but 404 used to count as absent, and bash -e is off inside the probe's condition, so a transport failure or a 429 became an overwrite."""+ step = _manifest_step(doc, job)+ res, log = _run_manifest(+ step,+ tmp_path,+ existing = [],+ tags = ["latest", "nightly-2026.09.06", "build-777"],+ probe_code = code,+ )+ assert res.returncode != 0+ assert f"(HTTP {code})" in res.stdout+ assert "::error::" in res.stdout+ assert log == "", "no manifest may be written while the pin's state is unknown"+ assert len(_probes(tmp_path)) == 5, "the probe is retried before giving up"+++def _run_cleanup(+ step: str,+ tmp_path: Path,+ *,+ event: str,+ delete_code: str = "204",+ tags: list[str] | None = None,+ second_page: list[str] | None = None,+ today: str = "2026.09.06",+) -> tuple[subprocess.CompletedProcess, str]:+ bin_dir = tmp_path / "bin"+ bin_dir.mkdir()+ log = tmp_path / "curl.log"+ listing = tmp_path / "tags.json"+ page2 = tmp_path / "tags2.json"+ nxt = (+ ', "next": "https://hub.docker.com/v2/namespaces/unsloth/repositories/unsloth/tags?page=2&page_size=100"'+ if second_page+ else ', "next": null'+ )+ listing.write_text(+ '{"results": [' + ", ".join(f'{{"name": "{t}"}}' for t in (tags or [])) + "]" + nxt + "}",+ encoding = "utf-8",+ )+ page2.write_text(+ '{"results": ['+ + ", ".join(f'{{"name": "{t}"}}' for t in (second_page or []))+ + '], "next": null}',+ encoding = "utf-8",+ )+ (bin_dir / "curl").write_text(+ "#!/usr/bin/env bash\n"+ f"printf '%s\\n' \"$*\" >> {log}\n"+ 'case "$*" in\n'+ ' *auth/token*) printf \'{"access_token": "tok"}\' ;;\n'+ f" *-X\\ DELETE*) printf '{delete_code}' ;;\n"+ f" *page=2*) cat {page2} ;;\n"+ f" *) cat {listing} ;;\n"+ "esac\n",+ encoding = "utf-8",+ )+ (bin_dir / "curl").chmod(0o755)+ (bin_dir / "date").write_text(+ "#!/usr/bin/env bash\n"+ f'/bin/date -u -d "{today.replace(".", "-")} -${{NIGHTLY_KEEP_DAYS}} days" +%Y.%m.%d\n',+ encoding = "utf-8",+ )+ (bin_dir / "date").chmod(0o755)+ script = (+ step.replace("${{ secrets.DOCKER_API_KEY }}", "not-a-secret")+ .replace("${{ env.REGISTRY_USERNAME }}", "unsloth")+ .replace("${{ github.run_id }}", "777")+ .replace("${{ github.event_name }}", event)+ )+ assert "${{" not in script, "unexpanded expression in the cleanup step"+ env = dict(os.environ)+ env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]+ env.update(IMAGE_NAME = "unsloth/unsloth", NIGHTLY_KEEP_DAYS = "60")+ res = subprocess.run(+ ["bash", "-e", "-c", script],+ capture_output = True,+ text = True,+ env = env,+ cwd = str(tmp_path),+ timeout = 60,+ )+ return res, log.read_text(encoding = "utf-8") if log.exists() else ""+++def test_a_push_removes_both_handles_on_the_namespace_route(cleanup_job: dict, tmp_path: Path):+ step = cleanup_job["steps"][-1]["run"]+ res, log = _run_cleanup(step, tmp_path, event = "push")+ assert res.returncode == 0, res.stdout + res.stderr+ deletes = [l for l in log.splitlines() if "-X DELETE" in l]+ assert [l.split("/tags/")[1].split(" ")[0] for l in deletes] == ["core-build-777", "build-777"]+ assert all("/v2/namespaces/unsloth/repositories/unsloth/tags/" in l for l in deletes)+ assert (+ "/v2/repositories/" not in log+ ), "the legacy route answers every organization token with 403"+ assert "?page_size" not in log, "a push must not prune pins"+++def test_a_missing_handle_is_not_a_failure(cleanup_job: dict, tmp_path: Path):+ """A failed merge never created the handle, so 404 on delete is expected."""+ step = cleanup_job["steps"][-1]["run"]+ res, _ = _run_cleanup(step, tmp_path, event = "push", delete_code = "404")+ assert res.returncode == 0, res.stdout + res.stderr+++def test_a_handle_that_survives_fails_the_job(cleanup_job: dict, tmp_path: Path):+ step = cleanup_job["steps"][-1]["run"]+ res, _ = _run_cleanup(step, tmp_path, event = "push", delete_code = "403")+ assert res.returncode != 0+ assert "not removed" in res.stdout + res.stderr+++def test_the_daily_run_prunes_only_old_dated_pins(cleanup_job: dict, tmp_path: Path):+ step = cleanup_job["steps"][-1]["run"]+ tags = [+ "latest",+ "core",+ "studio",+ "core-v2026.9.1",+ "stable",+ "nightly-2026.09.05",+ "core-nightly-2026.09.05",+ "nightly-2026.07.01",+ "core-nightly-2026.07.01",+ "nightly",+ "core-nightly",+ "2026.5.9-pt2.10.0-vllm-0.16.0-cu12.8-studio-release-v0.1.43-beta-2026-MAY-31",+ ]+ res, log = _run_cleanup(step, tmp_path, event = "schedule", tags = tags)+ assert res.returncode == 0, res.stdout + res.stderr+ deleted = [l.split("/tags/")[1].split(" ")[0] for l in log.splitlines() if "-X DELETE" in l]+ assert deleted == [+ "core-build-777",+ "build-777",+ "nightly-2026.07.01",+ "core-nightly-2026.07.01",+ ], deleted+++def test_the_prune_follows_every_page(cleanup_job: dict, tmp_path: Path):+ """The listing is newest first and two pins a day pass 100 tags inside the retention window, so expired pins live on pages a single request never returns."""+ step = cleanup_job["steps"][-1]["run"]+ res, log = _run_cleanup(+ step,+ tmp_path,+ event = "schedule",+ tags = ["latest", "nightly-2026.09.05"],+ second_page = ["nightly-2026.06.01", "core-nightly-2026.06.01", "stable"],+ )+ assert res.returncode == 0, res.stdout + res.stderr+ deleted = [l.split("/tags/")[1].split(" ")[0] for l in log.splitlines() if "-X DELETE" in l]+ assert deleted == [+ "core-build-777",+ "build-777",+ "nightly-2026.06.01",+ "core-nightly-2026.06.01",+ ], deleted+ assert log.count("page_size=100") == 2, "the second page was not fetched"