Merge pull request #237 from redhat-appstudio/retriggering-builds

How-to guide on retriggering builds

docs/modules/ROOT/pages/how-to-guides/configuring-builds/proc_retriggering_build_pipelines.adoc

@@ -0,0 +1,65 @@
+= Retriggering Build Pipelines
+
+Occasionally, your build pipeline may fail unexpectedly, necessitating a retrigger. For pull requests, this can be achieved by adding comments. For post-merge builds, retriggering can be done either through UI, or by using the API to add an annotation to your Component resource.
+
+See also xref:how-to-guides/testing_applications/proc_retriggering_integration_tests.adoc[Retriggering integration tests].
+
+== Retriggering a Pre-merge build on a pull request
+
+.**Prerequisite**
+
+- You have a build pipeline run on a pull request that has failed, and you want to re-run the build without pushing a new commit.
+
+.**Procedure**
+
+. Add a comment to the pull request with the text `/retest` to trigger a new build.
+
+You should see the pipelinerun start executing in the UI and in the pull request.
+
+NOTE: For additional options, refer to the link:https://pipelinesascode.com/docs/guide/running/#gitops-command-on-pull-or-merge-request[pipelinesascode documentation].
+
+== Retriggering a Post-merge build from your main branch from the UI
+
+.**Prerequisite**
+
+- You have already merged a pull request, but the subsequent build failed, prompting a need for retriggering.
+
+.**Procedure**
+
+In the console, complete the following steps to retrigger the build pipeline:
+
+. Navigate to the *Activity* > *Pipeline runs* tab.
+. Identify the pipeline run that you want to retrigger.
+. Select the three dots on the right side of the table.
+. Select the *Rerun* action.
+
+The pipeline run should resume in the *Activity* > *Pipeline runs* tab.
+
+== Retriggering a Post-merge build from your main branch from the API
+
+.**Prerequisite**
+
+- You have already merged a pull request, but the subsequent build failed, prompting a need for retriggering.
+- You have CLI access to {ProductName}. For information on obtaining CLI access, refer to  xref:../../getting-started/getting_started_in_cli.adoc[Getting started in CLI]
+
+.**Procedure**
+
+. Identify the *Component* whose pipeline requires rerun.
+. Use the following command to annotate the *Component*, triggering a new build:
++
+[source]
+----
+$ kubectl annotate components/[component name] build.appstudio.openshift.io/request=trigger-pac-build
+----
+
+. The build is re-triggered automatically.
+
++
+[source]
+----
+$ tkn pipelinerun list
+
+[Example Output]
+NAME                            STARTED         DURATION   STATUS
+your-component-jfrdb            4 seconds ago   ---        Running
+----