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.

Build Definition

External parameters

All external parameters are REQUIRED unless empty.

ParameterTypeDescription
inputsmapValue

The inputs context, with each value converted to string. Every non-empty input value MUST be recorded. Empty values SHOULD be omitted.

Note: Only workflow_dispatch events and reusable workflows have inputs.

sourceartifact

The git repository containing the top-level workflow YAML file.

This can be computed from the github context using "git+" + github.server_url + "/" + github.repository + "@" + github.ref.

varsvars

The vars context, with each value converted to string. Every non-empty input value MUST be recorded. Empty values SHOULD be omitted.

workflowPathstring

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.

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.

The github map 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.

TODO: What about actor_id, 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 resolved dependencies MAY contain any artifacts known to be input to the workflow, such as the specific versions of the virtual environments used.

Run details

Metadata

The invocationId SHOULD be set to github.server_url + "/actions/runs/" + github.run_id + "/attempts/" + github.run_attempt.

Example

{
    "predicateType": "https://slsa.dev/provenance/v1?draft",
    "predicate": {
        "buildDefinition": {
            "buildType": "https://slsa.dev/github-actions-workflow/v0.1?draft",
            "externalParameters": {
                "inputs": {
                    "mapValue": {
                        "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" }
                    }
                },
                "inputs": {
                    "mapValue": {
                        "mascot": "Mona"
                    }
                },
                "workflowPath": {
                    "scalarValue": ".github/workflow/release.yml"
                }
            },
            "systemParameters": {
                "github": {
                    "mapValue": {
                        "actor": "MarkLodato",
                        "event_name": "workflow_dispatch"
                    }
                }
            },
            "resolvedDependencies": [
                {
                    "uri": "https://github.com/actions/virtual-environments/releases/tag/ubuntu20/20220515.1"
                }
            ]
        },
        "runDetails": {
            "builder": {
                "id": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/builder_go_slsa3.yml@refs/tags/v0.0.1"
            },
            "metadata": {
                "invocationId": "https://github.com/octocat/hello-world/actions/runs/1536140711/attempts/1",
                "startedOn": "2023-01-01T12:34:56Z"
            }
        }
    },
    "subject": [
        {
            "name": "_",
            "digest": { "sha256": "fe4fe40ac7250263c5dbe1cf3138912f3f416140aa248637a60d65fe22c47da4" }
        }
    ]
}

Note: The builder.id in the example assumes that the build runs under slsa-github-generator. If GitHub itself generated the provenance, the id would be different.

Version history

v0.1

Initial version