Document buildType (#1)
* add schema Signed-off-by: Brian DeHamer <bdehamer@github.com> * reformat Signed-off-by: Brian DeHamer <bdehamer@github.com> * set-up GH pages redirects Signed-off-by: Brian DeHamer <bdehamer@github.com> * fix required elements Signed-off-by: Brian DeHamer <bdehamer@github.com> --------- Signed-off-by: Brian DeHamer <bdehamer@github.com>
This commit is contained in:
Brian DeHamer
@@ -6,5 +6,5 @@ GitHub Actions.
|
||||
|
||||
## What's in this repo
|
||||
|
||||
- [workflow/v1](workflow/v1): `buildType` for a top-level GitHub Actions
|
||||
Workflow.
|
||||
- [workflow/v1](workflow/v1): `buildType` for a top-level GitHub Actions
|
||||
Workflow.
|
||||
|
||||
0
docs/.nojekyll
Normal file
0
docs/.nojekyll
Normal file
7
docs/index.html
Normal file
7
docs/index.html
Normal file
@@ -0,0 +1,7 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en-US">
|
||||
<title>Redirecting…</title>
|
||||
<meta http-equiv="refresh" content="0; url=https://github.com/actions/buildtypes">
|
||||
<link rel="canonical" href="https://github.com/actions/buildtypes">
|
||||
<meta name="robots" content="noindex">
|
||||
</html>
|
||||
1
docs/workflow/index.html
Symbolic link
1
docs/workflow/index.html
Symbolic link
@@ -0,0 +1 @@
|
||||
v1.html
|
||||
7
docs/workflow/v1.html
Normal file
7
docs/workflow/v1.html
Normal file
@@ -0,0 +1,7 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en-US">
|
||||
<title>Redirecting…</title>
|
||||
<meta http-equiv="refresh" content="0; url=https://github.com/actions/buildtypes/blob/main/workflow/v1/">
|
||||
<link rel="canonical" href="https://github.com/actions/buildtypes/blob/main/workflow/v1/">
|
||||
<meta name="robots" content="noindex">
|
||||
</html>
|
||||
168
workflow/v1/README.md
Normal file
168
workflow/v1/README.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# Build Type: GitHub Actions Workflow
|
||||
|
||||
This is a GitHub-maintained [SLSA Provenance](https://slsa.dev/provenance/v1)
|
||||
`buildType` that describes the execution of a GitHub Actions workflow.
|
||||
|
||||
## Description
|
||||
|
||||
```jsonc
|
||||
"buildType": "https://actions.github.io/buildtypes/workflow/v1"
|
||||
```
|
||||
|
||||
This `buildType` describes the execution of a top-level [GitHub Actions]
|
||||
workflow that builds a software artifact.
|
||||
|
||||
Only the following [event types] are supported:
|
||||
|
||||
| Supported event type | Event description |
|
||||
| --------------------- | ------------------------------------------ |
|
||||
| [`create`] | Creation of a git tag or branch. |
|
||||
| [`release`] | Creation or update of a GitHub release. |
|
||||
| [`push`] | Creation or update of a git tag or branch. |
|
||||
| [`workflow_dispatch`] | Manual trigger of a workflow. |
|
||||
|
||||
[`create`]:
|
||||
https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#create
|
||||
[`release`]:
|
||||
https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#release
|
||||
[`push`]:
|
||||
https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push
|
||||
[`workflow_dispatch`]:
|
||||
https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch
|
||||
|
||||
This build type MUST NOT be used for any other event type unless this
|
||||
specification is first updated. Other event types are irrelevant for software
|
||||
builds (such as `issues`) or have complex semantics that may be error prone or
|
||||
require further analysis (such as `pull_request` or `repository_dispatch`). To
|
||||
add support for another event type, please open a [GitHub Issue].
|
||||
|
||||
Note: Consumers SHOULD reject unrecognized external parameters, so new event
|
||||
types can be added without a major version bump as long as they do not change
|
||||
the semantics of existing external parameters.
|
||||
|
||||
[GitHub Issue]: https://github.com/actions/buildtypes/issues
|
||||
[GitHub Actions]: https://docs.github.com/en/actions
|
||||
[event types]:
|
||||
https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows
|
||||
|
||||
## Build Definition
|
||||
|
||||
### External parameters
|
||||
|
||||
[External parameters]: #external-parameters
|
||||
|
||||
All external parameters are REQUIRED unless empty.
|
||||
|
||||
<table>
|
||||
<tr><th>Parameter<th>Type<th>Description
|
||||
|
||||
<tr id="workflow"><td><code>workflow</code><td>object<td>
|
||||
|
||||
The workflow that was run.
|
||||
|
||||
<tr id="workflow.ref"><td><code>workflow.ref</code><td>string<td>
|
||||
|
||||
A git reference to the commit containing the workflow, as either a git ref
|
||||
(starting with `refs/`). This is the value passed in via the event.
|
||||
|
||||
Can be computed from the [github context] using `github.ref`. Note that
|
||||
`github.ref` is not guaranteed to be available for all event types but should be
|
||||
present for all currently supported event types.
|
||||
|
||||
<tr id="workflow.repository"><td><code>workflow.repository</code><td>string<td>
|
||||
|
||||
HTTPS URI of the git repository, with `https://` protocol and without `.git`
|
||||
suffix.
|
||||
|
||||
Can be computed from the [github context] using
|
||||
`github.server_url + "/" + github.repository`.
|
||||
|
||||
<tr id="workflow.path"><td><code>workflow.path</code><td>string<td>
|
||||
|
||||
The path to the workflow YAML file within the commit.
|
||||
|
||||
Can be computed from the [github context] using `github.workflow_ref`, removing
|
||||
the prefix `github.repository + "/"` and the suffix `"@" + github.ref`. Take
|
||||
care to consider that the path and/or ref MAY contain `@` symbols.
|
||||
|
||||
</table>
|
||||
|
||||
[github context]:
|
||||
https://docs.github.com/en/actions/learn-github-actions/contexts#github-context
|
||||
[release body parameters]:
|
||||
https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#create-a-release--parameters
|
||||
[variables]: https://docs.github.com/en/actions/learn-github-actions/variables
|
||||
[vars context]:
|
||||
https://docs.github.com/en/actions/learn-github-actions/contexts#vars-context
|
||||
|
||||
### Internal parameters
|
||||
|
||||
The internal parameters MUST contain the `github` object with all of the
|
||||
parameters shown below.
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `github` | object | A subset of the [github context] as described below. Only includes parameters that are likely to have an effect on the build and that are not already captured elsewhere. |
|
||||
|
||||
The `github` object MUST contains the following elements:
|
||||
|
||||
| GitHub Context Parameter | Type | Description |
|
||||
| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------- |
|
||||
| `github.event_name` | string | The name of the event that triggered the workflow run. |
|
||||
| `github.repository_id` | string | The numeric ID corresponding to `externalParameters.workflow.repository`. |
|
||||
| `github.repository_owner_id` | string | The numeric ID of the user or organization that owns `externalParameters.workflow.repository`. |
|
||||
| `github.runner_environment` | string | The type of runner on which the the workflow was executed. One of the `github-hosted` or `self-hosted`. |
|
||||
|
||||
Numeric IDs are used here to provide stable identifiers across account and
|
||||
repository renames and to detect when an old name is reused for a new entity.
|
||||
|
||||
### Resolved dependencies
|
||||
|
||||
The `resolvedDependencies` MUST contain an entry identifying the resolved git
|
||||
commit ID corresponding to `externalParameters.workflow`. The dependency's `uri`
|
||||
MUST be in [SPDX Download Location] format:
|
||||
|
||||
```
|
||||
"git+" + github.server_url + "/" + github.repository + "@" + github.ref
|
||||
```
|
||||
|
||||
See [Examples](#examples).
|
||||
|
||||
[SPDX Download Location]:
|
||||
https://spdx.github.io/spdx-spec/v2.3/package-information/#77-package-download-location-field
|
||||
|
||||
## Run details
|
||||
|
||||
### Builder
|
||||
|
||||
The `builder.id` MUST represent the entity that generated the provenance, as per
|
||||
the [SLSA Provenance](https://slsa.dev/provenance/v1#builder.id) documentation.
|
||||
In practice, this is the workflow responsible for assembling/signing the
|
||||
provenance. When the provenance is generated within a [Reusable Workflow] that
|
||||
workflow will be used as the `builder.id`. Otherwise, it will refer to the
|
||||
top-level workflow:
|
||||
|
||||
```
|
||||
github.server_url + "/" + github.job_workflow_ref
|
||||
```
|
||||
|
||||
[Reusable Workflow]:
|
||||
https://docs.github.com/en/actions/using-workflows/reusing-workflows
|
||||
|
||||
### Metadata
|
||||
|
||||
The `invocationId` SHOULD be set to:
|
||||
|
||||
```
|
||||
github.server_url + "/" + github.repository "/actions/runs/" + github.run_id + "/attempts/" + github.run_attempt
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
See [example.json](example.json).
|
||||
|
||||
## Version history
|
||||
|
||||
### v1
|
||||
|
||||
Initial version
|
||||
49
workflow/v1/example.json
Normal file
49
workflow/v1/example.json
Normal file
@@ -0,0 +1,49 @@
|
||||
{
|
||||
"_type": "https://in-toto.io/Statement/v1",
|
||||
"predicateType": "https://slsa.dev/provenance/v1",
|
||||
"predicate": {
|
||||
"buildDefinition": {
|
||||
"buildType": "https://actions.github.io/buildtypes/workflow/v1",
|
||||
"externalParameters": {
|
||||
"workflow": {
|
||||
"ref": "refs/heads/main",
|
||||
"repository": "https://github.com/octocat/hello-world",
|
||||
"path": ".github/workflow/release.yml"
|
||||
}
|
||||
},
|
||||
"internalParameters": {
|
||||
"github": {
|
||||
"event_name": "workflow_dispatch",
|
||||
"repository_id": "1296269",
|
||||
"repository_owner_id": "583231",
|
||||
"runner_environment": "github-hosted"
|
||||
}
|
||||
},
|
||||
"resolvedDependencies": [
|
||||
{
|
||||
"uri": "git+https://github.com/octocat/hello-world@refs/heads/main",
|
||||
"digest": {
|
||||
"gitCommit": "c27d339ee6075c1f744c5d4b200f7901aad2c369"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"runDetails": {
|
||||
"builder": {
|
||||
"id": "https://github.com/octocat/builders/.github/workflows/builder_go_slsa3.yml@refs/tags/v1.0.0"
|
||||
},
|
||||
"metadata": {
|
||||
"invocationId": "https://github.com/octocat/hello-world/actions/runs/1536140711/attempts/1"
|
||||
}
|
||||
}
|
||||
},
|
||||
"subject": [
|
||||
{
|
||||
"name": "_",
|
||||
"digest": {
|
||||
"sha256": "fe4fe40ac7250263c5dbe1cf3138912f3f416140aa248637a60d65fe22c47da4"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user