release: generate release catalog companions for build artifacts

.github/workflows/compute-matrix.yaml

@@ -2,7 +2,7 @@ on:
   workflow_call:
     inputs:
       build_type:
-        description: "One of: [branch, nightly, pull-request]"
+        description: "One of: [branch, nightly, pull-request, release-candidate]"
         required: true
         type: string
       matrix_name:
@@ -58,8 +58,8 @@ jobs:
         env:
           MATRIX: ${{ steps.prepare-matrix.outputs.matrix }}
         run: |
-          if [[ "$BUILD_TYPE" != "branch" ]] && [[ "$BUILD_TYPE" != "nightly" ]] && [[ "$BUILD_TYPE" != "pull-request" ]]; then
-              echo "::error::Invalid build_type! Must be one of 'branch', 'nightly', or 'pull-request'."
+          if [[ "$BUILD_TYPE" != "branch" ]] && [[ "$BUILD_TYPE" != "nightly" ]] && [[ "$BUILD_TYPE" != "pull-request" ]] && [[ "$BUILD_TYPE" != "release-candidate" ]]; then
+              echo "::error::Invalid build_type! Must be one of 'branch', 'nightly', 'pull-request', or 'release-candidate'."
               exit 1
           fi
           if [[ ! "$MATRIX_TYPE" =~ ^(auto|nightly|pull-request)(,(auto|nightly|pull-request))*$ ]] || [[ "$MATRIX_TYPE" == *auto* && "$MATRIX_TYPE" != "auto" ]]; then
@@ -82,7 +82,7 @@ jobs:
 
           # only overwrite MATRIX_TYPE if it was set to 'auto'
           if [[ "${MATRIX_TYPE}" == "auto" ]]; then
-            if [[ "${BUILD_TYPE}" == "branch" ]]; then
+            if [[ "${BUILD_TYPE}" == "branch" || "${BUILD_TYPE}" == "release-candidate" ]]; then
               # Use the nightly matrix for branch tests
               MATRIX_TYPE="nightly"
             else

.github/workflows/conda-cpp-build.yaml

@@ -2,7 +2,7 @@ on:
   workflow_call:
     inputs:
       build_type:
-        description: "One of: [branch, nightly, pull-request]"
+        description: "One of: [branch, nightly, pull-request, release-candidate]"
         required: true
         type: string
       branch:
@@ -44,6 +44,10 @@ on:
         default: true
         required: false
         description: "One of [true, false], true if artifacts should be uploaded to GitHub's artifact store"
+      candidate-train-sha256:
+        description: "Canonical SHA-256 of the release train; required for release-candidate builds."
+        type: string
+        default: ""
       matrix_filter:
         description: |
           jq expression which modifies the matrix.
@@ -258,7 +262,7 @@ jobs:
           MAMBA_USE_SHARDED_REPODATA: false
           RATTLER_SHARDED: false
       - name: Get Package Name and Location
-        if: ${{ inputs.upload-artifacts }}
+        if: ${{ inputs.upload-artifacts || inputs.build_type == 'release-candidate' }}
         env:
           # Pass RAPIDS_PACKAGE_NAME from cpp-build step if available
           RAPIDS_PACKAGE_NAME: ${{ steps.cpp-build.outputs.rapids-package-name }}
@@ -272,20 +276,41 @@ jobs:
           echo "CONDA_OUTPUT_DIR=${RAPIDS_CONDA_BLD_OUTPUT_DIR}" >> "${GITHUB_OUTPUT}"
         id: package-name
       - name: Show files to be uploaded
-        if: ${{ inputs.upload-artifacts }}
+        if: ${{ inputs.upload-artifacts || inputs.build_type == 'release-candidate' }}
         env:
           CONDA_OUTPUT_DIR: ${{ steps.package-name.outputs.CONDA_OUTPUT_DIR }}
         run: |
           echo "Contents of directory to be uploaded:"
           ls -R "${CONDA_OUTPUT_DIR}"
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        if: ${{ inputs.upload-artifacts }}
+        if: ${{ inputs.upload-artifacts && inputs.build_type != 'release-candidate' }}
         with:
           if-no-files-found: 'error'
           name: ${{ steps.package-name.outputs.RAPIDS_PACKAGE_NAME }}
           path: ${{ steps.package-name.outputs.CONDA_OUTPUT_DIR }}
+
+      - name: Configure release-candidate store credentials
+        if: ${{ inputs.build_type == 'release-candidate' }}
+        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6.2.2
+        with:
+          aws-region: us-east-2
+          role-duration-seconds: 43200 # 12h
+          role-to-assume: arn:aws:iam::279114543810:role/gha-oidc-rapids-release-candidates
+      - name: Create Conda release catalog companion
+        if: ${{ inputs.build_type == 'release-candidate' }}
+        uses: rapidsai/shared-actions/release-catalog@4f580aef2a239f6c7b44f98ef526ae83b7543c78 # shared-actions PR 136 merged
+        with:
+          config: >-
+            {
+              "release_catalog_key": ${{ toJSON(format('conda:{0}', github.event.repository.name)) }},
+              "artifact_directory": ${{ toJSON(steps.package-name.outputs.CONDA_OUTPUT_DIR) }}
+            }
+          source-artifact-name: ${{ steps.package-name.outputs.RAPIDS_PACKAGE_NAME }}
+          source-sha: ${{ env.RAPIDS_SHA }}
+          candidate-train-sha256: ${{ inputs.candidate-train-sha256 }}
+          upload-to-s3: 'true'
       - name: Upload additional artifacts
-        if: "!cancelled()"
+        if: ${{ !cancelled() && inputs.build_type != 'release-candidate' }}
         run: rapids-upload-artifacts-dir "cuda${RAPIDS_CUDA_VERSION%%.*}_$(arch)"
       - name: Telemetry upload attributes
         uses: rapidsai/shared-actions/telemetry-dispatch-stash-job-artifacts@main

.github/workflows/conda-python-build.yaml

@@ -2,7 +2,7 @@ on:
   workflow_call:
     inputs:
       build_type:
-        description: "One of: [branch, nightly, pull-request]"
+        description: "One of: [branch, nightly, pull-request, release-candidate]"
         required: true
         type: string
       branch:
@@ -44,6 +44,10 @@ on:
         default: true
         required: false
         description: "One of [true, false], true if artifacts should be uploaded to GitHub's artifact store"
+      candidate-train-sha256:
+        description: "Canonical SHA-256 of the release train; required for release-candidate builds."
+        type: string
+        default: ""
       matrix_filter:
         description: |
           jq expression which modifies the matrix.
@@ -263,7 +267,7 @@ jobs:
           MAMBA_USE_SHARDED_REPODATA: false
           RATTLER_SHARDED: false
       - name: Get Package Name and Location
-        if: ${{ inputs.upload-artifacts }}
+        if: ${{ inputs.upload-artifacts || inputs.build_type == 'release-candidate' }}
         env:
           # Pass RAPIDS_PACKAGE_NAME from python-build step if available
           RAPIDS_PACKAGE_NAME: ${{ steps.python-build.outputs.rapids-package-name }}
@@ -277,20 +281,41 @@ jobs:
           echo "CONDA_OUTPUT_DIR=${RAPIDS_CONDA_BLD_OUTPUT_DIR}" >> "${GITHUB_OUTPUT}"
         id: package-name
       - name: Show files to be uploaded
-        if: ${{ inputs.upload-artifacts }}
+        if: ${{ inputs.upload-artifacts || inputs.build_type == 'release-candidate' }}
         env:
           CONDA_OUTPUT_DIR: ${{ steps.package-name.outputs.CONDA_OUTPUT_DIR }}
         run: |
           echo "Contents of directory to be uploaded:"
           ls -R "${CONDA_OUTPUT_DIR}"
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        if: ${{ inputs.upload-artifacts }}
+        if: ${{ inputs.upload-artifacts && inputs.build_type != 'release-candidate' }}
         with:
           if-no-files-found: 'error'
           name: ${{ steps.package-name.outputs.RAPIDS_PACKAGE_NAME }}
           path: ${{ steps.package-name.outputs.CONDA_OUTPUT_DIR }}
+
+      - name: Configure release-candidate store credentials
+        if: ${{ inputs.build_type == 'release-candidate' }}
+        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6.2.2
+        with:
+          aws-region: us-east-2
+          role-duration-seconds: 43200 # 12h
+          role-to-assume: arn:aws:iam::279114543810:role/gha-oidc-rapids-release-candidates
+      - name: Create Conda release catalog companion
+        if: ${{ inputs.build_type == 'release-candidate' }}
+        uses: rapidsai/shared-actions/release-catalog@4f580aef2a239f6c7b44f98ef526ae83b7543c78 # shared-actions PR 136 merged
+        with:
+          config: >-
+            {
+              "release_catalog_key": ${{ toJSON(format('conda:{0}', github.event.repository.name)) }},
+              "artifact_directory": ${{ toJSON(steps.package-name.outputs.CONDA_OUTPUT_DIR) }}
+            }
+          source-artifact-name: ${{ steps.package-name.outputs.RAPIDS_PACKAGE_NAME }}
+          source-sha: ${{ env.RAPIDS_SHA }}
+          candidate-train-sha256: ${{ inputs.candidate-train-sha256 }}
+          upload-to-s3: 'true'
       - name: Upload additional artifacts
-        if: "!cancelled()"
+        if: ${{ !cancelled() && inputs.build_type != 'release-candidate' }}
         run: rapids-upload-artifacts-dir "cuda${RAPIDS_CUDA_VERSION%%.*}_$(arch)_py${RAPIDS_PY_VERSION//.}"
       - name: Telemetry upload attributes
         uses: rapidsai/shared-actions/telemetry-dispatch-stash-job-artifacts@main

.github/workflows/conda-upload-packages.yaml

@@ -2,7 +2,7 @@ on:
   workflow_call:
     inputs:
       build_type:
-        description: "One of: [branch, nightly, pull-request]"
+        description: "One of: [branch, nightly, pull-request, release-candidate]"
         required: true
         type: string
       branch:
@@ -71,6 +71,9 @@ permissions:
 
 jobs:
   upload:
+    # Candidate artifacts are staged privately by the build workflow. They must
+    # not enter either public Anaconda.org channel before rollover approval.
+    if: ${{ inputs.build_type != 'release-candidate' }}
     runs-on: linux-amd64-cpu4
     container:
       image: "python:3.14-slim"

.github/workflows/custom-job.yaml

@@ -2,7 +2,7 @@ on:
   workflow_call:
     inputs:
       build_type:
-        description: "One of: [branch, nightly, pull-request]"
+        description: "One of: [branch, nightly, pull-request, release-candidate]"
         required: true
         type: string
       branch:
@@ -105,6 +105,18 @@ on:
         default: false
         type: boolean
         required: false
+      release-catalog-config:
+        description: >-
+          Optional JSON configuration for the shared-actions release catalog action. In release-candidate mode,
+          it writes the declared files and evidence to the private candidate store. See
+          https://github.com/rapidsai/shared-actions/tree/main/release-catalog for configuration details.
+        default: ''
+        type: string
+        required: false
+      candidate-train-sha256:
+        description: "Canonical SHA-256 of the release train; required for release-candidate builds."
+        type: string
+        default: ""
 
 defaults:
   run:
@@ -228,13 +240,30 @@ jobs:
           MAMBA_USE_SHARDED_REPODATA: false
           RATTLER_SHARDED: false
       - name: Upload file to GitHub Artifact
+        if: ${{ inputs.build_type != 'release-candidate' }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: ${{ inputs.artifact-name }}
           path: ${{ inputs.file_to_upload }}
           if-no-files-found: ignore
+      - name: Configure release-candidate store credentials
+        if: ${{ inputs.build_type == 'release-candidate' }}
+        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6.2.2
+        with:
+          aws-region: us-east-2
+          role-duration-seconds: 43200 # 12h
+          role-to-assume: arn:aws:iam::279114543810:role/gha-oidc-rapids-release-candidates
+      - name: Create release catalog companion
+        if: ${{ inputs.build_type == 'release-candidate' && inputs.release-catalog-config != '' }}
+        uses: rapidsai/shared-actions/release-catalog@4f580aef2a239f6c7b44f98ef526ae83b7543c78 # shared-actions PR 136 merged
+        with:
+          config: ${{ inputs.release-catalog-config }}
+          source-artifact-name: ${{ inputs.artifact-name }}
+          source-sha: ${{ env.RAPIDS_SHA }}
+          candidate-train-sha256: ${{ inputs.candidate-train-sha256 }}
+          upload-to-s3: 'true'
       - name: Upload additional artifacts
-        if: "!cancelled()"
+        if: ${{ !cancelled() && inputs.build_type != 'release-candidate' }}
         run: rapids-upload-artifacts-dir "custom-job-$(arch)"
       - name: Telemetry upload attributes
         uses: rapidsai/shared-actions/telemetry-dispatch-stash-job-artifacts@main

.github/workflows/wheels-build.yaml

@@ -26,7 +26,7 @@ on:
         description: "Git repo to check out, in '{org}/{repo}' form, e.g. 'rapidsai/cudf'"
         type: string
       build_type:
-        description: "One of: [branch, nightly, pull-request]"
+        description: "One of: [branch, nightly, pull-request, release-candidate]"
         required: true
         type: string
       script:
@@ -75,6 +75,10 @@ on:
         default: true
         required: false
         description: "One of [true, false], true if artifacts should be uploaded to GitHub's artifact store"
+      candidate-train-sha256:
+        description: "Canonical SHA-256 of the release train; required for release-candidate builds."
+        type: string
+        default: ""
       extra-repo:
         required: false
         type: string
@@ -223,7 +227,6 @@ jobs:
           cache-environment: ${{ inputs.cache-environment }}
           cache-read-only: ${{ inputs.cache-read-only }}
           matrix: ${{ toJSON(matrix) }}
-
       - name: Standardize repository information
         uses: rapidsai/shared-actions/rapids-github-info@main
         with:
@@ -310,7 +313,7 @@ jobs:
         shell: bash -leo pipefail {0}
 
       - name: Get package name
-        if: ${{ inputs.upload-artifacts }}
+        if: ${{ inputs.upload-artifacts || inputs.build_type == 'release-candidate' }}
         env:
           # Pass RAPIDS_PACKAGE_NAME from build-wheel step if available
           RAPIDS_PACKAGE_NAME: ${{ steps.build-wheel.outputs.rapids-package-name }}
@@ -343,22 +346,43 @@ jobs:
         id: package-name
 
       - name: Show files to be uploaded
-        if: ${{ inputs.upload-artifacts }}
+        if: ${{ inputs.upload-artifacts || inputs.build_type == 'release-candidate' }}
         env:
           WHEEL_OUTPUT_DIR: ${{ steps.package-name.outputs.WHEEL_OUTPUT_DIR }}
         run: |
           echo "Contents of directory to be uploaded:"
           ls -R "$WHEEL_OUTPUT_DIR"
 
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        if: ${{ inputs.upload-artifacts }}
+        if: ${{ inputs.upload-artifacts && inputs.build_type != 'release-candidate' }}
         with:
           if-no-files-found: 'error'
           name: ${{ steps.package-name.outputs.RAPIDS_PACKAGE_NAME }}
           path: ${{ steps.package-name.outputs.WHEEL_OUTPUT_DIR }}
 
+      - name: Configure release-candidate store credentials
+        if: ${{ inputs.build_type == 'release-candidate' }}
+        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6.2.2
+        with:
+          aws-region: us-east-2
+          role-duration-seconds: 43200 # 12h
+          role-to-assume: arn:aws:iam::279114543810:role/gha-oidc-rapids-release-candidates
+      - name: Create wheel release catalog companion
+        if: ${{ inputs.build_type == 'release-candidate' }}
+        uses: rapidsai/shared-actions/release-catalog@4f580aef2a239f6c7b44f98ef526ae83b7543c78 # shared-actions PR 136 merged
+        with:
+          config: >-
+            {
+              "release_catalog_key": ${{ toJSON(format('wheel:{0}', github.event.repository.name)) }},
+              "artifact_directory": ${{ toJSON(steps.package-name.outputs.WHEEL_OUTPUT_DIR) }}
+            }
+          source-artifact-name: ${{ steps.package-name.outputs.RAPIDS_PACKAGE_NAME }}
+          source-sha: ${{ env.RAPIDS_SHA }}
+          candidate-train-sha256: ${{ inputs.candidate-train-sha256 }}
+          upload-to-s3: 'true'
+
       - name: Upload additional artifacts
-        if: "!cancelled()"
+        if: ${{ !cancelled() && inputs.build_type != 'release-candidate' }}
         run: rapids-upload-artifacts-dir "cuda${RAPIDS_CUDA_VERSION%%.*}_$(arch)_py${RAPIDS_PY_VERSION//.}"
       - name: Telemetry upload attributes
         if: ${{ vars.TELEMETRY_ENABLED == 'true' }}

.github/workflows/wheels-publish.yaml

@@ -18,7 +18,7 @@ on:
         description: "Git repo to check out, in '{org}/{repo}' form, e.g. 'rapidsai/cudf'"
         type: string
       build_type:
-        description: "One of: [branch, nightly, pull-request]"
+        description: "One of: [branch, nightly, pull-request, release-candidate]"
         required: true
         type: string
 
@@ -73,6 +73,9 @@ permissions:
 jobs:
   wheel-publish:
     name: wheels publish
+    # Candidate artifacts are staged privately by the build workflow. They must
+    # not enter public Anaconda.org or PyPI channels before rollover approval.
+    if: ${{ inputs.build_type != 'release-candidate' }}
     # Use a self-hosted runner to ensure we have sufficient disk space. Using
     # cpu8 since we shouldn't need much CPU horsepower.
     runs-on: "linux-amd64-cpu8"

README.md

@@ -96,3 +96,22 @@ wheel-tests:
 ```
 
 Values passed through `secrets:` are redacted everywhere in the GitHub UI, including in logs, and in most cases are replaced with `***`.
+
+### Release catalog
+
+We add additional metadata files to our builds to help track what dependencies
+were present at build time (a Software Bill of Materials, SBoM), as well as
+keeping track of artifacts as we prepare for releases. The standard Conda and
+wheel builders do this automatically and upload an additional
+`release-catalog-<artifact-name>` GitHub Actions artifact for every package
+bundle.
+
+`custom-job.yaml` can be used to produce artifacts, but the generation of extra
+metadata files are opt-in, not automatic. Supplying a non-empty
+`release-catalog-config` causes the job to upload the additional
+release catalog companion; leaving it empty uploads only the original artifact.
+
+See the
+[`shared-actions` release catalog documentation](https://github.com/rapidsai/shared-actions/tree/main/release-catalog)
+for the companion layout, configuration schema, examples, and evidence
+semantics.