TEP-0103: Skipping Reason - Add SkippingReason to SkippedTasks field of PipelineRunStatus

docs/pipelineruns.md

@@ -665,6 +665,8 @@ False|PipelineRunTimeout|Yes|The `PipelineRun` timed out.
 
 When a `PipelineRun` changes status, [events](events.md#pipelineruns) are triggered accordingly.
 
+When a `PipelineRun` has `Tasks` that were `skipped`, the `reason` for skipping the task will be listed in the `Skipped Tasks` section of the `status` of the `PipelineRun`.
+
 When a `PipelineRun` has `Tasks` with [`when` expressions](pipelines.md#guard-task-execution-using-when-expressions):
 - If the `when` expressions evaluate to `true`, the `Task` is executed then the `TaskRun` and its resolved `when` expressions will be listed in the `Task Runs` section of the `status` of the `PipelineRun`.
 - If the `when` expressions evaluate to `false`, the `Task` is skipped then its name and its resolved `when` expressions will be listed in the `Skipped Tasks` section of the `status` of the `PipelineRun`.
@@ -678,6 +680,7 @@ Conditions:
   Type:                  Succeeded
 Skipped Tasks:
   Name:       skip-this-task
+  Reason:     When Expressions evaluated to false
   When Expressions:
     Input:     foo
     Operator:  in

pkg/apis/pipeline/v1beta1/pipelinerun_types.go

@@ -484,12 +484,36 @@ type PipelineRunStatusFields struct {
 type SkippedTask struct {
 	// Name is the Pipeline Task name
 	Name string `json:"name"`
+	// Reason is the cause of the PipelineTask being skipped.
+	Reason SkippingReason `json:"reason"`
 	// WhenExpressions is the list of checks guarding the execution of the PipelineTask
 	// +optional
 	// +listType=atomic
 	WhenExpressions []WhenExpression `json:"whenExpressions,omitempty"`
 }
 
+// SkippingReason explains why a PipelineTask was skipped.
+type SkippingReason string
+
+const (
+	// WhenExpressionsSkip means the task was skipped due to at least one of its when expressions evaluating to false
+	WhenExpressionsSkip SkippingReason = "When Expressions evaluated to false"
+	// ConditionsSkip means the task was skipped due to at least one of its conditions failing
+	ConditionsSkip SkippingReason = "Conditions failed"
+	// ParentTasksSkip means the task was skipped because its parent was skipped
+	ParentTasksSkip SkippingReason = "Parent Tasks were skipped"
+	// StoppingSkip means the task was skipped because the pipeline run is stopping
+	StoppingSkip SkippingReason = "PipelineRun was stopping"
+	// GracefullyCancelledSkip means the task was skipped because the pipeline run has been gracefully cancelled
+	GracefullyCancelledSkip SkippingReason = "PipelineRun was gracefully cancelled"
+	// GracefullyStoppedSkip means the task was skipped because the pipeline run has been gracefully stopped
+	GracefullyStoppedSkip SkippingReason = "PipelineRun was gracefully stopped"
+	// MissingResultsSkip means the task was skipped because it's missing necessary results
+	MissingResultsSkip SkippingReason = "Results were missing"
+	// None means the task was not skipped
+	None SkippingReason = "None"
+)
+
 // PipelineRunResult used to describe the results of a pipeline
 type PipelineRunResult struct {
 	// Name is the result's name as declared by the Pipeline

pkg/apis/pipeline/v1beta1/swagger.json

@@ -1889,14 +1889,20 @@
       "description": "SkippedTask is used to describe the Tasks that were skipped due to their When Expressions evaluating to False. This is a struct because we are looking into including more details about the When Expressions that caused this Task to be skipped.",
       "type": "object",
       "required": [
-        "name"
+        "name",
+        "reason"
       ],
       "properties": {
         "name": {
           "description": "Name is the Pipeline Task name",
           "type": "string",
           "default": ""
         },
+        "reason": {
+          "description": "Reason is the cause of the PipelineTask being skipped.",
+          "type": "string",
+          "default": ""
+        },
         "whenExpressions": {
           "description": "WhenExpressions is the list of checks guarding the execution of the PipelineTask",
           "type": "array",

pkg/reconciler/pipelinerun/pipelinerun_test.go

@@ -1836,9 +1836,11 @@ func runTestReconcileOnCancelledRunFinallyPipelineRun(t *testing.T, embeddedStat
 	verifyTaskRunStatusesCount(t, embeddedStatus, reconciledRun.Status, 0)
 
 	expectedSkippedTasks := []v1beta1.SkippedTask{{
-		Name: "hello-world-1",
+		Name:   "hello-world-1",
+		Reason: v1beta1.GracefullyCancelledSkip,
 	}, {
-		Name: "hello-world-2",
+		Name:   "hello-world-2",
+		Reason: v1beta1.GracefullyCancelledSkip,
 	}}
 
 	if d := cmp.Diff(expectedSkippedTasks, reconciledRun.Status.SkippedTasks); d != "" {
@@ -2278,7 +2280,7 @@ status:
 		hasNilCompletionTime bool
 		isFailed             bool
 		trInStatusCount      int
-		skippedTasks         []string
+		skippedTasks         []v1beta1.SkippedTask
 	}{
 		{
 			name:                 "stopped PipelineRun",
@@ -2289,7 +2291,7 @@ status:
 			hasNilCompletionTime: false,
 			isFailed:             true,
 			trInStatusCount:      0,
-			skippedTasks:         []string{"hello-world-1"},
+			skippedTasks:         []v1beta1.SkippedTask{{Name: "hello-world-1", Reason: v1beta1.GracefullyStoppedSkip}},
 		}, {
 			name:     "with running task",
 			pipeline: simpleHelloWorldPipeline,
@@ -2333,7 +2335,7 @@ status:
 			hasNilCompletionTime: false,
 			isFailed:             true,
 			trInStatusCount:      1,
-			skippedTasks:         []string{"hello-world-2"},
+			skippedTasks:         []v1beta1.SkippedTask{{Name: "hello-world-2", Reason: v1beta1.GracefullyStoppedSkip}},
 		},
 	}
 
@@ -2376,12 +2378,7 @@ status:
 				t.Fatalf("Expected %d TaskRuns in status but got %d", tc.trInStatusCount, len(reconciledRun.Status.TaskRuns))
 			}
 
-			var expectedSkipped []v1beta1.SkippedTask
-			for _, st := range tc.skippedTasks {
-				expectedSkipped = append(expectedSkipped, v1beta1.SkippedTask{Name: st})
-			}
-
-			if d := cmp.Diff(expectedSkipped, reconciledRun.Status.SkippedTasks); d != "" {
+			if d := cmp.Diff(tc.skippedTasks, reconciledRun.Status.SkippedTasks); d != "" {
 				t.Fatalf("Didn't get the expected list of skipped tasks. Diff: %s", diff.PrintWantGot(d))
 			}
 
@@ -3985,7 +3982,8 @@ spec:
 
 	actualSkippedTasks := pipelineRun.Status.SkippedTasks
 	expectedSkippedTasks := []v1beta1.SkippedTask{{
-		Name: "c-task",
+		Name:   "c-task",
+		Reason: v1beta1.WhenExpressionsSkip,
 		WhenExpressions: v1beta1.WhenExpressions{{
 			Input:    "aResultValue",
 			Operator: "in",
@@ -4165,30 +4163,34 @@ spec:
 	actualSkippedTasks := pipelineRun.Status.SkippedTasks
 	expectedSkippedTasks := []v1beta1.SkippedTask{{
 		// its when expressions evaluate to false
-		Name: "a-task",
+		Name:   "a-task",
+		Reason: v1beta1.WhenExpressionsSkip,
 		WhenExpressions: v1beta1.WhenExpressions{{
 			Input:    "foo",
 			Operator: "in",
 			Values:   []string{"bar"},
 		}},
 	}, {
 		// its when expressions evaluate to false
-		Name: "c-task",
+		Name:   "c-task",
+		Reason: v1beta1.WhenExpressionsSkip,
 		WhenExpressions: v1beta1.WhenExpressions{{
 			Input:    "foo",
 			Operator: "in",
 			Values:   []string{"bar"},
 		}},
 	}, {
 		// was attempted, but has missing results references
-		Name: "e-task",
+		Name:   "e-task",
+		Reason: v1beta1.MissingResultsSkip,
 		WhenExpressions: v1beta1.WhenExpressions{{
 			Input:    "$(tasks.a-task.results.aResult)",
 			Operator: "in",
 			Values:   []string{"aResultValue"},
 		}},
 	}, {
-		Name: "f-task",
+		Name:   "f-task",
+		Reason: v1beta1.ParentTasksSkip,
 	}}
 	if d := cmp.Diff(expectedSkippedTasks, actualSkippedTasks); d != "" {
 		t.Errorf("expected to find Skipped Tasks %v. Diff %s", expectedSkippedTasks, diff.PrintWantGot(d))
@@ -4311,7 +4313,8 @@ status:
 	actualSkippedTasks := pipelineRun.Status.SkippedTasks
 	expectedSkippedTasks := []v1beta1.SkippedTask{{
 		// its when expressions evaluate to false
-		Name: "b-task",
+		Name:   "b-task",
+		Reason: v1beta1.WhenExpressionsSkip,
 		WhenExpressions: v1beta1.WhenExpressions{{
 			Input:    "aResultValue",
 			Operator: "in",
@@ -6630,18 +6633,22 @@ spec:
 		t.Errorf("expected to see TaskRun %v created. Diff %s", expectedTaskRunName, diff.PrintWantGot(d))
 	}
 	expectedSkippedTasks := []v1beta1.SkippedTask{{
-		Name: "final-task-2",
+		Name:   "final-task-2",
+		Reason: v1beta1.MissingResultsSkip,
 	}, {
-		Name: "final-task-3",
+		Name:   "final-task-3",
+		Reason: v1beta1.WhenExpressionsSkip,
 		WhenExpressions: v1beta1.WhenExpressions{{
 			Input:    "aResultValue",
 			Operator: "notin",
 			Values:   []string{"aResultValue"},
 		}},
 	}, {
-		Name: "final-task-5",
+		Name:   "final-task-5",
+		Reason: v1beta1.MissingResultsSkip,
 	}, {
-		Name: "final-task-6",
+		Name:   "final-task-6",
+		Reason: v1beta1.MissingResultsSkip,
 	}}
 
 	if d := cmp.Diff(expectedSkippedTasks, reconciledRun.Status.SkippedTasks); d != "" {

pkg/reconciler/pipelinerun/resources/pipelinerunresolution.go

@@ -39,32 +39,10 @@ const (
 	ReasonConditionCheckFailed = "ConditionCheckFailed"
 )
 
-// SkippingReason explains why a task was skipped
-type SkippingReason string
-
-const (
-	// WhenExpressionsSkip means the task was skipped due to at least one of its when expressions evaluating to false
-	WhenExpressionsSkip SkippingReason = "WhenExpressionsSkip"
-	// ConditionsSkip means the task was skipped due to at least one of its conditions failing
-	ConditionsSkip SkippingReason = "ConditionsSkip"
-	// ParentTasksSkip means the task was skipped because its parent was skipped
-	ParentTasksSkip SkippingReason = "ParentTasksSkip"
-	// IsStoppingSkip means the task was skipped because the pipeline run is stopping
-	IsStoppingSkip SkippingReason = "IsStoppingSkip"
-	// IsGracefullyCancelledSkip means the task was skipped because the pipeline run has been gracefully cancelled
-	IsGracefullyCancelledSkip SkippingReason = "IsGracefullyCancelledSkip"
-	// IsGracefullyStoppedSkip means the task was skipped because the pipeline run has been gracefully stopped
-	IsGracefullyStoppedSkip SkippingReason = "IsGracefullyStoppedSkip"
-	// MissingResultsSkip means the task was skipped because it's missing necessary results
-	MissingResultsSkip SkippingReason = "MissingResultsSkip"
-	// None means the task was not skipped
-	None SkippingReason = "None"
-)
-
 // TaskSkipStatus stores whether a task was skipped and why
 type TaskSkipStatus struct {
 	IsSkipped      bool
-	SkippingReason SkippingReason
+	SkippingReason v1beta1.SkippingReason
 }
 
 // TaskNotFoundError indicates that the resolution failed because a referenced Task couldn't be retrieved
@@ -231,31 +209,31 @@ func (t *ResolvedPipelineRunTask) checkParentsDone(facts *PipelineRunFacts) bool
 }
 
 func (t *ResolvedPipelineRunTask) skip(facts *PipelineRunFacts) TaskSkipStatus {
-	var skippingReason SkippingReason
+	var skippingReason v1beta1.SkippingReason
 
 	switch {
 	case facts.isFinalTask(t.PipelineTask.Name) || t.IsStarted():
-		skippingReason = None
+		skippingReason = v1beta1.None
 	case facts.IsStopping():
-		skippingReason = IsStoppingSkip
+		skippingReason = v1beta1.StoppingSkip
 	case facts.IsGracefullyCancelled():
-		skippingReason = IsGracefullyCancelledSkip
+		skippingReason = v1beta1.GracefullyCancelledSkip
 	case facts.IsGracefullyStopped():
-		skippingReason = IsGracefullyStoppedSkip
+		skippingReason = v1beta1.GracefullyStoppedSkip
 	case t.skipBecauseParentTaskWasSkipped(facts):
-		skippingReason = ParentTasksSkip
+		skippingReason = v1beta1.ParentTasksSkip
 	case t.skipBecauseConditionsFailed():
-		skippingReason = ConditionsSkip
+		skippingReason = v1beta1.ConditionsSkip
 	case t.skipBecauseResultReferencesAreMissing(facts):
-		skippingReason = MissingResultsSkip
+		skippingReason = v1beta1.MissingResultsSkip
 	case t.skipBecauseWhenExpressionsEvaluatedToFalse(facts):
-		skippingReason = WhenExpressionsSkip
+		skippingReason = v1beta1.WhenExpressionsSkip
 	default:
-		skippingReason = None
+		skippingReason = v1beta1.None
 	}
 
 	return TaskSkipStatus{
-		IsSkipped:      skippingReason != None,
+		IsSkipped:      skippingReason != v1beta1.None,
 		SkippingReason: skippingReason,
 	}
 }
@@ -312,7 +290,7 @@ func (t *ResolvedPipelineRunTask) skipBecauseParentTaskWasSkipped(facts *Pipelin
 		if parentSkipStatus := parentTask.Skip(facts); parentSkipStatus.IsSkipped {
 			// if the parent task was skipped due to its `when` expressions,
 			// then we should ignore that and continue evaluating if we should skip because of other parent tasks
-			if parentSkipStatus.SkippingReason == WhenExpressionsSkip {
+			if parentSkipStatus.SkippingReason == v1beta1.WhenExpressionsSkip {
 				continue
 			}
 			return true
@@ -327,7 +305,7 @@ func (t *ResolvedPipelineRunTask) skipBecauseResultReferencesAreMissing(facts *P
 	if t.checkParentsDone(facts) && t.hasResultReferences() {
 		resolvedResultRefs, pt, err := ResolveResultRefs(facts.State, PipelineRunState{t})
 		rprt := facts.State.ToMap()[pt]
-		if err != nil && (t.IsFinalTask(facts) || rprt.Skip(facts).SkippingReason == WhenExpressionsSkip) {
+		if err != nil && (t.IsFinalTask(facts) || rprt.Skip(facts).SkippingReason == v1beta1.WhenExpressionsSkip) {
 			return true
 		}
 		ApplyTaskResults(PipelineRunState{t}, resolvedResultRefs)
@@ -343,26 +321,26 @@ func (t *ResolvedPipelineRunTask) IsFinalTask(facts *PipelineRunFacts) bool {
 
 // IsFinallySkipped returns true if a finally task is not executed and skipped due to task result validation failure
 func (t *ResolvedPipelineRunTask) IsFinallySkipped(facts *PipelineRunFacts) TaskSkipStatus {
-	var skippingReason SkippingReason
+	var skippingReason v1beta1.SkippingReason
 
 	switch {
 	case t.IsStarted():
-		skippingReason = None
+		skippingReason = v1beta1.None
 	case facts.checkDAGTasksDone() && facts.isFinalTask(t.PipelineTask.Name):
 		switch {
 		case t.skipBecauseResultReferencesAreMissing(facts):
-			skippingReason = MissingResultsSkip
+			skippingReason = v1beta1.MissingResultsSkip
 		case t.skipBecauseWhenExpressionsEvaluatedToFalse(facts):
-			skippingReason = WhenExpressionsSkip
+			skippingReason = v1beta1.WhenExpressionsSkip
 		default:
-			skippingReason = None
+			skippingReason = v1beta1.None
 		}
 	default:
-		skippingReason = None
+		skippingReason = v1beta1.None
 	}
 
 	return TaskSkipStatus{
-		IsSkipped:      skippingReason != None,
+		IsSkipped:      skippingReason != v1beta1.None,
 		SkippingReason: skippingReason,
 	}
 

pkg/reconciler/pipelinerun/resources/pipelinerunstate.go

@@ -556,17 +556,19 @@ func (facts *PipelineRunFacts) GetSkippedTasks() []v1beta1.SkippedTask {
 		if rprt.Skip(facts).IsSkipped {
 			skippedTask := v1beta1.SkippedTask{
 				Name:            rprt.PipelineTask.Name,
+				Reason:          rprt.Skip(facts).SkippingReason,
 				WhenExpressions: rprt.PipelineTask.WhenExpressions,
 			}
 			skipped = append(skipped, skippedTask)
 		}
 		if rprt.IsFinallySkipped(facts).IsSkipped {
 			skippedTask := v1beta1.SkippedTask{
-				Name: rprt.PipelineTask.Name,
+				Name:   rprt.PipelineTask.Name,
+				Reason: rprt.IsFinallySkipped(facts).SkippingReason,
 			}
 			// include the when expressions only when the finally task was skipped because
 			// its when expressions evaluated to false (not because results variables were missing)
-			if rprt.IsFinallySkipped(facts).SkippingReason == WhenExpressionsSkip {
+			if rprt.IsFinallySkipped(facts).SkippingReason == v1beta1.WhenExpressionsSkip {
 				skippedTask.WhenExpressions = rprt.PipelineTask.WhenExpressions
 			}
 			skipped = append(skipped, skippedTask)