Provenance v1: allow arbitrary JSON for params, refine github-actions-workflow

docs/_sass/minima/_layout.scss

@@ -623,3 +623,8 @@
         }
     }
 }
+
+.footnotes {
+    border-top: 1px solid $grey-border;
+    padding-top: $spacer-m;
+}

docs/github-actions-workflow/v0.1/example.json

@@ -5,36 +5,27 @@
             "buildType": "https://slsa.dev/github-actions-workflow/v0.1?draft",
             "externalParameters": {
                 "inputs": {
-                    "mapValue": {
-                        "build_id": "123456768",
-                        "deploy_target": "deployment_sys_1a",
-                        "perform_deploy": "true"
-                    }
+                    "build_id": 123456768,
+                    "deploy_target": "deployment_sys_1a",
+                    "perform_deploy": "true"
                 },
-                "source": {
-                    "artifactRef": {
-                        "uri": "git+https://github.com/octocat/hello-world@refs/heads/main",
-                        "digest": { "sha1": "c27d339ee6075c1f744c5d4b200f7901aad2c369" }
-                    }
+                "source": "git+https://github.com/octocat/hello-world@refs/heads/main",
+                "vars": {
+                    "MASCOT": "Mona"
                 },
-                "inputs": {
-                    "mapValue": {
-                        "mascot": "Mona"
-                    }
-                },
-                "workflowPath": {
-                    "scalarValue": ".github/workflow/release.yml"
-                }
+                "workflowPath": ".github/workflow/release.yml"
             },
             "systemParameters": {
                 "github": {
-                    "mapValue": {
-                        "actor": "MarkLodato",
-                        "event_name": "workflow_dispatch"
-                    }
+                    "actor_id": "1234567",
+                    "event_name": "workflow_dispatch"
                 }
             },
             "resolvedDependencies": [
+                {
+                    "uri": "git+https://github.com/octocat/hello-world@refs/heads/main",
+                    "digest": { "sha1": "c27d339ee6075c1f744c5d4b200f7901aad2c369" }
+                },
                 {
                     "uri": "https://github.com/actions/virtual-environments/releases/tag/ubuntu20/20220515.1"
                 }

docs/github-actions-workflow/v0.1/index.md

@@ -9,85 +9,153 @@ hero_text: |
 ## Description
 
 This `buildType` describes the execution of a top-level [GitHub Actions]
-workflow (as a whole).
-
-Note: This type is not meant to describe execution of subsets of the top-level
-workflow, such as an action, a job, or a reusable workflow.
-
+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. |
+| [`deployment`]        | Creation of a deployment. |
+| [`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
+[`deployment`]: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#deployment
+[`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. This ensures that the [external parameters] are
+fully captured and that the semantics are unambiguous. 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][SLSA Issues].
+
+Note: Consumers are REQUIRED to 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.
+
+Note: This build type is **not** meant to describe execution of a subset of a
+top-level workflow, such as an action, job, or reusable workflow. Only workflows
+have sufficient [isolation] between invocations, whereas actions and jobs do
+not. Reusable workflows do have sufficient isolation, but supporting both
+top-level and reusable would make the schema too error-prone.
+
+[SLSA Issues]: https://github.com/slsa-framework/slsa/issues
 [GitHub Actions]: https://docs.github.com/en/actions
+[event types]: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows
+[isolation]: /spec/v1.0/requirements#isolation-strength
 
 ## 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="inputs"><td><code>inputs</code><td>mapValue<td>
+<tr id="deployment"><td><code>deployment</code><td>object<td>
+
+The non-default [deployment body parameters] for `deployment` events; unset for
+other event types. SHOULD omit parameters that have a default value to make
+verification easier. SHOULD be unset if there are no non-default values.
+
+Only includes the following parameters (as of API version 2022-11-28) because
+these are the only ones that have an effect on the build: `description`,
+`environment`, `payload`, `production_environment`, `transient_environment`.
+
+Can be computed from the [github context] using the corresponding fields from
+`github.event.deployment`, filtering out default values (see API docs) and using
+`original_environment` for `environment`.
+
+<tr id="inputs"><td><code>inputs</code><td>object<td>
+
+The `inputs` from `workflow_dispatch` events; unset for other event types.
+SHOULD omit empty inputs to make verification easier. SHOULD be unset if there
+are no non-empty inputs.
 
-The [inputs context], with each value converted to string. Every non-empty input
-value MUST be recorded. Empty values SHOULD be omitted.
+Can be computed from the [github context] using `github.event.inputs`.
 
-Note: Only `workflow_dispatch` events and reusable workflows have inputs.
+<tr id="release"><td><code>release</code><td>object<td>
 
-<tr id="source"><td><code>source</code><td>artifact<td>
+The non-default [release body parameters] for `release` events; unset for
+other event types. SHOULD omit parameters that have a default value to make
+verification easier. SHOULD be unset if there are no non-default values.
 
-The git repository containing the top-level workflow YAML file.
+Only includes the following parameters (as of API version 2022-11-28) because
+these are the only ones that have an effect on the build: `body`, `draft`,
+`name`, `prerelease`, `target_commitish`.
 
-This can be computed from the [github context] using
+Can be computed from the [github context] using the corresponding fields from
+`github.event.release`, filtering out default values (see API docs).
+
+<tr id="source"><td><code>source</code><td>string<td>
+
+URI of the git commit containing the top-level workflow file, in [SPDX Download
+Location] format (`git+<repo>@<ref>`), without ".git" on the repo name. For most
+workflows, this represents the source code to be built.
+
+Can be computed from the [github context] using
 `"git+" + github.server_url + "/" + github.repository + "@" + github.ref`.
 
-<tr id="vars"><td><code>vars</code><td>vars<td>
+<tr id="vars"><td><code>vars</code><td>object<td>
+
+The [variables] passed in to the workflow. This SHOULD be unset if there are no
+vars.
 
-The [vars context], with each value converted to string. Every non-empty input
-value MUST be recorded. Empty values SHOULD be omitted.
+Can be computed from the [vars context] using `vars`.
 
 <tr id="workflowPath"><td><code>workflowPath</code><td>string<td>
 
 The path to the workflow YAML file within `source`.
 
-Note: this cannot be computed directly from the [github context]: the
-`github.workflow` context field only provides the *name* of the workflow, not
-the path. See [getEntryPoint] for one possible implementation.
-
-[getEntryPoint]: https://github.com/slsa-framework/slsa-github-generator/blob/ae7e58c315b65aa92b9440d5ce25d795845b3b2a/slsa/buildtype.go#L94-L135
+`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>
 
+[SPDX Download Location]: https://spdx.github.io/spdx-spec/v2.3/package-information/#77-package-download-location-field
+[deployment body parameters]: https://docs.github.com/en/rest/deployments/deployments?apiVersion=2022-11-28#create-a-deployment--parameters
 [github context]: https://docs.github.com/en/actions/learn-github-actions/contexts#github-context
-[inputs context]: https://docs.github.com/en/actions/learn-github-actions/contexts#inputs-context
+[relese 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
 
 ### System parameters
 
 All system parameters are OPTIONAL.
 
-| Parameter            | Type     | Description |
-| -------------------- | -------- | ----------- |
-| `github`       | mapValue   | 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. |
+| 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` map SHOULD contains the following elements:
+The `github` object SHOULD contains the following elements:
 
-| GitHub Context Parameter        | Description |
-| ------------------------------- | ----------- |
-| `github.mapValue["actor"]`      | The username of the user that triggered the initial workflow run. |
-| `github.mapValue["event_name"]` | The name of the event that triggered the workflow run. |
+| GitHub Context Parameter | Type   | Description |
+| ------------------------ | ------ | ----------- |
+| `github.actor_id`        | string | The numeric ID of the user that triggered the initial workflow run. |
+| `github.event_name`      | string | The name of the event that triggered the workflow run. |
 
-> TODO: What about `actor_id`, `repository_id`, and `repository_owner_id`? Those
+> TODO: What about `repository_id`, and `repository_owner_id`? Those
 > are not part of the context so they're harder to describe, and the repository
 > ones should arguably go on the `source` paramater rather than be here.
 >
 > Also `base_ref` and `head_ref` are similar in that they are annotations about
 > `source` rather than a proper parameter.
 
-> TODO: None of these are really "parameters", per se, but rather metadata
-> about the build. Perhaps they should go in `runDetails` instead? The problem
-> is that we don't have an appropriate field for it currently.
-
 ### Resolved dependencies
 
+The `resolvedDependencies` SHOULD contain an entry providing the git commit ID
+of `source`, with the `uri` matching `externalParameters.source`. See [Example].
+
 The resolved dependencies MAY contain any artifacts known to be input to the
 workflow, such as the specific versions of the virtual environments used.
 
@@ -100,6 +168,8 @@ github.run_id + "/attempts/" + github.run_attempt`.
 
 ## Example
 
+[Example]: #example
+
 ```json
 {% include_relative example.json %}
 ```