diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..7f2dcc4 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,140 @@ +# NVRC Release Process + +This document describes how to create a new NVRC release. + +## Prerequisites + +- Write access to the repository +- Ability to merge PRs to `main` branch + +## Important: Immutable Releases + +This repository has **Immutable Releases** enabled as a security measure. Once a +release is published: + +- Release assets cannot be modified or added +- The tag cannot be reused, even if deleted +- Each release attempt requires a unique version number + +If a release workflow fails after creating the tag, you must bump the version +and try again. There is no way to "retry" with the same version. + +**Note:** Even if you disable immutable releases after a failed release attempt, +you still cannot reuse the same version number. GitHub permanently remembers +that the tag/release existed. You must always bump to a new version. + +## Release Workflow + +### Step 1: Bump Version in Cargo.toml + +Create a PR that updates the version in `Cargo.toml`: + +```toml +[package] +name = "NVRC" +version = "X.Y.Z" # Update this +``` + +The version in `Cargo.toml` is the **source of truth** for release tags. The +workflow automatically derives the tag name as `vX.Y.Z` from this version. + +Merge the PR to `main` after review. + +### Step 2: Trigger the Release Workflow + +1. Go to **Actions** in the GitHub repository +2. Select **Release NVRC** workflow from the left sidebar +3. Click **Run workflow** +4. Ensure **main** branch is selected (this is the default and required) +5. Click the green **Run workflow** button + +**Important:** Always run from `main` branch. The signature verification step +validates that artifacts were built from `main` using certificate constraints +like `--certificate-github-workflow-ref`. + +### Step 3: Monitor the Workflow + +The release workflow performs these steps: + +1. **preflight** - Derives tag from `Cargo.toml`, checks no existing 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 +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 + +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. + +## Troubleshooting + +### "Release already exists" Error + +If preflight fails with "Release already exists", a previous release attempt +partially succeeded. With immutable releases enabled, you cannot reuse the +version. Bump the version in `Cargo.toml` and try again. + +### "Cannot upload assets to an immutable release" Error + +This occurs if the release was published before all assets were uploaded. The +workflow uses draft releases to prevent this, but if it happens: + +1. Delete the release: `gh release delete vX.Y.Z --repo NVIDIA/nvrc --yes` +2. Delete the tag: `gh api -X DELETE repos/NVIDIA/nvrc/git/refs/tags/vX.Y.Z` +3. Bump version and retry (required if immutable releases is enabled) + +### Tag Creation Fails + +If tag creation fails with repository rule violations, there may be org-level +restrictions. Contact the repository administrator. + +### Signature Verification Fails + +The verify-signatures job validates: + +- Cosign keyless signatures (online via Rekor) +- Cosign bundle signatures (offline verification) +- SLSA provenance (via slsa-verifier) + +Failures here indicate a problem with the signing process or certificate +constraints. Check that the workflow ran from `main` branch. + +## Release Artifacts + +Each release includes per-architecture: + +| File | Description | +| ------------------------------------------ | ---------------------------------------- | +| `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 | + +## Verifying a Release + +The release workflow automatically runs signature verification as the final step +(`verify-signatures` job) to ensure all artifacts are correctly signed before +the release is considered complete. This serves as a sanity check that the +signing and publishing process succeeded. + +For manual verification of downloaded releases, see [VERIFY.md](VERIFY.md) for +instructions on verifying release signatures and provenance.