release: add schema-validated build-output companions

[msarahan]

Posted by Codex (GPT-5) on behalf of @msarahan. This PR description is LLM-generated; readers should treat its content accordingly.

Why

Candidate-first releases need an immutable record of the exact bytes produced
by CI, rather than a release coordinator reconstructing a package list and
downloading artifacts later. This adds a small companion artifact beside each
existing build bundle so the release platform can collect the already-built
packages, their source revision, and available evidence by exact workflow run.

What changes

• Conda C++, Conda Python, and wheel producers create a
  release-build-output-<source-artifact-name> companion whenever they upload
  their normal source artifact.
• Standard producers derive their release unit and package identity from the
  built files, with an optional release-unit override for catalog exceptions.
• custom-job.yaml remains opt-in: callers provide one JSON configuration only
  when an uploaded bundle is a release package bundle. This avoids guessing an
  arbitrary archive's release identity.
• The custom configuration is validated by the shared action before it inspects
  build outputs. Its canonical contract is the
  shared-actions schema.
• The companion records the build manifest and metadata plus available
  provenance, signatures, and SBOM sidecars without changing the producer's
  existing artifact bundle.

Standard Conda and wheel callers need no release-specific configuration.
Custom callers use an explicit artifact_type: custom, release component ID,
and artifact descriptors so the generated companion has one unambiguous
identity.

Tracks rapidsai/build-infra#381.

[jameslamb]

Tried my best to review. I have enough questions about this that I'm leaving a blocking review.

[jameslamb]

override only when one repository's Conda produces must be tracked as distinct components

I don't understand what this means.

Offline you mentioned testing with these PRs:

• Add release build output canary dask-cuda#1672
• Add release build output canary nx-cugraph#274
• Enroll custom release build outputs NVIDIA/cuvs#2400

None of them appear to set release-unit... is there a specific repo you're targeting where you'd envision this being used? A concrete example might help me understand why this is needed.

If you don't have a specific example where this would be applicable, let's remove it and simplify here a bit.

I'm also wondering ... wouldn't conda:<repository-name> conflict if you have conda-cpp-build.yaml and conda-python-build.yaml workflow calls in the same CI workflow? Or multiple conda-python-build.yaml workflow calls like we do in cudf separating noarch and other builds? (cudf code link)

[msarahan]

I struggled with the "release unit" name as well. Believe it or not, it had a worse name before. Sorry I didn't get this to be more understandable.

A release-unit is a collection of files that shares:

• validation/posting state
• whether it should be included in the release (perhaps useful for something like your selective deployment of UCXX hotfix release)
• dependencies (within our graph, not something like python dependencies)
• destination (so you could split normal wheels from wheels that only go to pypi.nvidia.com, for example)

A given filename within a release unit must be unique, but multiple release units with the same name can/will be merged across multiple manifest files.

We can get rid of this for simplicity. I don't think we have a use case for it currently. I think it is worth keeping the definition of what a release unit is, though.

[jameslamb]

I think this entire section's contents should be deleted and replaced with a simpler rewording.

I think this could be significantly simplified without any information loss, and that most of the details about how this works should be deferred to a README in shared-actions close to the relevant code (not here in shared-workflows).

Some details here also appear to be the output of an LLM responding to a prompt to generate the docs, not information that'd help users of shared-workflows. For example, this doesn't belong in the top-level README of the shared-workflows repo:

The cross-repository enrollment inventory, blockers, and proposed PR sequence
are maintained in
rapidsai/build-infra#381.

Suggesting a rewording here, mainly to help others reading these docs but also as a way to test that I've understood this functionality correctly.

---

(James's proposed rewording below)

Workflows that produce packages intended for redistribution (conda packages, wheels, tarballs, etc.) also upload files containing metadata about the workflows that produced those packages, licenses for source code used in the packages, and more.

Those files are bundled in an archive that roughly looks like this:

.
├── release-build-metadata.json
├── release-build-output.json
└── release-evidence
    ├── <package ID>.provenance.json
    └── <package ID>.spdx.json

Those are used at release time to create SBOMs and other provenance records attesting to where/when packages were built and what they contain.

For standardized package types like conda packages and wheels, the naming conventions and process for generating these contents is completely automated.

For custom package types, the custom-job.yaml workflow allows specification of a configuration for additional data to be appended. For example, configuration similar to this:

cuvs-java-build:
  uses: rapidsai/shared-workflows/.github/workflows/custom-job.yaml@main
  with:
    # existing build inputs omitted
    artifact-name: cuvs-java-cuda12.9.1
    file_to_upload: java/cuvs-java/target/
    release-build-output: >-
      {
        "artifact_type": "custom",
        "component_id": "maven:cuvs-java",
        "output_directory": "java/cuvs-java/target",
        "package_file": "cuvs-java.release-package.json",
        "artifacts": [{"path": "cuvs-java-*-x86_64-cuda*.jar"}]
      }

Results in the same directory layout as shown above, but with content like the following in release-build-output.json:

{
  "artifacts": [
    {
      "package": {
        "ecosystem": "maven",
        "name": "com.nvidia.cuvs:cuvs-java",
        "version": "26.10.0"
      },
      "path": "cuvs-java-26.10.0-x86_64-cuda13.jar",
      "provenance": "release-evidence/cuvs-java-26.10.0-x86_64-cuda13.jar.e47b54cfc174f4c5bf3054d99e1f595d26a1ba9ece2cba7c7ba5aba292765892.provenance.json",
      "sbom": "release-evidence/cuvs-java-26.10.0-x86_64-cuda13.jar.e47b54cfc174f4c5bf3054d99e1f595d26a1ba9ece2cba7c7ba5aba292765892.spdx.json",
      "unit_id": "maven:cuvs-java"
    }
  ],
  "producer": "release-platform",
  "schema_version": 1
}

For much more detail on how to configure and use these outputs, see <link to docs in 'shared-actions' repo>.

[jameslamb]

There are multiple other uses of inputs.sha above. What's a case where falling back to {{ github.sha }} would be appropriate / expected here?

If you don't have a specific case for that, recommend using {{ inputs.sha }}.

(similar question applies to all cases like this in this PR)

[msarahan]

Makes sense. The LLM wanted to fall back to env.RAPIDS_SHA, which is apparently set in each of the workflows in one of two ways:

• Conda C++ directly writes git rev-parse HEAD to RAPIDS_SHA: conda-cpp-build.yaml (line 138)
• Conda Python does the same: conda-python-build.yaml (line 148)
• Wheels invokes rapids-github-info: wheels-build.yaml (line 176)
• custom-job invokes it too: custom-job.yaml (line 180)

I think it's fine to either not be defensive with the fallback, or to error out when it is not set.

EDIT: several workflows do not pass this, and instead rely on the state of the already checked-out source. env.RAPIDS_SHA seems like the right way. +1 for the LLM over me.

[msarahan]

Marking this as do not merge because we should change the shared-actions refs after merging rapidsai/shared-actions#136