Added docs for failure details

shipwright-io · Jan 3, 2022 · 4f3a7b1 · 4f3a7b1
1 parent 9c53217
commit 4f3a7b1
Showing 1 changed file with 17 additions and 0 deletions.
diff --git a/docs/buildrun.md b/docs/buildrun.md
@@ -17,6 +17,7 @@ SPDX-License-Identifier: Apache-2.0
 - [BuildRun Status](#buildrun-status)
   - [Understanding the state of a BuildRun](#understanding-the-state-of-a-buildrun)
   - [Understanding failed BuildRuns](#understanding-failed-buildruns)
+    - [Understanding failed git-source step](#understanding-failed-git-source-step)
   - [Step Results in BuildRun Status](#step-results-in-buildrun-status)
   - [Build Snapshot](#build-snapshot)
 - [Relationship with Tekton Tasks](#relationship-with-tekton-tasks)
@@ -292,6 +293,22 @@ status:
     reason: GitRemotePrivate
 ```
 
+#### Understanding failed git-source step
+
+All git related operations support error reporting via `Status.FailureDetails`. The following table explains the possible
+error reasons: 
+
+| Reason |  Description |
+| --- |  --- |
+| `git-auth-basic-invalid` | Basic authentication has failed. Check your username or password. Note: GitHub requires a personal access token instead of your regular password. |
+| `git-auth-ssh-invalid` | 	The key is invalid for the specified target. Please make sure that the Git repository exists, you have sufficient permissions, and the key is in the right format. |
+| `git-remote-revision` | The remote revision does not exist. Check your revision argument. |
+| `git-remote-repository`| The source repository does not exist, or you have insufficient permission to access it. |
+| `git-remote-private` | You are trying to access a non existing or private repository without having sufficient permissions to access it via HTTPS. |
+| `git-auth-basic-incomplete`| Basic Auth incomplete: Both username and password need to be configured. |
+| `git-auth-ssh-unexpected`| Credential/URL inconsistency: SSH credentials provided, but URL is not a SSH Git URL. |
+| `git-auth-ssh-expected`| Credential/URL inconsistency: No SSH credentials provided, but URL is a SSH Git URL. |
+
 ### 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.