Description

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.
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.

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.

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.

Build Definition

External parameters

All external parameters are REQUIRED unless empty. At most one of deployment, inputs, or release can be set.

ParameterTypeDescription
deploymentobject

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 parameters that are passed to the workflow. As of API version 2022-11-28, this is: 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.

inputsobject

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.

Can be computed from the github context using github.event.inputs.

releaseobject

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.

Only includes the parameters are passed to the workflow. As of API version 2022-11-28, this is: body, draft, name, prerelease, target_commitish.

Can be computed from the github context using the corresponding fields from github.event.release, filtering out default values (see API docs).

varsobject

The variables passed in to the workflow. This SHOULD be unset if there are no vars.

Can be computed from the vars context using vars.

workflowobject

The workflow that was run. For most workflows, this commit is the source code to be built.

workflow.refstring

A git reference to the commit containing the workflow, as either a git ref (starting with refs/) or commit ID (lowercase hex). This is the value passed in via the event. Only deployment events support commit IDs.

Can be computed from the github context using github.ref || github.sha.

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.

System parameters

All system parameters are OPTIONAL.

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 SHOULD contains the following elements:

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.
github.repository_id string The numeric ID corresponding to systemParameters.workflow.repository.
github.repository_owner_id string The numeric ID of the user or organization that owns systemParameters.workflow.repository.
github.triggering_actor_id string The numeric ID of the user that triggered the rerun, if different than actor_id.

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 SHOULD contain an entry identifying the resolved git commit ID corresponding to externalParameters.workflow. The dependency’s uri MUST be in SPDX Download Location format, i.e. "git+" + workflow.uri + "@" + workflow.ref. See Example.

The resolvedDependencies MAY contain additional 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": {
                    "build_id": 123456768,
                    "deploy_target": "deployment_sys_1a",
                    "perform_deploy": "true"
                },
                "vars": {
                    "MASCOT": "Mona"
                },
                "workflow": {
                    "ref": "refs/heads/main",
                    "repository": "https://github.com/octocat/hello-world",
                    "path": ".github/workflow/release.yml"
                }
            },
            "systemParameters": {
                "github": {
                    "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"
                }
            ]
        },
        "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