release-update-docker-image-pin

Release: Update Docker Image Pin

Pins the Linux manywheel builder docker images that the binary build workflows in pytorch/pytorch use, so a release branch builds against a fixed, reproducible toolchain instead of the floating tags that main tracks (e.g. pytorch/manylinux2_28-builder:cuda12.6). The pin lives in the workflow generator, so it survives regenerate.sh and the lint "generated files are up to date" check.

This skill operates on a pytorch/pytorch checkout (usually a release/X.Y branch), even though the skill itself lives in test-infra.

Inputs

The release version is the primary argument. If it was not supplied when the skill was invoked, ask for it before making any changes -- do not guess. Confirm it matches the checkout with cut -d'.' -f1-2 version.txt.

When to use this skill

Use when the user asks to:

• Pin / re-pin the manywheel (builder) docker images for a release
• Update or bump DOCKER_IMAGE_PIN
• Freeze the docker image the nightly/release binaries build with
• Refresh the docker image pin after the release branch's .ci/docker changed

Background: how the pin maps to a published image

When the builder images are built (.github/workflows/build-manywheel-images.yml and build-manywheel-images-s390x.yml via the binary-docker-build action), each image is pushed with several tags, including:

docker.io/pytorch/<image>:<prefix>-${CI_FOLDER_SHA}

where CI_FOLDER_SHA="$(git rev-parse HEAD:.ci/docker)" -- the git tree hash of the .ci/docker directory. This is exactly the value test-infra/.github/actions/calculate-docker-image computes at runtime. Pinning simply freezes that hash as a literal so the release stops tracking floating tags. Example published image:

pytorch/manylinux2_28_aarch64-builder:cpu-aarch64-<CI_FOLDER_SHA>

Only linux manywheel builds run inside these containers, so only the linux images are pinned. Windows and macOS keep the plain tag prefix.

Target

Repo: pytorch/pytorch (the release branch you are pinning).

Instructions

Step 1: Resolve inputs

Resolve the Release version and pytorch/pytorch path from the Inputs table above. If the release version was not provided, ask for it now. Confirm the checkout is on the matching branch and the version agrees:

cut -d'.' -f1-2 version.txt   # must equal the release version, e.g. 2.13
git rev-parse --abbrev-ref HEAD   # should be release/<version>

Step 2: Compute the pin hash

From the root of the pytorch/pytorch checkout, on the release branch:

git rev-parse HEAD:.ci/docker

This 40-char hash is the new DOCKER_IMAGE_PIN. It is the same value the builder images are published under. Do NOT invent or hand-edit it.

If the user instead points at a specific published image tag (e.g. from a known good nightly on https://hud.pytorch.org), use the suffix from that tag and verify it equals the git rev-parse output above; they should match on a fresh release cut.

Step 3 (optional): Verify the image exists

If the user wants confirmation, check that the tag exists on Docker Hub (a human can open the URL; automated egress may be restricted):

https://hub.docker.com/r/pytorch/manylinux2_28_aarch64-builder/tags?name=cpu-aarch64-<HASH>

Step 4: Update or add DOCKER_IMAGE_PIN

Open .github/scripts/generate_binary_build_matrix.py.

If the pin block already exists (re-pinning), just replace the hash:

DOCKER_IMAGE_PIN = "<NEW_40_CHAR_HASH>"

If pinning for the first time on this release branch, add the block right after the WHEEL_CONTAINER_IMAGES dict, and route the wheel tag prefix through the helper. Add:

# RELEASE-ONLY: pin the manywheel builder images to a fixed build so the release
# uses a reproducible toolchain instead of main's floating tags. The suffix is
# the .ci/docker tree hash (`git rev-parse HEAD:.ci/docker`), i.e. the same tag
# .github/actions/binary-docker-build publishes. Only linux manywheel builds run
# inside these containers, so only those images are pinned.
DOCKER_IMAGE_PIN = "<NEW_40_CHAR_HASH>"
MANYWHEEL_OSES = ("linux", "linux-aarch64", "linux-s390x")


def wheel_container_image_tag_prefix(arch_version: str, os: str) -> str:
    tag_prefix = WHEEL_CONTAINER_IMAGES[arch_version].split(":")[1]
    if os in MANYWHEEL_OSES:
        return f"{tag_prefix}-{DOCKER_IMAGE_PIN}"
    return tag_prefix

Then replace BOTH occurrences of the inline tag-prefix computation in generate_wheels_matrix with a call to the helper:

                        "container_image_tag_prefix": wheel_container_image_tag_prefix(
                            arch_version, os
                        ),

(The original reads WHEEL_CONTAINER_IMAGES[arch_version].split(":")[1].)

Step 5: Regenerate the workflows

Run the generator in release mode from the repo root:

RELEASE_VERSION_TAG=<RELEASE_VERSION> python3 .github/scripts/generate_ci_workflows.py

(Equivalent: RELEASE_VERSION_TAG=<ver> ./.github/regenerate.sh.)

Step 6: Verify

# Only the three linux manywheel files should change:
git status --short .github/workflows/generated-*.yml

# Every linux builder image should carry the new hash; none floating:
grep -rhE "image: pytorch/manylinux" .github/workflows/generated-linux-*.yml | grep -v "<HASH>" || echo "none floating (good)"

# Windows/macOS must be unchanged (plain cpu / cuda12.6 prefixes):
grep -nE "docker_image_tag_prefix:" .github/workflows/generated-macos-arm64-binary-wheel-nightly.yml | grep -v '\${{'

Then confirm idempotency -- regenerating a second time must produce byte-identical output (this is what the lint up-to-date check enforces):

md5sum .github/workflows/generated-linux-*.yml > /tmp/a
RELEASE_VERSION_TAG=<ver> python3 .github/scripts/generate_ci_workflows.py
md5sum .github/workflows/generated-linux-*.yml > /tmp/b
diff /tmp/a /tmp/b && echo "idempotent"

Step 7: Lint and commit

Run lintrunner -a on the changed files, then commit. The commit message should record the hash and that it equals git rev-parse HEAD:.ci/docker. This is a release-only change; do not port it to main.

Common pitfalls

• Wrong hash: always derive it with git rev-parse HEAD:.ci/docker on the release branch. A hand-typed or stale hash points at a nonexistent tag and every linux binary build will fail to pull its container.
• Pinning windows/macOS: those builds do not run in these containers. Keep the pin scoped to MANYWHEEL_OSES; a pinned windows/macOS prefix is wrong.
• Editing the generated YAML directly: the lint check regenerates and asserts no diff, so hand edits get reverted. Always change the generator.
• Forgetting RELEASE_VERSION_TAG: without it the regenerated reusable workflow refs/version may differ from the committed release files.

Example usage

Pin the manywheel docker images for release/2.13

Re-pin the builder images, .ci/docker changed on the release branch