Add schema-validated release catalog companion action

[msarahan]

This adds a schema-validated action that creates a release catalog companion for an existing build artifact. The release platform can aggregate these job-level entry files into the release catalog. That catalog supports the two purposes tracked in rapidsai/build-infra#381:

• assembling releases that can be tested and verified before formal tagging
• preserving build-time software evidence, especially for binary artifacts such as wheels where that evidence cannot reliably be reconstructed later.

The action:

• validates configuration before inspecting artifacts
• validates every resolved artifact, package identity, and evidence file during materialization
• uploads one enveloped release-catalog-entries.json plus collected evidence as release-catalog-<source-artifact-name>

Tracks rapidsai/build-infra#381.

[jameslamb]

I did my best to review this.

My read is that this replaces a bunch of individual arguments with:

• automatically calculating some of the values
• allowing a few more values only needed in specific cases (like cuVS Java builds) to be passed in as a single dictionary via this new config: argument

At a surface level that sounds good to me! Less opportunity for misconfiguration across the repos, easier to change the behavior in the future.

My comments in this PR are light, but see my review on rapidsai/shared-workflows#609 ... I think documentation (ideally written by a human) in the release-build-output/ directory would be really helpful for folks to understand why this exists and what it does. I looked through the code, logs, and output from the testing PRs (rapidsai/dask-cuda#1672, rapidsai/nx-cugraph#274, NVIDIA/cuvs#2400) and think I have a picture of that, but I personally would find it hard to modify this setup if a new requirement came in.

[jameslamb]

Suggested change

	skip: [actionlint-docker, release-build-output-config]
	# why skip these in pre-commit.ci?
	#
	# * 'actionlint-docker': needs docker
	# * 'release-build-output-config': need 'jq'
	#
	# There are covered in other CI jobs where we have more control over the runtime evnvironment.
	#
	skip: [actionlint-docker, release-build-output-config]

This comment is really verbose, overly-specific, and only applies to release-build-output-config even though its placement makes it looks like it applies to everything in skip:. Would you consider something like this suggestion?

[jameslamb]

Suggested change

	https://github.com/rapidsai/shared-actions/blob/main/release-build-output/config.schema.json
	JSON string with configuration for this action. Schema and field documentation:
	https://github.com/rapidsai/shared-actions/blob/main/release-build-output/config.schema.json

I don't think repeating the literal field names and the implementation detail "... and package identity when artifact_type is custom" is helpful. Let's simplify this and redirect back to the schema.

[jameslamb]

How do I figure out a value for this?

Do I generate a UUID and provide my own? Is this auto-generated by the code?

That type of detail would be helpful.

[jameslamb]

Thanks for the changes, but I'm really struggling to thoughtfully review this.

I really did try but it's time for me to stop.

Put some suggestions below for things that would have helped me to provide a thoughtful review, I hope you'll consider them for the next round of development on this.

---

This PR is large and complicated, most of the code is uncommented.

As an example, release-catalog/materialize.sh seems like a critical part of the release-catalog action to me, but it's 400+ lines of bash and jq with only 2 code comments, one of which is a TODO filled with jargon I don't understand. More comments, especially top-level ones with description and usage in the larger scripts, would have helped.

---

The release-catalog README reads as a literal description of the code as-is, not something I could use to form expectations about how the software's supposed to work at a high level.

There's heavy use of jargon throughout and I don't know what is your terminology and what is coming from standards (like SPDX) that we have to meet. Either way, I don't understand many of the terms.

example: what the difference between a "build identity", "identity evidence", and "job-level envelope"? Are any of those synonymous with "companion"?.

---

I'm struggling to understand what this is expected to do, so I'm struggling to review how well it's doing it.

If we were to take the final "assembled" output for 1 repo, say NVIDIA/cuvs, how large would that be? If it's just a bunch of JSON files and not too large, could they be checked into source control here or somewhere else so we could see an example of what the end state is that we're trying to get to? That'd be really helpful.

---

The links in the description to tracking issues that just contain huge walls of seemingly unedited LLM output did not at all help my understanding.

Descriptions of this work written by you would probably have helped my understanding.

---

I left a few other suggestions on the diff. I feel strongly about separating all this new testing code into its own job instead of jamming it onto the existing checks: job that by convention we use for static analysis like pre-commit, not unit tests.

Otherwise, I'm clicking "approve" to say "ok, fine, go ahead and experiment with this". You want to do this this way and this is an area you have ownership over, I'm getting out of the way.

[jameslamb]

These look like actual unit tests, way more than should just be tacked on to the checks job in my opinion.

Would you please consider:

1. create a new job in this matrix called like test-release-catalog-actions or something instead of adding more steps to checks
2. put more of the test logic in a ci/run_release_catalog_tests.sh or similar (instead of having all this shell code in a GitHub Actions config)

I understand we might not want to use pr-builder from shared-workflows here (because it'd create a circular dependency between repos), so after this is merged please add this new job to the branch protection on main.

[jameslamb]

Suggested change

	- using build-time metadata to triage CVE scan records more quickly (internal
	GitLab project, `nspect-manager`)
	- using build-time metadata to triage CVE scan records more quickly

I don't think the internal project name is appropriate or that useful here, recommend just removing this.

[jameslamb]

Just commenting on one example of a general trend I've seen in the READMEs / code comments around this effort... this seems like an excessive level of detail. It increases the effort needed to understand what this is all supposed to do (at a high level), and it's the type of things that's very likely to become out of date as our CI configurations change.

[jameslamb]

Suggested change

	names the built source. Variables written to `GITHUB_ENV` are available to the
	action when it runs as a subsequent job step.
	names the built source.

This is a generic feature of GitHub Actions and feels out of place in this README, in my opinion.

[jameslamb]

Suggested change

	--arg artifact_name "${RELEASE_SOURCE_ARTIFACT_NAME}" \
	--arg repository "${GITHUB_REPOSITORY:-}" \
	--arg run_attempt "${GITHUB_RUN_ATTEMPT:-}" \
	--arg run_id "${GITHUB_RUN_ID:-}" \
	--arg sha "${source_sha}" \
	--arg workflow_ref "${GITHUB_WORKFLOW_REF:-}" \
	--argjson entries "$(jq -c '.entries' "${temporary_manifest}")" \
	--arg artifact_name "${RELEASE_SOURCE_ARTIFACT_NAME}" \
	--arg repository "${GITHUB_REPOSITORY}" \
	--arg run_attempt "${GITHUB_RUN_ATTEMPT}" \
	--arg run_id "${GITHUB_RUN_ID}" \
	--arg sha "${source_sha}" \
	--arg workflow_ref "${GITHUB_WORKFLOW_REF}" \
	--argjson entries "$(jq -c '.entries' "${temporary_manifest}")" \

Choosing one place in the diff to make a suggestion on a general theme I see in these PRs... this is overly-permissive.

Is there any case where it would be acceptable for source.repository in whatever this JSON is to be empty?

If not, then remove these fallbacks so we get a big loud error right here where something we expected to be defined is now.

This would benefit from a pass for strictness.

[jameslamb]

There's a tension in this line that I wondered throughout reviewing this... what does this field actually do and what uniqueness guarantees does it need to meet?

We build multiple conda packages from the cudf repo, so <ecosystem>:<repository-name> seems to not offer enough uniqueness.

Or if it does and it's important that the repository something was built from be part of this key (for provenance reasons) then why would cuvs-java not be maven:cuvs? cuvs-java is built from the cuvs repo.