ci(py-315): prune cp315 wheels at every publication choke point

PR #19880 filtered cp315 out of the PyPI upload only, on the stated premise that
the other destination was "internal S3 and the private prerelease index". That is
wrong: s3://dd-trace-py-builds is anonymously readable and listable and is
registered in DataDog/cloud-inventory as a "Public bucket to host dev builds of
dd-trace-py from GitLab to share with customers". The pipeline republished cp315
wheels to main/ on 2026-08-27, so the leak was live, not historical.

Three mechanisms publish a ddtrace wheel outside the pipeline: twine to PyPI,
aws s3 cp to that bucket, and adms to pypi-private-prereleases. All three now call
.gitlab/scripts/prune-unsupported-wheels.sh first, which holds the withheld ABI
tags in one place. Putting it inside upload-wheels-to-s3.sh covers every S3 caller
and every index suffix, including "upload serverless", which no filter reached
before.

The PyPI-side shell in release.yml reverts to the pre-filter form plus one prune
call, per review feedback: with cp315 gone from the "ddtrace package" artifact,
twine check no longer needs a hand-built file list.

tests/internal/test_unsupported_wheel_pruning.py replaces the PyPI-specific test.
It pins the prune behaviour and asserts that every file under .gitlab/ running a
publish command also calls the prune script, so a new upload path cannot silently
reintroduce cp315.

Author: vlad-scherbich

.gitlab/package.yml

@@ -106,6 +106,8 @@ variables:
         IMAGE_TAG: *AARCH64_IMAGES
   # TODO(py-315): drop the cp315 allow_failure rule once #17849 ports the bytecode
   # wrapping path to sys.monitoring (currently raises NotImplementedError on 3.15).
+  # The cp315 wheels this matrix produces are kept for CI signal only and are deleted
+  # before every publication step by .gitlab/scripts/prune-unsupported-wheels.sh.
   rules:
     - if: $PYTHON_TAG == "cp315-cp315"
       allow_failure: true
@@ -226,6 +228,9 @@ variables:
         echo "Version '${PACKAGE_VERSION:-}' has no local segment (+...) -- nothing to patch, exiting."
         exit 0
       fi
+    # The prerelease index exists to hand custom builds to customers and internal services,
+    # so it gets the same treatment as PyPI and S3.
+    - .gitlab/scripts/prune-unsupported-wheels.sh pywheels
     - python3 .gitlab/scripts/patch-wheel-versions.py pywheels pywheels-patched
     - |
       set -euo pipefail
@@ -497,6 +502,8 @@ download_dependency_wheels:
       - "pywheels/*.whl"
       - "pywheels/*.tar.gz"
 
+# This job's artifact is what release_pypi_prod uploads to PyPI and what "upload all"
+# publishes as the default commit-scoped S3 index, so pruning here covers both.
 "ddtrace package":
   extends: .package_base
   needs:
@@ -507,6 +514,7 @@ download_dependency_wheels:
     - "collect windows wheels"
     - "package version"
   script:
+    - .gitlab/scripts/prune-unsupported-wheels.sh pywheels
     - .gitlab/validate-ddtrace-package.py pywheels
 
 "ddtrace package serverless":
@@ -515,4 +523,5 @@ download_dependency_wheels:
     - "build linux serverless"
     - "package version"
   script:
+    - .gitlab/scripts/prune-unsupported-wheels.sh pywheels
     - .gitlab/validate-ddtrace-package.py pywheels --mode=serverless

.gitlab/release.yml

@@ -15,28 +15,15 @@
     TWINE_NON_INTERACTIVE: "1"
   script:
     - export TWINE_PASSWORD=$(aws ssm get-parameter --region us-east-1 --name "ci.${CI_PROJECT_NAME}.${PYPI_REPOSITORY}_token" --with-decryption --query "Parameter.Value" --out text)
-    # TODO(py-315): cp315 wheels are built for internal S3 and the private prerelease index,
-    # and are withheld from PyPI while Python 3.15 is unsupported. Drop this filter once
-    # 3.15 is a supported target. Everything else, sdist included, is still uploaded.
-    #
-    # The list is built before "twine check" so both steps see exactly the same
-    # distributions: a malformed cp315 wheel from an allow_failure build must not fail a
-    # release whose supported wheels are all fine.
-    - |
-      set -eu
-      set --
-      for dist in pywheels/ddtrace-*; do
-        case "${dist}" in *cp315*) continue ;; esac
-        if [ -f "${dist}" ]; then set -- "$@" "${dist}"; fi
-      done
-      if [ "$#" -eq 0 ]; then
-        echo "[ERROR] no PyPI-eligible distributions found in pywheels/ -- refusing to upload" >&2
-        exit 1
-      fi
-      printf 'Uploading %s distribution(s) to %s:\n' "$#" "${PYPI_REPOSITORY}"
-      printf '  %s\n' "$@"
-      uvx --with="twine>=5.0,<7" twine check --strict "$@"
-      uvx --with="twine>=5.0,<7" twine upload --repository "${PYPI_REPOSITORY}" "$@"
+    # "ddtrace package" already pruned cp315 out of the artifact this job inherits. Pruning
+    # again keeps the invariant local and checkable: every publish command under .gitlab/
+    # is preceded by a prune call, and tests/internal/test_unsupported_wheel_pruning.py
+    # fails if a new one is not. It also means "twine check" and "twine upload" see the same
+    # set, so a malformed cp315 wheel from an allow_failure build cannot fail a release
+    # whose supported wheels are all fine.
+    - .gitlab/scripts/prune-unsupported-wheels.sh pywheels
+    - uvx --with="twine>=5.0,<7" twine check --strict pywheels/*
+    - uvx --with="twine>=5.0,<7" twine upload --repository ${PYPI_REPOSITORY} pywheels/ddtrace-*
   artifacts:
     paths:
       - pywheels/*.whl

.gitlab/scripts/prune-unsupported-wheels.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Deletes wheels whose Python ABI tag is built for CI signal but is not fit to publish.
+#
+# Usage: prune-unsupported-wheels.sh <dir> [<dir> ...]
+#
+# Every job that hands a ddtrace wheel to something outside this pipeline must call this
+# first. Today that is:
+#   * .gitlab/scripts/upload-wheels-to-s3.sh   -> the public dd-trace-py-builds bucket
+#   * .gitlab/release.yml (.release_pypi)      -> PyPI
+#   * .gitlab/package.yml ("ddtrace package")  -> the artifact release_pypi_prod and
+#                                                 "upload all" consume
+#   * .gitlab/package.yml (.patch_wheel_versions_base) -> the pypi-private-prereleases index
+#
+# tests/internal/test_unsupported_wheel_pruning.py asserts that every file under .gitlab/
+# that runs a publish command also calls this script, so a new upload path cannot skip it
+# without failing CI.
+#
+# Debug symbol archives (debugwheelhouse/*.zip) are deliberately not pruned: they are not
+# installable and carry no ABI risk. Pass only wheel directories.
+
+set -euo pipefail
+
+# Python ABI tags withheld from every publication channel. Single source of truth.
+#
+# TODO(py-315): cp315 wheels are built by "build linux" and "build linux serverless" under
+# allow_failure so that 3.15 keeps producing CI signal, but they are compiled against the
+# 3.15.0b1 PyThreadState layout and are ABI-broken. Drop cp315 from this list once #19861
+# makes those wheels correct and 3.15 is a supported target.
+UNSUPPORTED_TAGS=("cp315")
+
+if [ "$#" -eq 0 ]; then
+  echo "Usage: $0 <dir> [<dir> ...]" >&2
+  exit 1
+fi
+
+shopt -s nullglob
+
+for dir in "$@"; do
+  if [ ! -d "${dir}" ]; then
+    echo "[ERROR] ${dir} is not a directory -- refusing to publish unpruned wheels" >&2
+    exit 1
+  fi
+  for tag in "${UNSUPPORTED_TAGS[@]}"; do
+    matches=("${dir}"/*"${tag}"*.whl)
+    if [ ${#matches[@]} -eq 0 ]; then
+      continue
+    fi
+    printf 'Pruning %s unsupported %s wheel(s) from %s/:\n' "${#matches[@]}" "${tag}" "${dir}"
+    printf '  %s\n' "${matches[@]}"
+    rm -f -- "${matches[@]}"
+  done
+done

.gitlab/scripts/upload-wheels-to-s3.sh

@@ -18,6 +18,16 @@ if [ -z "$S3_PATH" ]; then
 fi
 
 shopt -s nullglob
+
+if [ ! -d pywheels ]; then
+  echo "No packages found in pywheels/"
+  exit 0
+fi
+
+# s3://dd-trace-py-builds is anonymously readable and listable, so nothing unsupported may
+# leave via this script. Every caller and every index suffix goes through here.
+.gitlab/scripts/prune-unsupported-wheels.sh pywheels
+
 WHEELS=(pywheels/*.whl pywheels/*.tar.gz)
 
 if [ ${#WHEELS[@]} -eq 0 ]; then