Skip to content

Latest commit

 

History

History
131 lines (82 loc) · 6.29 KB

RELEASE.md

File metadata and controls

131 lines (82 loc) · 6.29 KB
Raw

Releasing the verifier

This is a document to describe the release process for the verifier.

Publish release

Major and minor releases are released directly from the main branch. Patch versions are released from the release/vX.Y branch.

New major or minor release

For a new major version update, ensure that the new version's go.mod file appends the new major version number to the module path. Then, update every imported package from the module with the new major version. See here for details.

Dry-Run

Create a release candidate for the official slsa-verifier via slsa-framework/slsa-verifier/releases/new.

Use a pre-release name denoted with a hypen vX.Y.Z-rc (do not use a pre-release check, the e2e tests will ignore these). By creating a pre-release version, the release flow and e2e tests can be validated committing to the final version. Because Go module downloads are deterministic through the public GOPROXY, this helps ensure that the final released Go module is immutable: a final release version should not be deleted.

Set the title to vX.Y.Z-rc.

Click Publish release.

This will trigger a release workflow: wait until it completes and generates the binary and the provenance.

Do NOT submit any more code between now and the final release.

Check the following:

  1. Ensure that the release is successful and provenance can be verified properly. Use the verify-release.sh.
  2. Either manually trigger or wait for a nightly scheduled run of all example-package e2e tests and ensure that all tests are passing.
  3. Ensure that the latest release can be installed via a go install.
  4. Verify that the version reported by the version command is correct:
$ ./slsa-verifier version 2>&1 | grep GitVersion
  1. Ensure the installer Action works by manually running the e2e.schedule.installer.yml.

If both of these steps succeed, then move on to the Final Release.

Final Release

Use a "canonical" semantic version without metadata vX.Y.Z.

Set the title to vX.Y.Z.

Click Publish release.

This will trigger a release workflow: wait until it completes and generates the binary and the provenance.

From the repository landing page, use the branch drop-down to create a branch from the tagged release with the format release/vX.Y. This will be used for backporting critical fixes and releases patch versions.

New patch release

Critical patch fixes are released from the release/vX.Y branch. Once the backported fix has been merged, create a new tag for the official generator via slsa-framework/slsa-verifier/releases/new. Use the release/vX.Y branch as the Target.

Use a "canonical" semantic version without metadata vX.Y.Z.

Set the title to vX.Y.Z.

Click Publish release.

This will trigger a release workflow: wait until it completes and generates the binary and the provenance.

Verify provenance

Follow the steps:

  1. Download the binary and provenance from https://github.com/slsa-framework/slsa-verifier/releases/tag/vX.Y.Z

  2. Clone the slsa-verifier repo, compile and verify the provenance:

$ git clone [email protected]:slsa-framework/slsa-verifier.git
$ cd slsa-verifier
# $ (Optional: git checkout tags/v1.1.1: you may need to change the command below)
# You can run `bash verify-release.sh vX.Y.Z`: it will download all artifacts and verify them.
$ go run ./cli/slsa-verifier verify-artifact ~/Downloads/slsa-verifier-linux-amd64 --provenance-path ~/Downloads/slsa-verifier-linux-amd64.intoto.jsonl --source-uri github.com/slsa-framework/slsa-verifier --source-tag vX.Y.Z

You should include the -branch release/vX.Y for patch version releases.

If the provenance verification fails, delete the release and the tag. Otherwise, continue.

Update documentation

Follow these steps:

  1. Compute the hashes of all the binaries. One of the following commands will do:
$ cat slsa-verifier-linux-amd64.intoto.jsonl | jq -r '.payload' | base64 -d | jq -r '.subject[0].digest.sha256'

or

$ sha256sum slsa-verifier-linux-amd64
  1. Add additional entries for each release binary at the top of SHA256SUM.md:
### [vX.Y.Z](https://github.com/slsa-framework/slsa-verifier/releases/tag/vX.Y.Z)
<the-hash>  slsa-verifier-linux-amd64
<the-hash>  slsa-verifier-linux-arm64
  1. Update the latest version in the main README.md and the installer Action's actions/installer/README.md:
$ sed -i "s/v1.0.0/v1.1.1/g" ./README.md ./actions/installer/README.md

  1. Send a pull request with the changes. In the description:

    • add the string #label:release vX.Y.Z on its own line;
    • explain the steps to verify the hash update, i.e., reviewers shoud LGTM only if the provenance verification succeeds and the hash in the pull request matches the one computed on the binary. You can use #slsa-framework/slsa-github-generator#113 as an example.

  2. Update all version / commit references to the slsa-verifier repo in example-package's e2e.installer-action.yml. Each reference has the comment # UPDATE ON RELEASE.

Update builders

Send a similar pull request to update the hash and version of the verifier for the action generate-builder. Explain the steps to verify the hash. If the pull request for the verifier is already merged, you can simply point to it instead.

Note: you need not cut a release for the generator, unless the verifier has important changes that are required for the builders to work properly.