Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update release instructions #1212

Merged
merged 5 commits into from
Nov 7, 2022
Merged

Update release instructions #1212

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f338a15
Update release instructions
ianlewis Nov 7, 2022
665da66
fix url fragment
ianlewis Nov 7, 2022
40c8d14
fix order in TOC
ianlewis Nov 7, 2022
b8c95fb
Match 'main' or any version number
ianlewis Nov 7, 2022
bd3b1ff
Merge branch 'main' into release-instructions
ianlewis Nov 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 26 additions & 24 deletions RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ This is a document to describe the release process for the Go builder. Since all

- [Pre-release](#pre-release-tests)
- [Tagging](#tagging)
- [Verify version references & code freeze](#verify-version-references--code-freeze)
- [Post-release tests](#post-release-tests)
- [Update Verifier](#update-verifier)
- [Finalize release](#finalize-release)
Expand All @@ -31,20 +32,37 @@ $ export BUILDER_REPOSITORY="$GITHUB_USERNAME/slsa-github-generator"
$ export GH=/path/to/gh
```

## Pre-release tests
## Tagging

Create a new tag for the official generator via [slsa-framework/slsa-github-generator/releases/new](https://github.com/slsa-framework/slsa-github-generator/releases/new).
The tag _MUST_ be a "canonical" semantic version without metadata (`$BUILDER_TAG`). Shorter versions are not accepted by the builder's and verifier's code.

Set the title to `$BUILDER_TAG`.

Tick the `This is a pre-release` option.

Click `Publish release`.

## Verify version references & code freeze

Verify the references to the internal Actions by manually running the [release workflow](https://github.com/slsa-framework/slsa-github-generator/actions/workflows/release.yml). Ensure this workflow succeeds. If the references are still `@main`, update them with the following command:
Update version references with the following command:

```shell
find .github/workflows/ -name '*.yaml' -o -name '*.yml' | xargs sed -i 's/uses: slsa-framework\/slsa-github-generator\/\.github\/actions\/\(.*\)@main*/uses: slsa-framework\/slsa-github-generator\/.github\/actions\/\1@_YOUR_RELEASE_TAG_/'
find .github/workflows/ -name '*.yaml' -o -name '*.yml' | xargs sed -i "s/uses: slsa-framework\/slsa-github-generator\/\.github\/actions\/\(.*\)@\(main\|v[0-9]\+\.[0-9]\+\.[0-9]\+\)/uses: slsa-framework\/slsa-github-generator\/.github\/actions\/\1@$BUILDER_TAG/"
```

Send a PR with this update and add `#label:release ${BUILDER_TAG}` in the PR description.

Once the PR is merged, update the tag to point to HEAD.

Code freeze the repository for 1-2 days.

Verify all the e2e tests in [github.com/slsa-framework/example-package/.github/workflows/](github.com/slsa-framework/example-package/.github/workflows/) are passing. (They run daily).

## Pre-release tests

Verify the references to the internal Actions by manually running the [release workflow](https://github.com/slsa-framework/slsa-github-generator/actions/workflows/release.yml). Ensure this workflow succeeds.

There is one integration test we cannot easily test "live", so we need to simulate it by changing the code: malicious verifier binary in assets. We want to be sure the builder fails if the verifier's binary is tampered with. For this:

1. Create a new release for your fork of the slsa-verifier repository with a malicious binary.
Expand Down Expand Up @@ -116,23 +134,6 @@ There is one integration test we cannot easily test "live", so we need to simula
Error: Process completed with exit code 4.
```

## Tagging

Create a new tag for the official generator via [slsa-framework/slsa-github-generator/releases/new](https://github.com/slsa-framework/slsa-github-generator/releases/new).
The tag _MUST_ be a "canonical" semantic version without metadata (`$BUILDER_TAG`). Shorter versions are not accepted by the builder's and verifier's code.

Set the title to `$BUILDER_TAG`.

Tick the `This is a pre-release` option.

Click `Publish release`.

Download the generated binary `slsa-builder-go-linux-amd64` locally on your machine:

```
$ "$GH" release -R slsa-framework/slsa-github-generator download "$BUILDER_TAG" -p "slsa-builder-go-linux-amd64"
```

## Post-release tests

End-to-end tests run daily in [github.com/slsa-framework/example-package/.github/workflows/](github.com/slsa-framework/example-package/.github/workflows/), and contain adversarial tests (developer tampers with the artifacts used by the builders). All these adversarial tests compile the builder from source (`compile-builder: true`). But we need to verify that the builder detects malicious builder's binary when `compile-builder: false` (default).
Expand Down Expand Up @@ -226,13 +227,14 @@ For each of the GHA builders, you will need to:
1. Generate binaries and provenance in [example-package](https://github.com/slsa-framework/example-package) using the GHA action builder. These require using the updated builders, so validate that the workflows you use below are pinned at `$BUILDER_TAG`.

You will need the following trigger types:
* A workflow dispatch event.
* A tag of the form `vX.Y.Z`.
* Tags of the form `vX` and `vX.Y`.

- A workflow dispatch event.
- A tag of the form `vX.Y.Z`.
- Tags of the form `vX` and `vX.Y`.

To do this, trigger the [Go workflow dispatch](https://github.com/slsa-framework/example-package/blob/main/.github/workflows/verifier-e2e.go.workflow_dispatch.main.all.slsa3.yml) and [Generic workflow dispatch](https://github.com/slsa-framework/example-package/blob/main/.github/workflows/verifier-e2e.generic.workflow_dispatch.main.all.slsa3.yml). These will dispatch the workflow and create provenance for the workflow dispatch event, and then trigger subsequent runs on fixed tags.

Download the uploaded artifacts of each of these, labelling the workflow dispatch artifacts by `binary-linux-amd64-workflow_dispatch(.intoto.jsonl)` and the tags by `binary-linux-amd64-push-v$TAG(.intoto.jsonl)`.
Download the uploaded artifacts of each of these, labelling the workflow dispatch artifacts by `binary-linux-amd64-workflow_dispatch(.intoto.jsonl)` and the tags by `binary-linux-amd64-push-v$TAG(.intoto.jsonl)`.

2. Move these files to `./cli/slsa-verifier/testdata/gha_$BUILDER_TYPE/$BUILDER_TAG/`. Send a pull request to merge the changes into the verifier's repository. The pre-submits will validate that the verifier is able to verify provenance from the `$BUILDER_TAG` builder.

Expand Down