Added docs for failure details

cmd/git/main.go

@@ -44,9 +44,9 @@ func (e ExitError) Error() string {
 
 type settings struct {
 	help                   bool
-	depth                  uint
 	url                    string
 	revision               string
+	depth                  uint
 	target                 string
 	resultFileCommitSha    string
 	resultFileCommitAuthor string
@@ -104,7 +104,6 @@ func main() {
 // Execute performs flag parsing, input validation and the Git clone
 func Execute(ctx context.Context) error {
 	flagValues = settings{depth: 1}
-
 	pflag.Parse()
 
 	if flagValues.help {

deploy/crds/shipwright.io_buildruns.yaml

@@ -459,7 +459,7 @@ spec:
                   type: object
                 type: array
               failedAt:
-                description: FailedAt points to the resource where the BuildRun failed
+                description: 'Deprecated: FailedAt points to the resource where the BuildRun failed'
                 properties:
                   container:
                     type: string

docs/buildrun.md

@@ -268,10 +268,29 @@ _Note_: We heavily rely on the Tekton TaskRun [Conditions](https://github.com/te
 
 ### Understanding failed BuildRuns
 
-To make it easier for users to understand why did a BuildRun failed, users can infer from the `Status.FailedAt` field, the pod and container where the failure took place.
+[DEPRECATED] To make it easier for users to understand why did a BuildRun failed, users can infer from the `Status.FailedAt` field, the pod and container where the failure took place.
 
 In addition, the `Status.Conditions` will host under the `Message` field a compacted message containing the `kubectl` command to trigger, in order to retrieve the logs.
 
+Lastly, users can check `Status.FailureDetails` field, which includes the same information available in the `Status.FailedAt` field, 
+as well as a humanly-readable error message and reason.
+The message and reason are only included if the build strategy provides them.
+
+Example of failed BuildRun:
+
+```yaml 
+# [...]
+status:
+  # [...]
+  failureDetails:
+    location:
+      container: step-source-default
+      pod: baran-build-buildrun-gzmv5-b7wbf-pod-bbpqr
+    message: The source repository does not exist, or you have insufficient permission
+      to access it.
+    reason: GitRemotePrivate
+```
+
 ### Step Results in BuildRun Status
 
 After the successful completion of a `BuildRun`, the `.status` field contains the results (`.status.taskResults`) emitted from the `TaskRun` steps generate by the `BuildRun` controller as part of processing the `BuildRun`. These results contain valuable metadata for users, like the _image digest_ or the _commit sha_ of the source code used for building.

docs/buildstrategies.md

@@ -296,10 +296,36 @@ status:
  # [...]
   output:
     digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53
-    size: "1989004"
+    size: 1989004
   # [...]
 ```
 
+Additionally, you can store error details for debugging purposes when a BuildRun fails using your strategy.
+
+| Result file                        | Description                                     |
+| ---------------------------------- | ----------------------------------------------- |
+| `$(results.shp-error-reason.path)` | File to store the error reason.          |
+| `$(results.shp-error-message.path)` | File to store the error message. |
+
+Reason is intended to be a one-word, CamelCase classification of the error source, with the first letter capitalized.
+Error details are only propagated if the build container terminates with a non-zero exit code.
+This information will be available in the `.status.failureDetails` field of the BuildRun. 
+
+```yaml 
+apiVersion: shipwright.io/v1alpha1
+kind: BuildRun
+# [...]
+status:
+  # [...]
+  failureDetails:
+    location:
+      container: step-source-default
+      pod: baran-build-buildrun-gzmv5-b7wbf-pod-bbpqr
+    message: The source repository does not exist, or you have insufficient permission
+      to access it.
+    reason: GitRemotePrivate
+```
+
 ## Steps Resource Definition
 
 All strategies steps can include a definition of resources(_limits and requests_) for CPU, memory and disk. For strategies with more than one step, each step(_container_) could require more resources than others. Strategy admins are free to define the values that they consider the best fit for each step. Also, identical strategies with the same steps that are only different in their name and step resources can be installed on the cluster to allow users to create a build with smaller and larger resource requirements.

pkg/apis/build/v1alpha1/buildrun_types.go

@@ -149,7 +149,7 @@ type BuildRunStatus struct {
 	// +optional
 	BuildSpec *BuildSpec `json:"buildSpec,omitempty"`
 
-	// FailedAt points to the resource where the BuildRun failed
+	// Deprecated: FailedAt points to the resource where the BuildRun failed
 	// +optional
 	FailedAt *FailedAt `json:"failedAt,omitempty"`
 

pkg/reconciler/buildrun/resources/conditions.go

@@ -11,11 +11,12 @@ import (
 	"knative.dev/pkg/apis"
 	"sigs.k8s.io/controller-runtime/pkg/client"
 
-	buildv1alpha1 "github.com/shipwright-io/build/pkg/apis/build/v1alpha1"
-	"github.com/shipwright-io/build/pkg/ctxlog"
 	corev1 "k8s.io/api/core/v1"
 	apierrors "k8s.io/apimachinery/pkg/api/errors"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	buildv1alpha1 "github.com/shipwright-io/build/pkg/apis/build/v1alpha1"
+	"github.com/shipwright-io/build/pkg/ctxlog"
 )
 
 // Common condition strings for reason, kind, etc.
@@ -81,9 +82,11 @@ func UpdateBuildRunUsingTaskRunCondition(ctx context.Context, client client.Clie
 				return err
 			}
 
+			//lint:ignore SA1019 we want to give users some time to adopt to failureDetails
 			buildRun.Status.FailedAt = &buildv1alpha1.FailedAt{Pod: pod.Name}
 
 			if failedContainer != nil {
+			  	//lint:ignore SA1019 we want to give users some time to adopt to failureDetails
 				buildRun.Status.FailedAt.Container = failedContainer.Name
 				message = fmt.Sprintf("buildrun step %s failed in pod %s, for detailed information: kubectl --namespace %s logs %s --container=%s",
 					failedContainer.Name,

pkg/reconciler/buildrun/resources/failureDetails.go → pkg/reconciler/buildrun/resources/failure_details.go

@@ -8,15 +8,18 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
-	buildv1alpha1 "github.com/shipwright-io/build/pkg/apis/build/v1alpha1"
 	"github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1"
 	v1 "k8s.io/api/core/v1"
 	"k8s.io/apimachinery/pkg/types"
 	"knative.dev/pkg/apis"
 	"sigs.k8s.io/controller-runtime/pkg/client"
+
+	buildv1alpha1 "github.com/shipwright-io/build/pkg/apis/build/v1alpha1"
 )
 
 const (
+	resultErrorMessage         = "error-message"
+	resultErrorReason          = "error-reason"
 	prefixedResultErrorReason  = prefixParamsResultsVolumes + "-" + resultErrorReason
 	prefixedResultErrorMessage = prefixParamsResultsVolumes + "-" + resultErrorMessage
 )
@@ -61,13 +64,14 @@ func extractFailedPodAndContainer(ctx context.Context, client client.Client, tas
 	}
 
 	failures := make(map[string]struct{})
+	// Find the names of all containers with failure status
 	for _, containerStatus := range pod.Status.ContainerStatuses {
 		if containerStatus.State.Terminated != nil && containerStatus.State.Terminated.ExitCode != 0 {
 			failures[containerStatus.Name] = struct{}{}
 		}
 	}
 
-	// Find the first container that failed
+	// Find the first container that has a failure status
 	var failedContainer *v1.Container
 	for i, container := range pod.Spec.Containers {
 		if _, has := failures[container.Name]; has {
@@ -80,8 +84,8 @@ func extractFailedPodAndContainer(ctx context.Context, client client.Client, tas
 }
 
 func extractFailureDetails(ctx context.Context, client client.Client, taskRun *v1beta1.TaskRun) (failure *buildv1alpha1.FailureDetails) {
-	failure = &buildv1alpha1.FailureDetails{ }
-	failure.Location = &buildv1alpha1.FailedAt{ Pod: taskRun.Status.PodName }
+	failure = &buildv1alpha1.FailureDetails{}
+	failure.Location = &buildv1alpha1.FailedAt{Pod: taskRun.Status.PodName}
 
 	if reason, message, hasReasonAndMessage := extractFailureReasonAndMessage(taskRun); hasReasonAndMessage {
 		failure.Reason = reason