v1

Build Type: GitHub Actions Workflow

This is a community-maintained SLSA Provenance buildType that describes the execution of a GitHub Actions workflow.

This definition is hosted and maintained by the SLSA community, not GitHub. Our hope is for GitHub Actions to eventually host and maintain this definition, served under a URL it controls, once it officially supports SLSA. In the meantime, this unofficial definition can be used by tooling such as slsa-github-generator to describe a GitHub Actions Workflow.

Description

"buildType": "https://slsa-framework.github.io/github-actions-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.

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

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 inputs or release can be set.

Parameter	Type	Description
inputs	object	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.
release	object	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).
vars	object	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.
workflow	object	The workflow that was run. For most workflows, this commit is the source code to be built.
workflow.ref	string	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.repository	string	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.path	string	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.

Internal parameters

All internal 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 externalParameters.workflow.repository.
github.repository_owner_id	string	The numeric ID of the user or organization that owns externalParameters.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 Examples.

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

Builder

The builder.id MUST represent the entity that generated the provenance, as per the SLSA Provenance documentation. In practice, this is likely one of the following:

• When the provenance is generated by a workflow (often using Sigstore in the envelope layer), the builder.id SHOULD be set to github.server_url + job_workflow_ref. Example: https://github.com/slsa-framework/slsa-github-generator/.github/workflows/builder_go_slsa3.yml@refs/tags/v0.0.1
• When the provenance is generated by GitHub, the builder.id SHOULD be set to a URI representing GitHub.

Metadata

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

Examples

See example.json.

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

v1.1

• The deployment event type was removed as a supported event type.

v1

Initial version