Build Type: Azure Pipelines

This is a SLSA Provenance buildType that describes the execution of an Azure Pipeline workflow.

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

Description

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

This buildType describes the execution of an Azure Pipelines workflow that builds a software artifact.

Only the following trigger types are supported:

Supported event type	Event description
Manual	A user manually queued the build.
IndividualCI	CI triggered by a Git push or a TFVC check-in.
BatchedCI	CI triggered by a Git push or a TFVC check-in, and the Batch changes was selected.
Schedule	Starts your pipeline based on a schedule, such as a nightly build.
ResourceTrigger	The build was triggered by a resource trigger or it was triggered by another build.

A list of all event type values can be found on the variables page under the Build.Reason variable.

Build Definition

External parameters

All external parameters are REQUIRED unless empty.

Parameter	Type	Description
workflow	object	The workflow that was run
workflow.name	string	The pipeline name for the workflow
workflow.repository	string	URI of the git repository
workflow.ref	string	A git reference to the commit
workflow.filePath	string	Path to the workflow YAML file
job	object	The job definition for the build
job.jobName	string	The name of the job
job.jobId	string	UUID defining job ID
build	object	The specific build that generated the provenance
build.buildRun	string	The build ID
build.buildRunAttempt	string	Number attempt for the specified build ID
build.buildUrl	string	The full web URL for the build

Example:

"externalParameters": {
    "workflow": {
        "name": "Azure Test Pipeline",
        "repository": "https://github.com/CycodeLabs/cimon-test-repository",
        "ref": "refs/pull/582/merge",
        "filePath": "azure-pipelines.yml"
    },
    "job": {
        "jobName": "Build Job",
        "jobId": "5b694ae9-86cc-5057-d72a-30cde2f12d73"
    },
    "build": {
        "buildRun": "836",
        "buildRunAttempt": "1",
        "buildUrl": "https://dev.azure.com/cycodelabs/cimon/_build/results?buildId=836&view=results"
    }
}

Internal parameters

All internal parameters are OPTIONAL.

The internal parameters contain the CI environment variables as they appear in the build. This is how the internal parameters look for this type of build type:

"internalParameters": {
    "AGENT_NAME": "Hosted Agent",
    "AGENT_OS": "Linux",
    "AGENT_OSARCHITECTURE": "X64",
    "BUILD_BUILDID": "123",
    "BUILD_DEFINITIONNAME": "Attest Tests CI",
    "BUILD_REASON": "Manual",
    "BUILD_REPOSITORY_ID": "CycodeLabs/cimon",
    "BUILD_REPOSITORY_NAME": "CycodeLabs/cimon",
    "BUILD_REPOSITORY_PROVIDER": "GitHub",
    "BUILD_REPOSITORY_URI": "https://github.com/CycodeLabs/cimon",
    "BUILD_SOURCEBRANCH": "refs/heads/chore/branch-name",
    "BUILD_SOURCEBRANCHNAME": "branch-name",
    "BUILD_SOURCEVERSION": "167f5f63d349edc1db6273da8b9db08b75f4026e",
    "BUILD_SOURCEVERSIONAUTHOR": "actor-id",
    "SYSTEM_COLLECTIONID": "11111111-0000-1111-0000-111111111111",
    "SYSTEM_COLLECTIONURI": "https://dev.azure.com/cycodelabs/",
    "SYSTEM_DEFINITIONID": "15",
    "SYSTEM_JOBATTEMPT": "1",
    "SYSTEM_JOBDISPLAYNAME": "This is Job Display Name",
    "SYSTEM_JOBID": "11111111-0000-1111-0000-111111111111",
    "SYSTEM_PIPELINESTARTTIME": "2024-01-01 00:00:00+00:00",
    "SYSTEM_TEAMPROJECT": "cimon",
    "SYSTEM_TEAMPROJECTID": "11111111-0000-1111-0000-111111111111"
}

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-test-repository@refs/pull/582/merge",
        "digest": {
            "gitCommit": "bc93e6f8e6721d802678219af080a8559bc058b0"
        },
        "annotations": {
            "signedStatus": "signed",
            "gpgKeyId": "B5690EEEBB952194"
        }
    }
]

Each referenced commit contains signing information as well. The signedStatus field will receive one of three values:

• signed: Confirmed that the commit is signed. In that case, gpgKeyId will also be included. The GPG Key ID should look similar to the command output: git log --show-signature -s.
• unsigned: Confirmed that the commit is not signed.
• unknown: The commit signing information could not be verified.

Run details

Builder

The builder.id MUST represent the entity that generated the provenance, as per the SLSA Provenance documentation. In practice, this is the workflow reference such as <server_url> + <job_workflow_ref>.

Example:

"builder": {
    "id": "https://github.com/CycodeLabs/cimon-test-repository@refs/pull/582/merge"
},

Metadata

The invocationId SHOULD be set to <server_url> + "/azure/runs/" + <azure.run_id> + "/attempts/" + <azure.run_attempt>. The startedOn MAY contain the time when the build started.

Example:

"metadata": {
    "invocationID": "https://dev.azure.com/cycodelabs/cimon/azure/runs/836/attempts/1",
    "startedOn": "2023-07-10T14:07:36Z"
}