Skip to content

Commit

Permalink
docs: Add known issue for #1702 (#1733)
Browse files Browse the repository at this point in the history 
Signed-off-by: Ian Lewis <ianlewis@google.com>
  • Loading branch information
Ian Lewis authored Mar 6, 2023
1 parent ef939e0 commit 94238bc
Showing 1 changed file with 104 additions and 72 deletions.
176 changes: 104 additions & 72 deletions internal/builders/generic/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -229,16 +229,16 @@ The [generic workflow](https://github.com/slsa-framework/slsa-github-generator/b
| `provenance-name` | no | "(subject name).intoto.jsonl" if a single subject. "multiple.intoto.json" if multiple subjects. | The artifact name of the signed provenance. The file must have the `intoto.jsonl` extension. |
| `attestation-name` | no | "(subject name).intoto.jsonl" if a single subject. "multiple.intoto.json" if multiple subjects. | The artifact name of the signed provenance. The file must have the `intoto.jsonl` extension. DEPRECATED: use `provenance-name` instead. |
| `private-repository` | no | false | Set to true to opt-in to posting to the public transparency log. Will generate an error if false for private repositories. This input has no effect for public repositories. See [Private Repositories](#private-repositories). |
| `continue-on-error` | no | false | Set to true to ignore errors. This option is useful if you won't want a failure to fail your entire workflow.|
| `continue-on-error` | no | false | Set to true to ignore errors. This option is useful if you won't want a failure to fail your entire workflow. |

### Workflow Outputs

The [generic workflow](https://github.com/slsa-framework/slsa-github-generator/blob/main/.github/workflows/generator_generic_slsa3.yml) produces the following outputs:

| Name | Description |
| ------------------ | -------------------------------------------------------------------------------------- |
| `provenance-name` | The artifact name of the signed provenance. |
| `attestation-name` | The artifact name of the signed provenance. DEPRECATED: use `provenance-name` instead. |
| Name | Description |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| `provenance-name` | The artifact name of the signed provenance. |
| `attestation-name` | The artifact name of the signed provenance. DEPRECATED: use `provenance-name` instead. |
| `outcome` | If `continue-on-error` is `true`, will contain the outcome of the run (`success` or `failure`). |

### Provenance Format
Expand Down Expand Up @@ -332,6 +332,7 @@ If you use [GoReleaser](https://github.com/goreleaser/goreleaser-action) to gene
generate SLSA3 provenance by updating your existing workflow with the steps indicated in the workflow below:

**Notes**:

- Make sure you did not disable checksum generation in the goreleaser yml.
- Make sure you specified sha256 as the algorithm for the checksum or left it empty (sha256 is the default).
- To enable provenance generation for dockers (as well as artifacts), use [goreleaser version >= v1.13.0](https://github.com/goreleaser/goreleaser/releases/tag/v1.13.0).
Expand Down Expand Up @@ -919,11 +920,13 @@ jobs:
```

### Provenance for Python

If you develop with Python you can
easily generate SLSA3 provenance by updating your existing workflow with the
steps indicated in the workflow below:

1. Declare an outputs for the artifacts generated by the build and their hashes:

```yaml
jobs:
build:
Expand Down Expand Up @@ -967,6 +970,7 @@ steps:
```

4. Call the generic workflow to generate provenance by declaring the job below:

```yaml
provenance:
needs: [build]
Expand Down Expand Up @@ -1038,7 +1042,7 @@ Regardless of your choice, there's unfortunately a bit of necessary boilerplate.
### A single provenance attestation for all artifacts

1. As with the examples above, the first thing to do is define the build job,
with its outputs and its matrix strategy.
with its outputs and its matrix strategy.

GitHub currently doesn't support different outputs for matrix builds. We must
therefore declare a different hash output for each iteration. A follow-up job
Expand All @@ -1053,69 +1057,69 @@ jobs:
flavor: ["mint", "vanilla"]
outputs:
# The key-names are actually irrelevant, but keep them descriptive
hash-red-mint: ${{ steps.hash.outputs.hash-red-mint }}
hash-red-vanilla: ${{ steps.hash.outputs.hash-red-vanilla }}
hash-blue-mint: ${{ steps.hash.outputs.hash-blue-mint }}
hash-blue-vanilla: ${{ steps.hash.outputs.hash-blue-vanilla }}
hash-green-mint: ${{ steps.hash.outputs.hash-green-mint }}
hash-red-mint: ${{ steps.hash.outputs.hash-red-mint }}
hash-red-vanilla: ${{ steps.hash.outputs.hash-red-vanilla }}
hash-blue-mint: ${{ steps.hash.outputs.hash-blue-mint }}
hash-blue-vanilla: ${{ steps.hash.outputs.hash-blue-vanilla }}
hash-green-mint: ${{ steps.hash.outputs.hash-green-mint }}
hash-green-vanilla: ${{ steps.hash.outputs.hash-green-vanilla }}
````
```

2. You'll now have to build your project as usual:

```yml
steps:
# whatever you need to do to build (checkout, setup the environment,
# get dependencies, compile...)
- ...
- ...
- ...
steps:
# whatever you need to do to build (checkout, setup the environment,
# get dependencies, compile...)
- ...
- ...
- ...
```

3. As with the other examples, you'll then have to generate the hashes that
represent your build. This step is effectively identical to all the examples
above, except each iteration must store its hash in a different output
variable.
represent your build. This step is effectively identical to all the examples
above, except each iteration must store its hash in a different output
variable.

```yml
- name: Generate subject
id: hash
run: |
echo "hash-${{ matrix.color }}-${{ matrix.flavor }}=$( \
sha256sum ... | base64 -w0 \
)" >> "$GITHUB_OUTPUT"
- name: Generate subject
id: hash
run: |
echo "hash-${{ matrix.color }}-${{ matrix.flavor }}=$( \
sha256sum ... | base64 -w0 \
)" >> "$GITHUB_OUTPUT"
```

4. Now you'll collate all the individual hashes into a single bas64 string.

```yml
combine_hashes:
needs: [build]
outputs:
hashes: ${{ steps.hashes.outputs.hashes }}
env:
HASHES: ${{ toJSON(needs.build.outputs) }}
steps:
- id: hashes
run: |
echo "$HASHES" | jq -r '.[] | @base64d' | sed "/^$/d" > hashes.txt
echo "hashes=$(cat hashes.txt | base64 -w0)" >> "$GITHUB_OUTPUT"
combine_hashes:
needs: [build]
outputs:
hashes: ${{ steps.hashes.outputs.hashes }}
env:
HASHES: ${{ toJSON(needs.build.outputs) }}
steps:
- id: hashes
run: |
echo "$HASHES" | jq -r '.[] | @base64d' | sed "/^$/d" > hashes.txt
echo "hashes=$(cat hashes.txt | base64 -w0)" >> "$GITHUB_OUTPUT"
```

5. The provenance job is also effectively identical to the examples above,
except that it relies on `combine_hashes` instead of the `build` job.
except that it relies on `combine_hashes` instead of the `build` job.

```yml
provenance:
needs: [combine_hashes]
permissions:
actions: read # To read the workflow path.
id-token: write # To sign the provenance.
contents: write # To add assets to a release.
uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v1.5.0
with:
base64-subjects: "${{ needs.combine_hashes.outputs.hashes }}"
upload-assets: true # Optional: Upload to a new release
provenance:
needs: [combine_hashes]
permissions:
actions: read # To read the workflow path.
id-token: write # To sign the provenance.
contents: write # To add assets to a release.
uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v1.5.0
with:
base64-subjects: "${{ needs.combine_hashes.outputs.hashes }}"
upload-assets: true # Optional: Upload to a new release
```

Now all together:
Expand All @@ -1128,11 +1132,11 @@ jobs:
color: ["red", "blue", "green"]
flavor: ["mint", "vanilla"]
outputs:
hash-red-mint: ${{ steps.hash.outputs.hash-red-mint }}
hash-red-vanilla: ${{ steps.hash.outputs.hash-red-vanilla }}
hash-blue-mint: ${{ steps.hash.outputs.hash-blue-mint }}
hash-blue-vanilla: ${{ steps.hash.outputs.hash-blue-vanilla }}
hash-green-mint: ${{ steps.hash.outputs.hash-green-mint }}
hash-red-mint: ${{ steps.hash.outputs.hash-red-mint }}
hash-red-vanilla: ${{ steps.hash.outputs.hash-red-vanilla }}
hash-blue-mint: ${{ steps.hash.outputs.hash-blue-mint }}
hash-blue-vanilla: ${{ steps.hash.outputs.hash-blue-vanilla }}
hash-green-mint: ${{ steps.hash.outputs.hash-green-mint }}
hash-green-vanilla: ${{ steps.hash.outputs.hash-green-vanilla }}
steps:
# all your build steps
Expand Down Expand Up @@ -1195,19 +1199,19 @@ use its values to define unique names for each provenance attestation using the
function.

```yml
provenance:
needs: [build]
matrix:
color: ["red", "blue", "green"]
flavor: ["mint", "vanilla"]
permissions:
actions: read # To read the workflow path.
id-token: write # To sign the provenance.
contents: write # To add assets to a release.
uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v1.5.0
with:
base64-subjects: "${{ needs.build.outputs[format('hash-{0}-{1}', matrix.color, matrix.flavor)] }}"
upload-assets: true # Optional: Upload to a new release
provenance:
needs: [build]
matrix:
color: ["red", "blue", "green"]
flavor: ["mint", "vanilla"]
permissions:
actions: read # To read the workflow path.
id-token: write # To sign the provenance.
contents: write # To add assets to a release.
uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v1.5.0
with:
base64-subjects: "${{ needs.build.outputs[format('hash-{0}-{1}', matrix.color, matrix.flavor)] }}"
upload-assets: true # Optional: Upload to a new release
```

So, all together, this version becomes:
Expand All @@ -1220,11 +1224,11 @@ jobs:
color: ["red", "blue", "green"]
flavor: ["mint", "vanilla"]
outputs:
hash-red-mint: ${{ steps.hash.outputs.hash-red-mint }}
hash-red-vanilla: ${{ steps.hash.outputs.hash-red-vanilla }}
hash-blue-mint: ${{ steps.hash.outputs.hash-blue-mint }}
hash-blue-vanilla: ${{ steps.hash.outputs.hash-blue-vanilla }}
hash-green-mint: ${{ steps.hash.outputs.hash-green-mint }}
hash-red-mint: ${{ steps.hash.outputs.hash-red-mint }}
hash-red-vanilla: ${{ steps.hash.outputs.hash-red-vanilla }}
hash-blue-mint: ${{ steps.hash.outputs.hash-blue-mint }}
hash-blue-vanilla: ${{ steps.hash.outputs.hash-blue-vanilla }}
hash-green-mint: ${{ steps.hash.outputs.hash-green-mint }}
hash-green-vanilla: ${{ steps.hash.outputs.hash-green-vanilla }}
steps:
# all your build steps
Expand Down Expand Up @@ -1253,6 +1257,34 @@ jobs:

## Known Issues

### 'internal error' when using using `upload-assets`

**Affected versions:** v1.5.0

When setting `upload-assets` to `true` when the trigger occurred on a git ref
that is a not a tag (e.g. a push to a branch), the workflow would fail with
`'internal error'` if `upload-tag-name` input was not specified.

Prior to 1.5.0 `upload-assets` was ignored if a tag name could not be determined
by the git ref.

Please set the following to `upload-assets`:

```yaml
upload-assets: ${{ startsWith(github.ref, 'refs/tags/') }}
```

or specify a value for `upload-tag-name`:

```yaml
upload-assets: true
upload-tag-name: "v1.0.0"
```

See issue
[#1702](https://github.com/slsa-framework/slsa-github-generator/issues/1702) for
more details.

### error updating to TUF remote mirror: tuf: invalid key

**Affected versions:** v1.2.x
Expand Down

0 comments on commit 94238bc

Please sign in to comment.