Skip to main content

Build Type: GitHub Actions

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

This build type was inspired by the GitHub Actions build type described here.

Description

"buildType": "https://docs.cimon.build/provenance/buildtypes/github/v1"

The GitHub Actions build type describes the execution of a GitHub Actions workflow that builds a software artifact.

Only the following trigger types are supported:

Supported event typeEvent description
workflow_dispatchA user manually queued the workflow.
pushCI triggered by a Git push event.
pull_requestCI triggered when a pull request is opened or updated.
tagCI triggered when a new tag is pushed to the repository.
scheduleStarts your pipeline based on a schedule, such as a nightly build.
createCI triggered when a branch or tag is created.
workflow_runCI triggered when a workflow run is requested or completed.

A list of all event types can be found on the GitHub Actions documentation here.

Build Definition

External parameters

All external parameters are REQUIRED unless empty.

ParameterTypeDescription
workflowobjectThe workflow that was run
workflow.namestringThe name of the GitHub Actions workflow
workflow.repositorystringURI of the git repository
workflow.refstringA git reference to the commit
workflow.filePathstringPath to the workflow YAML file
jobobjectThe job definition for the build
job.jobNamestringThe name of the job
job.jobIdstring-
buildobjectThe specific build that generated the provenance
build.buildRunstringThe build run ID
build.buildRunAttemptstringNumber attempt for the specified build run ID
build.buildUrlstringThe full web URL for the build

Example:

"externalParameters": {
"workflow": {
"name": "GitHub Test Workflow",
"repository": "https://github.com/cycodelabs/cimon",
"ref": "refs/heads/main",
"filePath": ".github/workflows/push.yml"
},
"job": {
"jobName": "PushEvent",
"jobId": "00000000000"
},
"build": {
"buildRun": "5706737730",
"buildRunAttempt": "1",
"buildUrl": "https://github.com/cycodelabs/cimon/actions/runs/5706737730/attempts/1"
}
}

Internal parameters

All internal parameters are OPTIONAL. This build type doesn't use internal parameters.

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.

Example:

"resolvedDependencies": [
{
"uri": "git+https://github.com/cycodelabs/cimon@refs/heads/main",
"digest": {
"gitCommit": "bc93e6f8e6721d802678219af080a8559bc058b0"
}
}
]

Run Details

Builder

The builder.id MUST represent the entity that generated the provenance, as per the SLSA Provenance documentation. In the case of GitHub Actions, it should be the URL of the repository and the reference to the workflow.

Example:

"builder": {
"id": "https://github.com/cycodelabs/cimon/.github/workflows/push.yml@refs/heads/main"
}

Metadata

The invocationId SHOULD be set to the GitHub Actions URL for the specific run and run attempt.

Example:

"metadata": {
"invocationID": "https://github.com/cycodelabs/cimon/actions/runs/5706737730/attempts/1",
}