feat: introduce more docker tags for uv (#6053)

## Summary

Closes #5610

This PR introduces additional images with the uv/uvx binaries from
scratch for both amd64/arm64 and make the mapping easy to configure by
generating the Dockerfile on the fly. This approach focuses on
minimizing CI time by taking advantage of dedicating a worker per
mapping (20-30s~ per job).

This PR also fixes `org.opencontainers.image.version` for all tags
(including the one from `scratch) to contain the right release version
instead of branch name `main` (default when no tag patterns are
specified).

For example, on release `x.y.z`, this will publish the following image
tags with format `ghcr.io/astral-sh/uv:{tag}` with manifests for both
amd64/arm64. This also include `x.y` tags for each respective additional
tag.

* From **scratch**: `latest`, `x.y.z`, `x.y` (currently being published)
* From **alpine:3.20**: `alpine`, `alpine3.20`, `x.y.z-alpine`,
`x.y.z-alpine3.20`
* From **debian:bookworm-slim**: `debian-slim`, `bookworm-slim`,
`x.y.z-debian-slim`, `x.y.z-bookworm-slim`
* From **buildpack-deps:bookworm**: `debian`, `bookworm`,
`x.y.z-debian`, `x.y.z-bookworm`
* From **python:3.12-alpine**: `python3.12-alpine`,
`x.y.z-python3.12-alpine`
* From **python:3.11-alpine**: `python3.11-alpine`,
`x.y.z-python3.11-alpine`
* From **python:3.10-alpine**: `python3.10-alpine`,
`x.y.z-python3.10-alpine`
* From **python:3.9-alpine**: `python3.9-alpine`,
`x.y.z-python3.9-alpine`
* From **python:3.8-alpine**: `python3.8-alpine`,
`x.y.z-python3.8-alpine`
* From **python:3.12-bookworm**: `python3.12-bookworm`,
`x.y.z-python3.12-bookworm`
* From **python:3.11-bookworm**: `python3.11-bookworm`,
`x.y.z-python3.11-bookworm`
* From **python:3.10-bookworm**: `python3.10-bookworm`,
`x.y.z-python3.10-bookworm`
* From **python:3.9-bookworm**: `python3.9-bookworm`,
`x.y.z-python3.9-bookworm`
* From **python:3.8-bookworm**: `python3.8-bookworm`,
`x.y.z-python3.8-bookworm`
* From **python:3.12-slim-bookworm**: `python3.12-slim-bookworm`,
`x.y.z-python3.12-slim-bookworm`
* From **python:3.11-slim-bookworm**: `python3.11-slim-bookworm`,
`x.y.z-python3.11-slim-bookworm`
* From **python:3.10-slim-bookworm**: `python3.10-slim-bookworm`,
`x.y.z-python3.10-slim-bookworm`
* From **python:3.9-slim-bookworm**: `python3.9-slim-bookworm`,
`x.y.z-python3.9-slim-bookworm`
* From **python:3.8-slim-bookworm**: `python3.8-slim-bookworm`,
`x.y.z-python3.8-slim-bookworm`

.github/workflows/build-docker.yml

@@ -45,12 +45,6 @@ jobs:
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Extract metadata (tags, labels) for Docker
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.UV_BASE_IMG }}
-
       - name: Check tag consistency
         if: ${{ inputs.plan != '' && !fromJson(inputs.plan).announcement_tag_is_implicit }}
         run: |
@@ -64,6 +58,16 @@ jobs:
             echo "Releasing ${version}"
           fi
 
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.UV_BASE_IMG }}
+          # Defining this makes sure the org.opencontainers.image.version OCI label becomes the actual release version and not the branch name
+          tags: |
+            type=raw,value=dry-run,enable=${{ inputs.plan == '' || fromJson(inputs.plan).announcement_tag_is_implicit }}
+            type=pep440,pattern={{ version }},value=${{ inputs.plan != '' && fromJson(inputs.plan).announcement_tag || 'dry-run' }},enable=${{ inputs.plan != '' && !fromJson(inputs.plan).announcement_tag_is_implicit }}
+
       - name: Normalize Platform Pair (replace / with -)
         run: |
           platform=${{ matrix.platform }}
@@ -118,6 +122,7 @@ jobs:
         uses: docker/metadata-action@v5
         with:
           images: ${{ env.UV_BASE_IMG }}
+          # Order is on purpose such that the label org.opencontainers.image.version has the first pattern with the full version
           tags: |
             type=pep440,pattern={{ version }},value=${{ fromJson(inputs.plan).announcement_tag }}
             type=pep440,pattern={{ major }}.{{ minor }},value=${{ fromJson(inputs.plan).announcement_tag }}
@@ -138,3 +143,106 @@ jobs:
           docker buildx imagetools create \
             $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
             $(printf '${{ env.UV_BASE_IMG }}@sha256:%s ' *)
+
+  docker-publish-extra:
+    name: Publish additional Docker image based on ${{ matrix.image-mapping }}
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+    needs:
+      - docker-publish
+    if: ${{ inputs.plan != '' && !fromJson(inputs.plan).announcement_tag_is_implicit }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Mapping of base image followed by a comma followed by one or more base tags (comma separated)
+        # Note, org.opencontainers.image.version label will use the first base tag (use the most specific tag first)
+        image-mapping:
+          - alpine:3.20,alpine3.20,alpine
+          - debian:bookworm-slim,bookworm-slim,debian-slim
+          - buildpack-deps:bookworm,bookworm,debian
+          - python:3.12-alpine,python3.12-alpine
+          - python:3.11-alpine,python3.11-alpine
+          - python:3.10-alpine,python3.10-alpine
+          - python:3.9-alpine,python3.9-alpine
+          - python:3.8-alpine,python3.8-alpine
+          - python:3.12-bookworm,python3.12-bookworm
+          - python:3.11-bookworm,python3.11-bookworm
+          - python:3.10-bookworm,python3.10-bookworm
+          - python:3.9-bookworm,python3.9-bookworm
+          - python:3.8-bookworm,python3.8-bookworm
+          - python:3.12-slim-bookworm,python3.12-bookworm-slim
+          - python:3.11-slim-bookworm,python3.11-bookworm-slim
+          - python:3.10-slim-bookworm,python3.10-bookworm-slim
+          - python:3.9-slim-bookworm,python3.9-bookworm-slim
+          - python:3.8-slim-bookworm,python3.8-bookworm-slim
+    steps:
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate Dynamic Dockerfile Tags
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          # Extract the image and tags from the matrix variable
+          IFS=',' read -r BASE_IMAGE BASE_TAGS <<< "${{ matrix.image-mapping }}"
+
+          # Generate Dockerfile content
+          cat <<EOF > Dockerfile
+          FROM ${BASE_IMAGE}
+          COPY --from=${{ env.UV_BASE_IMG }}:latest /uv /usr/local/bin/uv
+          COPY --from=${{ env.UV_BASE_IMG }}:latest /uvx /usr/local/bin/uvx
+          ENTRYPOINT ["/usr/local/bin/uv"]
+          EOF
+
+          # Initialize a variable to store all tag docker metadata patterns
+          TAG_PATTERNS=""
+
+          # Loop through all base tags and append its docker metadata pattern to the list
+          # Order is on purpose such that the label org.opencontainers.image.version has the first pattern with the full version
+          IFS=','; for TAG in ${BASE_TAGS}; do
+            TAG_PATTERNS="${TAG_PATTERNS}type=pep440,pattern={{ version }},suffix=-${TAG},value=${{ fromJson(inputs.plan).announcement_tag }}\n"
+            TAG_PATTERNS="${TAG_PATTERNS}type=pep440,pattern={{ major }}.{{ minor }},suffix=-${TAG},value=${{ fromJson(inputs.plan).announcement_tag }}\n"
+            TAG_PATTERNS="${TAG_PATTERNS}type=raw,value=${TAG}\n"
+          done
+
+          # Remove the trailing newline from the pattern list
+          TAG_PATTERNS="${TAG_PATTERNS%\\n}"
+
+          # Export image cache name
+          echo "IMAGE_REF=${BASE_IMAGE//:/-}" >> $GITHUB_ENV
+
+          # Export tag patterns using the multiline env var syntax
+          {
+            echo "TAG_PATTERNS<<EOF"
+            echo -e "${TAG_PATTERNS}"
+            echo EOF
+          } >> $GITHUB_ENV
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.UV_BASE_IMG }}
+          flavor: |
+            latest=false
+          tags: |
+            ${{ env.TAG_PATTERNS }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          # We do not really need to cache here as the Dockerfile is tiny
+          #cache-from: type=gha,scope=uv-${{ env.IMAGE_REF }}
+          #cache-to: type=gha,mode=min,scope=uv-${{ env.IMAGE_REF }}
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

docs/guides/integration/docker.md

@@ -24,12 +24,84 @@ uv builds and publishes the following Docker tags:
 - `uv:{major}.{minor}.{patch}`, e.g., `uv:0.4.3`
 - `uv:{major}.{minor}`, e.g., `uv:0.4` (the latest patch version)
 
+In addition, uv builds and publishes these additional tags:
+
+- Based on `alpine:3.20`:
+  - `uv:alpine`
+  - `uv:alpine3.20`
+  - `uv:{major}.{minor}-alpine`
+  - `uv:{major}.{minor}-alpine3.20`
+  - `uv:{major}.{minor}.{patch}-alpine`
+  - `uv:{major}.{minor}.{patch}-alpine3.20`
+- Based on `debian:bookworm-slim`:
+  - `uv:debian-slim`
+  - `uv:bookworm-slim`
+  - `uv:{major}.{minor}-debian-slim`
+  - `uv:{major}.{minor}-bookworm-slim`
+  - `uv:{major}.{minor}.{patch}-debian-slim`
+  - `uv:{major}.{minor}.{patch}-bookworm-slim`
+- Based on `buildpack-deps:bookworm`:
+  - `uv:debian`
+  - `uv:bookworm`
+  - `uv:{major}.{minor}-debian`
+  - `uv:{major}.{minor}-bookworm`
+  - `uv:{major}.{minor}.{patch}-debian`
+  - `uv:{major}.{minor}.{patch}-bookworm`
+- Based on `python3.x-alpine`:
+  - `uv:python3.12-alpine`
+  - `uv:python3.11-alpine`
+  - `uv:python3.10-alpine`
+  - `uv:python3.9-alpine`
+  - `uv:python3.8-alpine`
+  - `uv:{major}.{minor}-python3.12-alpine`
+  - `uv:{major}.{minor}-python3.11-alpine`
+  - `uv:{major}.{minor}-python3.10-alpine`
+  - `uv:{major}.{minor}-python3.9-alpine`
+  - `uv:{major}.{minor}-python3.8-alpine`
+  - `uv:{major}.{minor}.{patch}-python3.12-alpine`
+  - `uv:{major}.{minor}.{patch}-python3.11-alpine`
+  - `uv:{major}.{minor}.{patch}-python3.10-alpine`
+  - `uv:{major}.{minor}.{patch}-python3.9-alpine`
+  - `uv:{major}.{minor}.{patch}-python3.8-alpine`
+- Based on `python3.x-bookworm`:
+  - `uv:python3.12-bookworm`
+  - `uv:python3.11-bookworm`
+  - `uv:python3.10-bookworm`
+  - `uv:python3.9-bookworm`
+  - `uv:python3.8-bookworm`
+  - `uv:{major}.{minor}-python3.12-bookworm`
+  - `uv:{major}.{minor}-python3.11-bookworm`
+  - `uv:{major}.{minor}-python3.10-bookworm`
+  - `uv:{major}.{minor}-python3.9-bookworm`
+  - `uv:{major}.{minor}-python3.8-bookworm`
+  - `uv:{major}.{minor}.{patch}-python3.12-bookworm`
+  - `uv:{major}.{minor}.{patch}-python3.11-bookworm`
+  - `uv:{major}.{minor}.{patch}-python3.10-bookworm`
+  - `uv:{major}.{minor}.{patch}-python3.9-bookworm`
+  - `uv:{major}.{minor}.{patch}-python3.8-bookworm`
+- Based on `python3.x-slim-bookworm`:
+  - `uv:python3.12-slim-bookworm`
+  - `uv:python3.11-slim-bookworm`
+  - `uv:python3.10-slim-bookworm`
+  - `uv:python3.9-slim-bookworm`
+  - `uv:python3.8-slim-bookworm`
+  - `uv:{major}.{minor}-python3.12-slim-bookworm`
+  - `uv:{major}.{minor}-python3.11-slim-bookworm`
+  - `uv:{major}.{minor}-python3.10-slim-bookworm`
+  - `uv:{major}.{minor}-python3.9-slim-bookworm`
+  - `uv:{major}.{minor}-python3.8-slim-bookworm`
+  - `uv:{major}.{minor}.{patch}-python3.12-slim-bookworm`
+  - `uv:{major}.{minor}.{patch}-python3.11-slim-bookworm`
+  - `uv:{major}.{minor}.{patch}-python3.10-slim-bookworm`
+  - `uv:{major}.{minor}.{patch}-python3.9-slim-bookworm`
+  - `uv:{major}.{minor}.{patch}-python3.8-slim-bookworm`
+
 For more details, see the [GitHub Container](https://github.com/astral-sh/uv/pkgs/container/uv)
 page.
 
 ### Installing uv
 
-uv can be installed by copying from the official Docker image:
+uv can also be installed by copying from the official distroless Docker image:
 
 ```dockerfile title="Dockerfile"
 FROM python:3.12-slim-bookworm