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 typos and formatting in RELEASE.md #518

Merged
merged 7 commits into from
Jul 25, 2022
Merged

Update typos and formatting in RELEASE.md #518

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a534517
Update typos and formatting in RELEASE.md
ianlewis Jul 10, 2022
630a4e4
Merge branch 'main' into release-docformatting
ianlewis Jul 22, 2022
cf4b909
fix issues after merge
ianlewis Jul 22, 2022
a592889
add indent
ianlewis Jul 22, 2022
7defdf3
update indent
ianlewis Jul 22, 2022
3003e92
update indent
ianlewis Jul 22, 2022
4871c31
Merge branch 'main' into release-docformatting
ianlewis Jul 25, 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
34 changes: 25 additions & 9 deletions RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Releasing the Go builder

This is a document to describe the release process for the Go builder. Since all builders are in this repository, we will expand this doc to cover other builders in the future.
This is a document to describe the release process for the Go builder. Since all builders are in this repository, we will expand this doc to cover other builders in the future.

---

Expand All @@ -13,17 +13,18 @@ This is a document to describe the release process for the Go builder. Since al

---

## Pre-requesites
## Prerequisites

Set up env variables:

```
$ export GH_TOKEN=<PAT-token>
$ export GITHUB_USERNAME="laurentsimon"
# This is the existing slsa-verifier version used by the builder. (https://github.com/slsa-framework/slsa-github-generator/blob/release/bad-verifier/.github/workflows/builder_go_slsa3.yml#L31)
$ export VERIFIER_TAG="v0.0.1"
$ export VERIFIER_TAG="v0.0.1"
$ export VERIFIER_REPOSITORY="$GITHUB_USERNAME/slsa-verifier"
# Release tag of the builder we want to release
$ export BUILDER_TAG="v0.0.2"
$ export BUILDER_TAG="v0.0.2"
# Branch name for our test
$ export BUILDER_REF="release/bad-verifier"
$ export BUILDER_REPOSITORY="$GITHUB_USERNAME/slsa-github-generator"
Expand All @@ -36,7 +37,8 @@ Needless to say, only think about a release when all the e2e tests in [github.co

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.
1. Create a new release for your fork of the slsa-verifier repository with a malicious binary.

```
# Create a release
$ "$GH" release -R "$VERIFIER_REPOSITORY" create "$VERIFIER_TAG" --title "$VERIFIER_TAG" --notes "pre-release tests for builder $BUILDER_TAG $(date)"
Expand All @@ -45,30 +47,36 @@ $ # Note: this will create a release workflow: cancel it in the GitHub UI.
$ echo hello > slsa-verifier-linux-amd64
$ "$GH" release -R "$VERIFIER_REPOSITORY" upload "$VERIFIER_TAG" slsa-verifier-linux-amd64
```

2. Ensure your fork of the builder is at the same commit hash as the offical builder's `$BUILDER_TAG` release.
3. Create a new branch `git checkout -b "$BUILDER_REF"`
4. Update the file `$BUILDER_REPOSITORY/main/.github/workflows/builder_go_slsa3.yml` by replacing the strings `BUILDER_REPOSITORY` and `VERIFIER_REPOSITORY` with your own username (value of `$GITHUB_USERNAME`). Then push the changes.
3. Create a release for your builder for this branch:
5. Create a release for your builder for this branch:

```
$ "$GH" release -R "$BUILDER_REPOSITORY" create "$BUILDER_TAG" --title "$BUILDER_TAG" --notes "pre-release tests for $BUILDER_TAG $(date)" --target "$BUILDER_REF"
```

This will trigger a workflow release, let it complete and generate the release assets.

4. Edit the file [slsa-framework/example-package/.github/workflows/e2e.go.workflow_dispatch.main.adversarial-verifier-binary.slsa3.yml#L14](https://github.com/slsa-framework/example-package/blob/main/.github/workflows/e2e.go.workflow_dispatch.main.adversarial-verifier-binary.slsa3.yml#L14) by using `$BUILDER_REPOSITORY` and `$BUILDER_TAG`:
ianlewis marked this conversation as resolved.
Show resolved Hide resolved

```
uses: $BUILDER_REPOSITORY/.github/workflows/builder_go_slsa3.yml@$BUILDER_TAG
```

5. Run the test manually via the GitHub UX in [https://github.com/slsa-framework/example-package/actions/workflows/e2e.go.workflow_dispatch.main.adversarial-verifier-binary.slsa3.yml](https://github.com/slsa-framework/example-package/actions/workflows/e2e.go.workflow_dispatch.main.adversarial-verifier-binary.slsa3.yml) by cliking `Run Workflow`.
6. Verify the run fails with log message:

```
verifier hash computed is 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
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.
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`.

Expand All @@ -77,6 +85,7 @@ 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"
```
Expand All @@ -86,18 +95,24 @@ $ "$GH" release -R slsa-framework/slsa-github-generator download "$BUILDER_TAG"
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).

For this:

1. Make sure you have downloaded the `$BUILDER_TAG` builder's binary locally `slsa-builder-go-linux-amd64`, either via the web UI or via:

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

2. Upload a different binary to the assets:

```
$ echo hello > slsa-builder-go-linux-amd64
$ "$GH" release -R slsa-framework/slsa-github-generator upload "$BUILDER_TAG" slsa-builder-go-linux-amd64 --clobber
```

3. Update the version of the workflow [slsa-framework/example-package/.github/workflows/e2e.go.workflow_dispatch.main.adversarial-builder-binary.slsa3.yml#L14](https://github.com/slsa-framework/example-package/blob/main/.github/workflows/e2e.go.workflow_dispatch.main.adversarial-builder-binary.slsa3.yml#L14) with the `$BUILDER_TAG` to test.
4. Trigger the test in [slsa-framework/example-package/actions/workflows/e2e.go.workflow_dispatch.main.adversarial-builder-binary.slsa3.yml](https://github.com/slsa-framework/example-package/actions/workflows/e2e.go.workflow_dispatch.main.adversarial-builder-binary.slsa3.yml) by cliking `Run workflow`. Verify that it fails, with a message:

```
verifier hash computed is 60c91c9d5b9a059e37ac46da316f20c81da335b5d00e1f74d03dd50f819694bd
verifier hash verification has passed
Expand All @@ -109,6 +124,7 @@ Error: Process completed with exit code 6.
If it does not, delete the release, fix the bug and re-start the release process at the top of this page.

4. If the test above failed with the expected message, re-upload the original binary back to the assets, e.g. via:
ianlewis marked this conversation as resolved.
Show resolved Hide resolved

```
$ mv slsa-builder-go-linux-amd64-"$BUILDER_TAG".original slsa-builder-go-linux-amd64
$ "$GH" release -R slsa-framework/slsa-github-generator upload "$BUILDER_TAG" slsa-builder-go-linux-amd64 --clobber
Expand All @@ -130,7 +146,7 @@ Send a pull request to merge the changes into the verifier's repository. The pre

## Finalize release

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

Update the documentation to recommend using the new version:

Expand Down