From 606f10916d446f92bf934719bffa405a0110ec4d Mon Sep 17 00:00:00 2001 From: Brian DeHamer Date: Tue, 11 Jun 2024 07:57:19 -0700 Subject: [PATCH] Document buildType (#1) * add schema Signed-off-by: Brian DeHamer * reformat Signed-off-by: Brian DeHamer * set-up GH pages redirects Signed-off-by: Brian DeHamer * fix required elements Signed-off-by: Brian DeHamer --------- Signed-off-by: Brian DeHamer --- README.md | 4 +- docs/.nojekyll | 0 docs/index.html | 7 ++ docs/workflow/index.html | 1 + docs/workflow/v1.html | 7 ++ workflow/v1/README.md | 168 +++++++++++++++++++++++++++++++++++++++ workflow/v1/example.json | 49 ++++++++++++ 7 files changed, 234 insertions(+), 2 deletions(-) create mode 100644 docs/.nojekyll create mode 100644 docs/index.html create mode 120000 docs/workflow/index.html create mode 100644 docs/workflow/v1.html create mode 100644 workflow/v1/README.md create mode 100644 workflow/v1/example.json diff --git a/README.md b/README.md index f1babc3..76cd148 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..c2c17ab --- /dev/null +++ b/docs/index.html @@ -0,0 +1,7 @@ + + +Redirecting… + + + + diff --git a/docs/workflow/index.html b/docs/workflow/index.html new file mode 120000 index 0000000..f9bfc12 --- /dev/null +++ b/docs/workflow/index.html @@ -0,0 +1 @@ +v1.html \ No newline at end of file diff --git a/docs/workflow/v1.html b/docs/workflow/v1.html new file mode 100644 index 0000000..112181e --- /dev/null +++ b/docs/workflow/v1.html @@ -0,0 +1,7 @@ + + +Redirecting… + + + + diff --git a/workflow/v1/README.md b/workflow/v1/README.md new file mode 100644 index 0000000..9e9e8fa --- /dev/null +++ b/workflow/v1/README.md @@ -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. + + +
ParameterTypeDescription + +
workflowobject + +The workflow that was run. + +
workflow.refstring + +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. + +
workflow.repositorystring + +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`. + +
workflow.pathstring + +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. + +
+ +[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 diff --git a/workflow/v1/example.json b/workflow/v1/example.json new file mode 100644 index 0000000..0b09e16 --- /dev/null +++ b/workflow/v1/example.json @@ -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" + } + } + ] +} +