You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: internal/builders/generic/README.md
+17
Original file line number
Diff line number
Diff line change
@@ -19,6 +19,7 @@ project simply generates provenance as a separate step in an existing workflow.
19
19
-[Benefits of Provenance](#benefits-of-provenance)
20
20
-[Generating Provenance](#generating-provenance)
21
21
-[Getting Started](#getting-started)
22
+
-[Supported Triggers](#supported-triggers)
22
23
-[Workflow Inputs](#workflow-inputs)
23
24
-[Workflow Outputs](#workflow-outputs)
24
25
-[Provenance Format](#provenance-format)
@@ -157,6 +158,22 @@ jobs:
157
158
${{needs.provenance.outputs.attestation-name}}
158
159
```
159
160
161
+
### Supported Triggers
162
+
163
+
The following [GitHub trigger events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows) are fully supported and tested:
164
+
165
+
- `schedule`
166
+
- `push`(including new tags)
167
+
- `release`
168
+
- Manual run via `workflow_dispatch`
169
+
170
+
However, in practice, most triggers should work with the exception of
171
+
`pull_request`. If you would like support for `pull_request`, please tell us
172
+
about your use case on [issue
173
+
#358](https://github.com/slsa-framework/slsa-github-generator/issues/358). If
174
+
you have an issue in all other triggers please submit a [new
Copy file name to clipboardExpand all lines: internal/builders/go/README.md
+48-44
Original file line number
Diff line number
Diff line change
@@ -1,33 +1,37 @@
1
-
# Generation of SLSA3+ provenance for Golang projects
1
+
# Generation of SLSA3+ provenance for Go projects
2
2
3
-
This document explains how to use the builder for Golang projects.
3
+
This document explains how to use the builder for [Go](https://go.dev/) projects.
4
4
5
5
---
6
6
7
7
[Generation of provenance](#generation)
8
8
9
-
-[Supported triggers](#supported-triggers)
10
-
-[Configuration file](#configuration-file)
9
+
-[Supported Triggers](#supported-triggers)
10
+
-[Configuration File](#configuration-file)
11
11
-[Migration from goreleaser](#migration-from-goreleaser)
12
-
-[Workflow inputs](#workflow-inputs)
12
+
-[Workflow Inputs](#workflow-inputs)
13
13
-[Workflow Example](#workflow-example)
14
-
-[Example provenance](#example-provenance)
15
-
-[BuildConfig format](#buildconfig-format)
14
+
-[Provenance Example](#provenance-example)
15
+
-[BuildConfig Format](#buildconfig-format)
16
16
17
17
---
18
18
19
19
## Generation
20
20
21
-
To generate provenance for a golang binary, follow the steps below:
21
+
To generate provenance for a Go binary, follow the steps below:
22
22
23
-
### Supported triggers
23
+
### Supported Triggers
24
24
25
-
Most GitHub trigger events are supported, at the exception of `pull_request`. We have extensively tested the
26
-
following triggers: `schedule`, `push` (including new tags), `release` and manual `workflow_dispatch`.
25
+
The following [GitHub trigger events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows) are fully supported and tested:
27
26
28
-
If you would like support for `pull_request`, please tell us about your use case and [file an issue](https://github.com/slsa-framework/slsa-github-generator/issues/new).
27
+
-`schedule`
28
+
-`push` (including new tags)
29
+
-`release`
30
+
- Manual run via `workflow_dispatch`
29
31
30
-
### Configuration file
32
+
However, in practice, most triggers should work with the exception of `pull_request`. If you would like support for `pull_request`, please tell us about your use case on [issue #358](https://github.com/slsa-framework/slsa-github-generator/issues/358). If you have an issue in all other triggers please submit a [new issue](https://github.com/slsa-framework/slsa-github-generator/issues/new/choose).
33
+
34
+
### Configuration File
31
35
32
36
Define a configuration file called `.slsa-goreleaser.yml` in the root of your project.
33
37
@@ -46,7 +50,7 @@ flags:
46
50
- -tags=netgo
47
51
48
52
# The OS to compile for. `GOOS` env variable will be set to this value.
49
-
goos: linux
53
+
goos: linux
50
54
51
55
# The architecture to compile for. `GOARCH` env variable will be set to this value.
# (Optional) ldflags generated dynamically in the workflow, and set as the `evaluated-envs` input variables in the workflow.
66
70
ldflags:
67
-
- '-X main.Version={{ .Env.VERSION }}'
68
-
- '-X main.Commit={{ .Env.COMMIT }}'
69
-
- '-X main.CommitDate={{ .Env.COMMIT_DATE }}'
70
-
- '-X main.TreeState={{ .Env.TREE_STATE }}'
71
+
- "-X main.Version={{ .Env.VERSION }}"
72
+
- "-X main.Commit={{ .Env.COMMIT }}"
73
+
- "-X main.CommitDate={{ .Env.COMMIT_DATE }}"
74
+
- "-X main.TreeState={{ .Env.TREE_STATE }}"
71
75
```
72
76
73
77
### Migration from goreleaser
74
78
75
-
If you are already using Goreleaser, you may be able to migrate to our builder using multiple config files for each build. However, this is cumbersome and we are working on supporting multiple builds in a single config file for future releases.
79
+
If you are already using Goreleaser, you may be able to migrate to our builder using multiple config files for each build. However, this is cumbersome and we are working on supporting multiple builds in a single config file for future releases.
76
80
77
81
In the meantime, you can use both Goreleaser and this builder in the same repository. For example, you can pick one build you would like to start generating provenance for. Goreleaser and this builder can co-exist without interfering with one another, so long as the resulting binaries have different names (e.g., when building for different OS/Arch). If you want to keep the same name, you can use the Goreleaser `ignore` option in the `.goreleaser.yml`:
78
82
@@ -97,38 +101,38 @@ We think gradual adoption is good for projects to get used to SLSA.
97
101
98
102
The configuration file accepts many of the common fields Goreleaser uses, as you can see in the [example](#configuration-file). The configuration file also supports two variables: `{{ .Os }}` and `{{ .Arch }}`. Other variables can be set manually as shows in the table below, in combination with the builder's `evaluated-envs`:
| `{{ .ShortCommit }}` | `$(echo $GITHUB_SHA \| cut -c1-8)` or `$(git rev-parse HEAD \| cut -c1-8)` | `b2a98088` |
105
-
| `{{ .Version }}` | `$(git describe --tags --always --dirty \| cut -c2-)` or `$(echo $GITHUB_REF_NAME \| cut -c2-)` on new tags and release triggers | `1.2.3-alpha+b2a98088` |
106
-
| `{{ .Tag }}` | `$GITHUB_REF_NAME` (on `release` and `push` new tag triggers) or `$(git describe --tags --always --dirty \| cut -c2-)` | `v1.2.3-alpha+b2a98088` |
| `{{ .ShortCommit }}` | `$(echo $GITHUB_SHA \| cut -c1-8)` or `$(git rev-parse HEAD \| cut -c1-8)` | `b2a98088` |
109
+
| `{{ .Version }}` | `$(git describe --tags --always --dirty \| cut -c2-)` or `$(echo $GITHUB_REF_NAME \| cut -c2-)` on new tags and release triggers | `1.2.3-alpha+b2a98088` |
110
+
| `{{ .Tag }}` | `$GITHUB_REF_NAME` (on `release` and `push` new tag triggers) or `$(git describe --tags --always --dirty \| cut -c2-)` | `v1.2.3-alpha+b2a98088` |
If you think you need suppport for other variables, please [open an issue](https://github.com/slsa-framework/slsa-github-generator/issues/new).
112
116
113
-
### Workflow inputs
117
+
### Workflow Inputs
114
118
115
119
The builder workflow [slsa-framework/slsa-github-generator/.github/workflows/builder_go_slsa3.yml](.github/workflows/builder_go_slsa3.yml) accepts the following inputs:
| `config-file` | no | `.github/workflows/slsa-goreleaser.yml` | The configuration file for the builder. A path within the calling repository. |
120
-
| `evaluated-envs` | no | empty value | A list of environment variables, seperated by `,`: `VAR1: value, VAR2: value`. This is typically used to pass dynamically-generated values, such as `ldflags`. Note that only environment variables with names starting with `CGO_` or `GO` are accepted. |
121
-
| `go-version` | yes | The go version for your project. This value is passed, unchanged, to the [actions/setup-go](https://github.com/actions/setup-go) action when setting up the environment |
122
-
| `upload-assets` | no | true on new tags | Whether to upload assets to a GitHub release or not. |
| `config-file` | no | `.github/workflows/slsa-goreleaser.yml` | The configuration file for the builder. A path within the calling repository. |
124
+
| `evaluated-envs` | no | empty value | A list of environment variables, seperated by `,`: `VAR1: value, VAR2: value`. This is typically used to pass dynamically-generated values, such as `ldflags`. Note that only environment variables with names starting with `CGO_` or `GO` are accepted. |
125
+
| `go-version` | yes | The go version for your project. This value is passed, unchanged, to the [actions/setup-go](https://github.com/actions/setup-go) action when setting up the environment |
126
+
| `upload-assets` | no | true on new tags | Whether to upload assets to a GitHub release or not. |
123
127
124
128
### Workflow Example
125
129
126
130
Create a new workflow, say `.github/workflows/slsa-goreleaser.yml`.
127
131
128
-
Make sure that you reference the trusted builder with a semnatic version of the form `vX.Y.Z`. The build will fail
129
-
if you reference it via a shorter tag like `vX.Y` or `vX`.
132
+
Make sure that you reference the trusted builder with a semantic version of the form `vX.Y.Z`. The build will fail
133
+
if you reference it via a shorter tag like `vX.Y` or `vX`.
130
134
131
-
Refencing via hash is currently not supported due to limitations
135
+
Referencing via hash is currently not supported due to limitations
132
136
of the reusable workflow APIs. (We are working with GitHub to address this limitation).
0 commit comments