release: Add RELEASE documentation #128
Conversation
Signed-off-by: Zvonko Kaiser <zkaiser@nvidia.com>
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for the NVRC release process, including step-by-step instructions for creating releases, troubleshooting common issues, and understanding the release artifacts.
Changes:
- Added RELEASE.md documenting the complete release workflow including prerequisites, version bumping, workflow execution, and troubleshooting
- Documented the immutable releases security measure and its implications
- Provided detailed tables of release artifacts and their descriptions
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Sigstore/cosign, creates tarballs | ||
| 3. **create-release** - Creates a **draft** GitHub release with tarballs | ||
| 4. **provenance** - Generates SLSA Level 3 provenance attestations | ||
| 5. **provenance-publish** - Uploads provenance to the draft release |
There was a problem hiding this comment.
The step description says "Uploads provenance to the draft release", but the release is not a draft - it's published immediately when created. Remove the word "draft" to accurately reflect the workflow behavior.
| 5. **provenance-publish** - Uploads provenance to the draft release | |
| 5. **provenance-publish** - Uploads provenance to the release |
| | `NVRC-{arch}.tar.xz` | Tarball containing binary and signatures | | ||
| | `NVRC-{arch}.tar.xz.sig` | Cosign signature for tarball | | ||
| | `NVRC-{arch}.tar.xz.cert` | Cosign certificate for tarball | | ||
| | `NVRC-{arch}.tar.xz.bundle.json` | Rekor bundle for offline verification | | ||
| | `NVRC-{arch}.intoto.jsonl` | SLSA provenance attestation | | ||
|
|
||
| Inside each tarball: | ||
|
|
||
| | File | Description | | ||
| | ------------------------------------------ | -------------------- | | ||
| | `NVRC-{arch}` | The binary | | ||
| | `NVRC-{arch}.sig` | Binary signature | | ||
| | `NVRC-{arch}.cert` | Binary certificate | | ||
| | `NVRC-{arch}.bundle.json` | Binary Rekor bundle | | ||
| | `sbom-NVRC-{arch}.spdx.json` | SBOM in SPDX format | | ||
| | `sbom-NVRC-{arch}.spdx.json.sig` | SBOM signature | | ||
| | `sbom-NVRC-{arch}.spdx.json.cert` | SBOM certificate | | ||
| | `sbom-NVRC-{arch}.spdx.json.bundle.json` | SBOM Rekor bundle | |
There was a problem hiding this comment.
The artifact naming in the table uses {arch} as a placeholder, which is ambiguous. The actual workflow uses full target triples like x86_64-unknown-linux-musl and aarch64-unknown-linux-musl. Update the table to use {target} instead of {arch} to be consistent with the workflow terminology, or clarify in the table header that {arch} refers to the full target triple (e.g., "where {arch} is x86_64-unknown-linux-musl or aarch64-unknown-linux-musl").
| | `NVRC-{arch}.tar.xz` | Tarball containing binary and signatures | | |
| | `NVRC-{arch}.tar.xz.sig` | Cosign signature for tarball | | |
| | `NVRC-{arch}.tar.xz.cert` | Cosign certificate for tarball | | |
| | `NVRC-{arch}.tar.xz.bundle.json` | Rekor bundle for offline verification | | |
| | `NVRC-{arch}.intoto.jsonl` | SLSA provenance attestation | | |
| Inside each tarball: | |
| | File | Description | | |
| | ------------------------------------------ | -------------------- | | |
| | `NVRC-{arch}` | The binary | | |
| | `NVRC-{arch}.sig` | Binary signature | | |
| | `NVRC-{arch}.cert` | Binary certificate | | |
| | `NVRC-{arch}.bundle.json` | Binary Rekor bundle | | |
| | `sbom-NVRC-{arch}.spdx.json` | SBOM in SPDX format | | |
| | `sbom-NVRC-{arch}.spdx.json.sig` | SBOM signature | | |
| | `sbom-NVRC-{arch}.spdx.json.cert` | SBOM certificate | | |
| | `sbom-NVRC-{arch}.spdx.json.bundle.json` | SBOM Rekor bundle | | |
| | `NVRC-{target}.tar.xz` | Tarball containing binary and signatures | | |
| | `NVRC-{target}.tar.xz.sig` | Cosign signature for tarball | | |
| | `NVRC-{target}.tar.xz.cert` | Cosign certificate for tarball | | |
| | `NVRC-{target}.tar.xz.bundle.json` | Rekor bundle for offline verification | | |
| | `NVRC-{target}.intoto.jsonl` | SLSA provenance attestation | | |
| Inside each tarball (per target triple, where `{target}` is `x86_64-unknown-linux-musl` or `aarch64-unknown-linux-musl`): | |
| | File | Description | | |
| | ------------------------------------------ | -------------------- | | |
| | `NVRC-{target}` | The binary | | |
| | `NVRC-{target}.sig` | Binary signature | | |
| | `NVRC-{target}.cert` | Binary certificate | | |
| | `NVRC-{target}.bundle.json` | Binary Rekor bundle | | |
| | `sbom-NVRC-{target}.spdx.json` | SBOM in SPDX format | | |
| | `sbom-NVRC-{target}.spdx.json.sig` | SBOM signature | | |
| | `sbom-NVRC-{target}.spdx.json.cert` | SBOM certificate | | |
| | `sbom-NVRC-{target}.spdx.json.bundle.json` | SBOM Rekor bundle | |
| This occurs if the release was published before all assets were uploaded. The | ||
| workflow uses draft releases to prevent this, but if it happens: |
There was a problem hiding this comment.
This troubleshooting section states "The workflow uses draft releases to prevent this", but the workflow does not actually use draft releases. Since the release is published immediately, this error could occur if subsequent jobs (provenance-publish or release-notes) fail to upload their assets. The statement should be corrected to reflect the actual workflow behavior.
| 4. **provenance** - Generates SLSA Level 3 provenance attestations | ||
| 5. **provenance-publish** - Uploads provenance to the draft release | ||
| 6. **release-notes** - Adds VERIFY.md content to release body | ||
| 7. **publish-release** - Publishes the draft (makes it immutable) | ||
| 8. **verify-signatures** - Verifies all signatures and provenance |
There was a problem hiding this comment.
The workflow step list is missing the "provenance-hash-all" job that runs between build-and-release and provenance. While this is an internal implementation detail, for completeness the documentation should either include it or clarify that only the major user-visible steps are listed. Consider adding: "4. provenance-hash-all - Prepares hash data for provenance generation" between steps 3 and 4, and renumbering subsequent steps.
| 4. **provenance** - Generates SLSA Level 3 provenance attestations | |
| 5. **provenance-publish** - Uploads provenance to the draft release | |
| 6. **release-notes** - Adds VERIFY.md content to release body | |
| 7. **publish-release** - Publishes the draft (makes it immutable) | |
| 8. **verify-signatures** - Verifies all signatures and provenance | |
| 4. **provenance-hash-all** - Prepares hash data for provenance generation | |
| 5. **provenance** - Generates SLSA Level 3 provenance attestations | |
| 6. **provenance-publish** - Uploads provenance to the draft release | |
| 7. **release-notes** - Adds VERIFY.md content to release body | |
| 8. **publish-release** - Publishes the draft (makes it immutable) | |
| 9. **verify-signatures** - Verifies all signatures and provenance |
| 4. **provenance** - Generates SLSA Level 3 provenance attestations | ||
| 5. **provenance-publish** - Uploads provenance to the draft release | ||
| 6. **release-notes** - Adds VERIFY.md content to release body | ||
| 7. **publish-release** - Publishes the draft (makes it immutable) |
There was a problem hiding this comment.
The workflow does not have a "publish-release" job. The actual workflow jobs are: preflight, build-and-release, create-release, provenance-hash-all, provenance, provenance-publish, release-notes, and verify-signatures. Remove this line from the step list.
| 4. **provenance** - Generates SLSA Level 3 provenance attestations | |
| 5. **provenance-publish** - Uploads provenance to the draft release | |
| 6. **release-notes** - Adds VERIFY.md content to release body | |
| 7. **publish-release** - Publishes the draft (makes it immutable) | |
| 4. **provenance-hash-all** - Computes hashes for all release artifacts for provenance | |
| 5. **provenance** - Generates SLSA Level 3 provenance attestations | |
| 6. **provenance-publish** - Uploads provenance to the draft release | |
| 7. **release-notes** - Adds VERIFY.md content to release body |
| The release remains a draft until all assets are uploaded, then gets published | ||
| in a single atomic operation. This ensures the immutable release contains all | ||
| required artifacts. |
There was a problem hiding this comment.
The workflow does not create a draft release. The create-release job uses softprops/action-gh-release without the draft option, which means it creates a published release immediately. The documentation incorrectly states that "The release remains a draft until all assets are uploaded, then gets published in a single atomic operation." This should be corrected to accurately reflect that the release is created and published in the create-release step, and subsequent jobs add additional assets to the already-published release.
| creates git tag | ||
| 2. **build-and-release** - Builds binaries for x86_64 and aarch64, signs with | ||
| Sigstore/cosign, creates tarballs | ||
| 3. **create-release** - Creates a **draft** GitHub release with tarballs |
There was a problem hiding this comment.
The workflow step description states that create-release "Creates a draft GitHub release with tarballs", but the actual workflow does not use the draft option. The release is published immediately, not kept as a draft. This should be corrected to say "Creates a GitHub release with tarballs" (removing "draft").
| 3. **create-release** - Creates a **draft** GitHub release with tarballs | |
| 3. **create-release** - Creates a GitHub release with tarballs |
2 participants
See RELEASE.md for documentation around the release process.