fix(taskspec): ensure TaskRun.Status.Steps ordering matches pod execution order

The TaskRun.Status.Steps list was not guaranteed to reflect the true
execution order when StepActions were involved, causing confusing behavior
in dashboards like Tekton Dashboard where steps would appear to "pop" into
view and reshuffle.

This change addresses three related issues:
1. Steps populated from StepAction resolution appeared first in Status.Steps,
   while inline steps were only added later during pod-based status
   reconciliation, creating a mismatch with actual execution order.
2. When TaskRuns used StepActions, inline steps were missing from
   Status.Steps during the resolution phase, contributing to the ordering
   confusion.
3. The final Status.Steps ordering didn't match the pod container sequence,
   making it difficult for dashboards to display accurate step progression.

The fix ensures that:
- Status.Steps are populated for both StepAction-backed and inline steps
  during resolution, even when there is no StepActions involved
- The final Status.Steps ordering is aligned with the pod step container
  sequence by creating a temporary slice and replacing trs.Steps in one shot
- Existing Provenance information is preserved for matching steps by name

Author: Maximilien-R

pkg/pod/status.go

@@ -268,8 +268,15 @@ func setTaskRunStatusBasedOnStepStatus(ctx context.Context, logger *zap.SugaredL
 		}
 	}
 
+	// Build a lookup map for step state provenances.
+	stepStateProvenances := make(map[string]*v1.Provenance)
+	for _, ss := range trs.Steps {
+		stepStateProvenances[ss.Name] = ss.Provenance
+	}
+
 	// Continue with extraction of termination messages
-	for _, s := range stepStatuses {
+	orderedStepStates := make([]v1.StepState, len(stepStatuses))
+	for i, s := range stepStatuses {
 		// Avoid changing the original value by modifying the pointer value.
 		state := s.State.DeepCopy()
 		taskRunStepResults := []v1.TaskRunStepResult{}
@@ -378,18 +385,13 @@ func setTaskRunStatusBasedOnStepStatus(ctx context.Context, logger *zap.SugaredL
 			Inputs:            sas.Inputs,
 			Outputs:           sas.Outputs,
 		}
-		foundStep := false
-		for i, ss := range trs.Steps {
-			if ss.Name == stepState.Name {
-				stepState.Provenance = ss.Provenance
-				trs.Steps[i] = stepState
-				foundStep = true
-				break
-			}
-		}
-		if !foundStep {
-			trs.Steps = append(trs.Steps, stepState)
+		if stepStateProvenance, exist := stepStateProvenances[stepState.Name]; exist {
+			stepState.Provenance = stepStateProvenance
 		}
+		orderedStepStates[i] = stepState
+	}
+	if len(orderedStepStates) > 0 {
+		trs.Steps = orderedStepStates
 	}
 
 	return errors.Join(errs...)

pkg/pod/status_test.go

@@ -814,14 +814,14 @@ func TestMakeTaskRunStatus_StepArtifacts(t *testing.T) {
 
 func TestMakeTaskRunStatus(t *testing.T) {
 	for _, c := range []struct {
-		desc      string
-		podStatus corev1.PodStatus
-		pod       corev1.Pod
-		want      v1.TaskRunStatus
+		desc       string
+		podStatus  corev1.PodStatus
+		pod        corev1.Pod
+		stepStates []v1.StepState
+		want       v1.TaskRunStatus
 	}{{
 		desc:      "empty",
 		podStatus: corev1.PodStatus{},
-
 		want: v1.TaskRunStatus{
 			Status: statusRunning(),
 			TaskRunStatusFields: v1.TaskRunStatusFields{
@@ -1741,6 +1741,137 @@ func TestMakeTaskRunStatus(t *testing.T) {
 				CompletionTime: &metav1.Time{Time: time.Now()},
 			},
 		},
+	}, {
+		desc: "TaskRun status steps ordering based on pod spec containers",
+		pod: corev1.Pod{
+			ObjectMeta: metav1.ObjectMeta{
+				Name: "pod",
+			},
+			Spec: corev1.PodSpec{
+				Containers: []corev1.Container{{
+					Name: "step-first-inline",
+				}, {
+					Name: "step-second-remote",
+				}, {
+					Name: "step-third-inline",
+				}, {
+					Name: "step--inline",
+				}, {
+					Name: "step-fourth-remote",
+				}, {
+					Name: "step-fifth-remote",
+				}},
+			},
+			Status: corev1.PodStatus{
+				Phase: corev1.PodSucceeded,
+				ContainerStatuses: []corev1.ContainerStatus{{
+					Name: "step-second-remote",
+					State: corev1.ContainerState{
+						Terminated: &corev1.ContainerStateTerminated{},
+					},
+				}, {
+					Name: "step-fourth-remote",
+					State: corev1.ContainerState{
+						Terminated: &corev1.ContainerStateTerminated{},
+					},
+				}, {
+					Name: "step--inline",
+					State: corev1.ContainerState{
+						Terminated: &corev1.ContainerStateTerminated{},
+					},
+				}, {
+					Name: "step-first-inline",
+					State: corev1.ContainerState{
+						Terminated: &corev1.ContainerStateTerminated{},
+					},
+				}, {
+					Name: "step-fifth-remote",
+					State: corev1.ContainerState{
+						Terminated: &corev1.ContainerStateTerminated{},
+					},
+				}, {
+					Name: "step-third-inline",
+					State: corev1.ContainerState{
+						Terminated: &corev1.ContainerStateTerminated{},
+					},
+				}},
+			},
+		},
+		stepStates: []v1.StepState{
+			{
+				Name: "second-remote",
+				Provenance: &v1.Provenance{
+					RefSource: &v1.RefSource{
+						URI:    "test-uri",
+						Digest: map[string]string{"sha256": "digest"},
+					},
+				},
+			},
+			{
+				Name: "fourth-remote",
+			},
+			{
+				Name: "fifth-remote",
+				Provenance: &v1.Provenance{
+					RefSource: nil,
+				},
+			},
+		},
+		want: v1.TaskRunStatus{
+			Status: statusSuccess(),
+			TaskRunStatusFields: v1.TaskRunStatusFields{
+				Steps: []v1.StepState{{
+					ContainerState: corev1.ContainerState{
+						Terminated: &corev1.ContainerStateTerminated{},
+					},
+					Name:      "first-inline",
+					Container: "step-first-inline",
+				}, {
+					ContainerState: corev1.ContainerState{
+						Terminated: &corev1.ContainerStateTerminated{},
+					},
+					Name:      "second-remote",
+					Container: "step-second-remote",
+					Provenance: &v1.Provenance{
+						RefSource: &v1.RefSource{
+							URI:    "test-uri",
+							Digest: map[string]string{"sha256": "digest"},
+						},
+					},
+				}, {
+					ContainerState: corev1.ContainerState{
+						Terminated: &corev1.ContainerStateTerminated{},
+					},
+					Name:      "third-inline",
+					Container: "step-third-inline",
+				}, {
+					ContainerState: corev1.ContainerState{
+						Terminated: &corev1.ContainerStateTerminated{},
+					},
+					Name:      "-inline",
+					Container: "step--inline",
+				}, {
+					ContainerState: corev1.ContainerState{
+						Terminated: &corev1.ContainerStateTerminated{},
+					},
+					Name:      "fourth-remote",
+					Container: "step-fourth-remote",
+				}, {
+					ContainerState: corev1.ContainerState{
+						Terminated: &corev1.ContainerStateTerminated{},
+					},
+					Name:      "fifth-remote",
+					Container: "step-fifth-remote",
+					Provenance: &v1.Provenance{
+						RefSource: nil,
+					},
+				}},
+				Sidecars:  []v1.SidecarState{},
+				Artifacts: &v1.Artifacts{},
+				// We don't actually care about the time, just that it's not nil
+				CompletionTime: &metav1.Time{Time: time.Now()},
+			},
+		},
 	}, {
 		desc: "include non zero exit code in a container termination message if entrypoint is set to ignore the error",
 		pod: corev1.Pod{
@@ -1964,6 +2095,7 @@ func TestMakeTaskRunStatus(t *testing.T) {
 				Status: v1.TaskRunStatus{
 					TaskRunStatusFields: v1.TaskRunStatusFields{
 						StartTime: &metav1.Time{Time: startTime},
+						Steps:     c.stepStates,
 					},
 				},
 			}

pkg/reconciler/taskrun/resources/taskspec.go

@@ -174,6 +174,8 @@ func resolveStepRef(ctx context.Context, taskSpec v1.TaskSpec, taskRun *v1.TaskR
 
 // updateTaskRunProvenance update the TaskRun's status with source provenance information for a given step
 func updateTaskRunProvenance(taskRun *v1.TaskRun, stepName string, stepIndex int, source *v1.RefSource, stepStatusIndex map[string]int) {
+	var provenance *v1.Provenance
+
 	// The StepState already exists. Update it in place
 	if index, found := stepStatusIndex[stepName]; found {
 		if taskRun.Status.Steps[index].Provenance == nil {
@@ -183,19 +185,36 @@ func updateTaskRunProvenance(taskRun *v1.TaskRun, stepName string, stepIndex int
 		return
 	}
 
+	provenance = &v1.Provenance{RefSource: source}
+
 	// No existing StepState found. Create and append a new one
 	newState := v1.StepState{
 		Name:       pod.TrimStepPrefix(pod.StepName(stepName, stepIndex)),
-		Provenance: &v1.Provenance{RefSource: source},
+		Provenance: provenance,
 	}
 	taskRun.Status.Steps = append(taskRun.Status.Steps, newState)
 }
 
 // GetStepActionsData extracts the StepActions and merges them with the inlined Step specification.
 func GetStepActionsData(ctx context.Context, taskSpec v1.TaskSpec, taskRun *v1.TaskRun, tekton clientset.Interface, k8s kubernetes.Interface, requester remoteresource.Requester) ([]v1.Step, error) {
-	// If there are no step-ref to resolve, return immediately
+	steps := make([]v1.Step, len(taskSpec.Steps))
+
+	// Init step states and known step states indexes lookup map
+	if taskRun.Status.Steps == nil {
+		taskRun.Status.Steps = []v1.StepState{}
+	}
+	stepStatusIndex := make(map[string]int, len(taskRun.Status.Steps))
+	for i, stepState := range taskRun.Status.Steps {
+		stepStatusIndex[stepState.Name] = i
+	}
+
+	// If there are no step-ref to resolve, return immediately with nil provenance
 	if !hasStepRefs(&taskSpec) {
-		return taskSpec.Steps, nil
+		for i, step := range taskSpec.Steps {
+			steps[i] = step
+			updateTaskRunProvenance(taskRun, step.Name, i, nil, stepStatusIndex) // create StepState with nil provenance
+		}
+		return steps, nil
 	}
 
 	// Phase 1: Concurrently resolve all StepActions
@@ -225,27 +244,16 @@ func GetStepActionsData(ctx context.Context, taskSpec v1.TaskSpec, taskRun *v1.T
 	}
 
 	// Phase 2: Sequentially merge results into the final step list and update status
-	if taskRun.Status.Steps == nil {
-		taskRun.Status.Steps = []v1.StepState{}
-	}
-	stepStatusIndex := make(map[string]int, len(taskRun.Status.Steps))
-	for i, stepState := range taskRun.Status.Steps {
-		stepStatusIndex[stepState.Name] = i
-	}
-
-	steps := make([]v1.Step, len(taskSpec.Steps))
 	for i, step := range taskSpec.Steps {
 		if step.Ref == nil {
 			steps[i] = step
+			updateTaskRunProvenance(taskRun, step.Name, i, nil, stepStatusIndex) // create StepState for inline step with nil provenance
 			continue
 		}
 
 		stepRefResolution := stepRefResolutions[i]
 		steps[i] = *stepRefResolution.resolvedStep
-
-		if stepRefResolution.source != nil {
-			updateTaskRunProvenance(taskRun, stepRefResolution.resolvedStep.Name, i, stepRefResolution.source, stepStatusIndex)
-		}
+		updateTaskRunProvenance(taskRun, stepRefResolution.resolvedStep.Name, i, stepRefResolution.source, stepStatusIndex)
 	}
 
 	return steps, nil