Add isBuildArtifact field to Artifacts

This PR adds isBuildArtifact field to Artifacts. This field will allow Tekton Chains to understand user's desire and appropriate add the artifact as a subject or a byProduct in the SLSA provenance.
tektoncd · Jul 20, 2024 · faa32cb · faa32cb
1 parent c0b29b4
commit faa32cb
Show file tree

Hide file tree

Showing 13 changed files with 249 additions and 28 deletions.
diff --git a/docker b/docker
@@ -0,0 +1,98 @@
+    bash:5.2.26
+      alpine:3.20.1
+      alpine:3.20.1
+              ubuntu
+              alpine:3.20.1
+              ubuntu
+              ubuntu
+              ubuntu
+              ubuntu
+              ubuntu
+              ubuntu
+              ubuntu
+              ubuntu
+              ubuntu
+              ubuntu
+  bash:5.2.26
+    bash:5.2.26
+    bash:5.2.26
+              alpine:3.20.1
+              alpine
+              alpine:3.20.1
+              alpine
+        - alpine:3.20.1
+        - alpine:3.20.1
+              bash:5.2.26
+              bash:5.2.26
+              bash:5.2.26
+              bash:5.2.26
+              bash:5.2.26
+              bash:5.2.26
+              bash:5.2.26
+              bash:5.2.26
+      alpine:3.20.1
+              bash:5.2.26
+              bash:5.2.26
+              bash:5.2.26
+      alpine:3.20.1
+      alpine:3.20.1
+      alpine:3.20.1
+      bash:5.2.26
+      alpine:3.20.1
+      ubuntu
+      alpine:3.20.1
+      alpine:3.20.1
+      alpine:3.20.1
+      alpine:3.20.1
+              ubuntu
+              ubuntu
+            - alpine:3.20.1
+              ubuntu
+              bash
+    ubuntu
+      value: docker.io/cnbs/sample-builder:bionic@sha256:6c03dd604503b59820fd15adbc65c0a077a47e31d404a3dcad190f3179e920b5
+      value: docker.io/cnbs/sample-builder:bionic@sha256:6c03dd604503b59820fd15adbc65c0a077a47e31d404a3dcad190f3179e920b5
+      ubuntu
+      alpine:3.20.1
+    bash:5.2.26
+        bash:5.2.26
+        bash:5.2.26
+        python:3.12.4
+          - docker.io/library/bash
+        bash
+        bash
+        bash
+        bash
+        bash
+        bash
+        bash
+          - docker.io/library/bash
+          - docker.io/library/bash
+      - bash:5.2.26
+      - bash:5.2.26
+      - bash:5.2.26
+      - bash:5.2.26
+      image: docker.io/alpine/git:v2.26.2
+      image: docker.io/alpine/git:v2.26.2
+      image: docker.io/alpine/git:v2.26.2
+      bash:5.2.26
+      ubuntu
+        bash:5.2.26
+        bash:5.2.26
+        bash:5.2.26
+        ubuntu
+        bash
+  ubuntu
+  bash:5.2.26
+        alpine:3.20.1
+  alpine:3.20.1
+  alpine:3.20.1
+  alpine:3.20.1
+    - alpine:3.20.1
+    - alpine:3.20.1
+      alpine:3.20.1
+      alpine:3.20.1
+      alpine:3.20.1
+    ubuntu
+    ubuntu
+      ubuntu
diff --git a/docs/artifacts.md b/docs/artifacts.md
@@ -155,6 +155,50 @@ spec:
 
 It is recommended to use [purl format](https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst) for artifacts uri as shown in the example. 
 
+### Output Artifacts in SLSA Provenance
+By default, Tekton Chains will consider all output artifacts as `byProducts` when generating in the [SLSA provenance](https://slsa.dev/spec/v1.0/provenance). In order to treat an artifact as a [subject](https://slsa.dev/spec/v1.0/provenance#schema) of the build, you must set a boolean field `"buildOutput": true` for the output artifact.
+
+e.g.  
+```yaml
+apiVersion: tekton.dev/v1
+kind: TaskRun
+metadata:
+  generateName: step-artifacts-
+spec:
+  taskSpec:
+    description: |
+      A simple task that populates artifacts to TaskRun stepState
+    steps:
+      - name: artifacts-producer
+        image: bash:latest
+        script: |
+          cat > $(artifacts.path) << EOF
+          {
+            "outputs":[
+              {
+                "name":"image",
+                "buildOutput": true,
+                "values":[
+                  {
+                    "uri":"pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
+                    "digest":{
+                      "sha256":"df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48",
+                      "sha1":"95588b8f34c31eb7d62c92aaa4e6506639b06ef2"
+                    }
+                  }
+                ]
+              }
+            ]
+          }
+          EOF
+```
+This informs Tekton Chains your desire to handle the artifact.
+
+When authoring a `StepAction` or a `Task`, you can even parametrize this field and let the user of the `StepAction`/`Task` indicate their desire.This is because there are generally two categories:
+1. "build" artifacts - packages, images etc.
+2. "non-build"/incidental artifacts - logs, caches, etc.
+Depending on what the user of the `Task/StepAction` is uploading, they can indicate their choice.
+
 ### Passing Artifacts between Steps
 You can pass artifacts from one step to the next using:
 - Specific Artifact: `$(steps.<step-name>.inputs.<artifact-category-name>)` or `$(steps.<step-name>.outputs.<artifact-category-name>)`

diff --git a/docs/pipeline-api.md b/docs/pipeline-api.md
@@ -1370,6 +1370,7 @@ string
 </em>
 </td>
 <td>
+<p>The artifact&rsquo;s identifying category name</p>
 </td>
 </tr>
 <tr>
@@ -1382,7 +1383,18 @@ string
 </em>
 </td>
 <td>
-<p>The artifact&rsquo;s identifying category name</p>
+<p>A collection of values related to the artifact</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>buildOutput</code><br/>
+<em>
+bool
+</em>
+</td>
+<td>
+<p>Indicate if the artifact is a build output or a by-product</p>
 </td>
 </tr>
 </tbody>
@@ -10047,6 +10059,7 @@ string
 </em>
 </td>
 <td>
+<p>The artifact&rsquo;s identifying category name</p>
 </td>
 </tr>
 <tr>
@@ -10059,7 +10072,18 @@ string
 </em>
 </td>
 <td>
-<p>The artifact&rsquo;s identifying category name</p>
+<p>A collection of values related to the artifact</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>buildOutput</code><br/>
+<em>
+bool
+</em>
+</td>
+<td>
+<p>Indicate if the artifact is a build output or a by-product</p>
 </td>
 </tr>
 </tbody>

diff --git a/examples/v1/taskruns/alpha/produce-consume-artifacts.yaml b/examples/v1/taskruns/alpha/produce-consume-artifacts.yaml
@@ -6,6 +6,9 @@ spec:
   taskSpec:
     description: |
       A simple task that populates artifacts to TaskRun stepState
+    params:
+      - name: isBuildArtifact
+        default: true
     steps:
       - name: artifacts-producer
         image: docker.io/library/bash:5.2.26
@@ -28,6 +31,7 @@ spec:
             "outputs":[
               {
                 "name":"image",
+                "isBuildArtifact": $(params.isBuildArtifact),
                 "values":[
                   {
                     "uri":"pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c",

diff --git a/go.mod b/go.mod
@@ -1,6 +1,7 @@
 module github.com/tektoncd/pipeline
 
 go 1.22
+
 toolchain go1.22.5
 
 require (

diff --git a/pkg/apis/pipeline/v1/artifact_types.go b/pkg/apis/pipeline/v1/artifact_types.go
@@ -26,8 +26,12 @@ type Algorithm string
 // Artifact represents an artifact within a system, potentially containing multiple values
 // associated with it.
 type Artifact struct {
-	Name   string          `json:"name,omitempty"`   // The artifact's identifying category name
-	Values []ArtifactValue `json:"values,omitempty"` // A collection of values related to the artifact
+	// The artifact's identifying category name
+	Name string `json:"name,omitempty"`
+	// A collection of values related to the artifact
+	Values []ArtifactValue `json:"values,omitempty"`
+	// Indicate if the artifact is a build output or a by-product
+	BuildOutput bool `json:"buildOutput,omitempty"`
 }
 
 // ArtifactValue represents a specific value or data element within an Artifact.
@@ -82,35 +86,45 @@ func (a *Artifacts) Merge(another Artifacts) {
 		})
 	}
 
-	outputMap := make(map[string][]ArtifactValue)
+	outputMap := make(map[string]Artifact)
 	var newOutputs []Artifact
 	for _, v := range a.Outputs {
-		outputMap[v.Name] = v.Values
+		outputMap[v.Name] = v
 	}
 
 	for _, v := range another.Outputs {
 		_, ok := outputMap[v.Name]
 		if !ok {
-			outputMap[v.Name] = []ArtifactValue{}
+			outputMap[v.Name] = Artifact{Name: v.Name, Values: []ArtifactValue{}, BuildOutput: v.BuildOutput}
+		}
+		// only update buildOutput to true.
+		// Do not convert to false if it was true before.
+		if v.BuildOutput {
+			art := outputMap[v.Name]
+			art.BuildOutput = v.BuildOutput
+			outputMap[v.Name] = art
 		}
 		for _, vv := range v.Values {
 			exists := false
-			for _, av := range outputMap[v.Name] {
+			for _, av := range outputMap[v.Name].Values {
 				if cmp.Equal(vv, av) {
 					exists = true
 					break
 				}
 			}
 			if !exists {
-				outputMap[v.Name] = append(outputMap[v.Name], vv)
+				art := outputMap[v.Name]
+				art.Values = append(art.Values, vv)
+				outputMap[v.Name] = art
 			}
 		}
 	}
 
-	for k, v := range outputMap {
+	for _, v := range outputMap {
 		newOutputs = append(newOutputs, Artifact{
-			Name:   k,
-			Values: v,
+			Name:        v.Name,
+			Values:      v.Values,
+			BuildOutput: v.BuildOutput,
 		})
 	}
 	a.Inputs = newInputs

diff --git a/pkg/apis/pipeline/v1/artifact_types_test.go b/pkg/apis/pipeline/v1/artifact_types_test.go
@@ -95,7 +95,8 @@ func TestArtifactsMerge(t *testing.T) {
 				},
 				Outputs: []Artifact{
 					{
-						Name: "output1",
+						Name:        "output1",
+						BuildOutput: true,
 						Values: []ArtifactValue{
 							{
 								Digest: map[Algorithm]string{"sha256": "698c4539633943f7889f41605003d7fa63833722ebd2b37c7e75df1d3d06941a"},
@@ -104,7 +105,8 @@ func TestArtifactsMerge(t *testing.T) {
 						},
 					},
 					{
-						Name: "output2",
+						Name:        "output2",
+						BuildOutput: true,
 						Values: []ArtifactValue{
 							{
 								Digest: map[Algorithm]string{"sha256": "7e406d83706c7193df3e38b66d350e55df6f13d2a28a1d35917a043533a70f5c"},
@@ -150,7 +152,8 @@ func TestArtifactsMerge(t *testing.T) {
 				},
 				Outputs: []Artifact{
 					{
-						Name: "output1",
+						Name:        "output1",
+						BuildOutput: true,
 						Values: []ArtifactValue{
 							{
 								Digest: map[Algorithm]string{"sha256": "47de7a85905970a45132f48a9247879a15c483477e23a637504694e611135b40e"},
@@ -163,7 +166,8 @@ func TestArtifactsMerge(t *testing.T) {
 						},
 					},
 					{
-						Name: "output2",
+						Name:        "output2",
+						BuildOutput: true,
 						Values: []ArtifactValue{
 							{
 								Digest: map[Algorithm]string{"sha256": "7e406d83706c7193df3e38b66d350e55df6f13d2a28a1d35917a043533a70f5c"},

diff --git a/pkg/apis/pipeline/v1/openapi_generated.go b/pkg/apis/pipeline/v1/openapi_generated.go
diff --git a/pkg/apis/pipeline/v1/swagger.json b/pkg/apis/pipeline/v1/swagger.json
@@ -155,11 +155,16 @@
       "description": "TaskRunStepArtifact represents an artifact produced or used by a step within a task run. It directly uses the Artifact type for its structure.",
       "type": "object",
       "properties": {
+        "buildOutput": {
+          "description": "Indicate if the artifact is a build output or a by-product",
+          "type": "boolean"
+        },
         "name": {
+          "description": "The artifact's identifying category name",
           "type": "string"
         },
         "values": {
-          "description": "The artifact's identifying category name",
+          "description": "A collection of values related to the artifact",
           "type": "array",
           "items": {
             "default": {},