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,12 +9,39 @@ 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. |
+| [`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
+[`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. The reason for this
+restriction is to ensure that both producer and consumer are clear on semantics.
+The event types above are simple and have unambiguous semantics about what
+software is supposed to be built. Others are irrelevant for software builds
+(such as `issues`), not intended for release builds (such as `pull_request`), or
+have complex semantics that need further analysis (such as `deployment` or
+`repository_dispatch`). To add support for another event type, please open a
+[GitHub Issue][SLSA Issues].
+
+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
 
@@ -25,34 +52,33 @@ 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="inputs"><td><code>inputs</code><td>object<td>
 
-The [inputs context], with each value converted to string. Every non-empty input
-value MUST be recorded. Empty values SHOULD be omitted.
+The full [inputs context] for `workflow_dispatch` events; unset for other event
+types. This field SHOULD be omitted if empty.
 
-Note: Only `workflow_dispatch` events and reusable workflows have inputs.
+<tr id="source"><td><code>source</code><td>string<td>
 
-<tr id="source"><td><code>source</code><td>artifact<td>
-
-The git repository containing the top-level workflow YAML file.
+URI of the git commit containing the top-level workflow file, in [SPDX Download
+Location] format: `git+<repo>@<ref>`. For most workflows, this represents the
+source code to be built.
 
 This 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>
+[SPDX Download Location]: https://spdx.github.io/spdx-spec/v2.3/package-information/#77-package-download-location-field
+
+<tr id="vars"><td><code>vars</code><td>object<td>
 
-The [vars context], with each value converted to string. Every non-empty input
-value MUST be recorded. Empty values SHOULD be omitted.
+The full [vars context]. This field SHOULD be omitted if empty.
 
 <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
+This can be computed from the [github context] `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>
 
@@ -64,30 +90,29 @@ the path. See [getEntryPoint] for one possible implementation.
 
 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 +125,8 @@ github.run_id + "/attempts/" + github.run_attempt`.
 
 ## Example
 
+[Example]: #example
+
 ```json
 {% include_relative example.json %}
 ```