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.

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.yml
index 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: 5
permissions:
contents: read
+ actions: read
outputs:
+ # 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 tag
id: llama
env:
@@ -272,7 +284,7 @@ jobs:
merge:
runs-on: ubuntu-latest
- needs: build
+ needs: [prepare, build]
timeout-minutes: 15
permissions:
contents: read
@@ -306,14 +318,33 @@ jobs:
# dispatch, else a feature ref overwrites :core with non-main bits
type=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 manifest
working-directory: /tmp/digests
run: |
- 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_digest
working-directory: /tmp/digests
run: |
- # 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: 15
permissions:
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 manifest
working-directory: /tmp/digests
run: |
- 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_digest
working-directory: /tmp/digests
run: |
- # 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 image
run: |
- # 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" = 0
diff --git a/docker/DOCKERHUB.md b/docker/DOCKERHUB.md
index 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.py
index 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: s
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")
@@ -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.py
new file mode 100644
index 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"