Merge pull request #78 from arewm/retrigger-builds

fix(KFLUXBUGS-1414) Migrate docs on retriggering build pipelines

Author: arewm

docs/modules/ROOT/pages/how-tos/_nav.adoc

@@ -7,6 +7,7 @@
 *** xref:how-tos/configuring/hermetic-builds.adoc[Enabling hermetic builds]
 *** xref:how-tos/configuring/prefetching-dependencies.adoc[Prefetching package manager dependencies]
 *** xref:how-tos/configuring/component-nudges.adoc[Defining component relationships]
+*** xref:how-tos/configuring/rerunning.adoc[Retriggering build pipelines]
 *** xref:how-tos/configuring/redundant-rebuilds.adoc[Preventing redundant rebuilds]
 ** xref:how-tos/testing/index.adoc[Testing your components and applications]
 *** xref:how-tos/testing/build/index.adoc[Build-time tests]

docs/modules/ROOT/pages/how-tos/configuring/rerunning.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-tos/testing/integration/rerunning.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/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
+----

docs/modules/ROOT/pages/how-tos/testing/index.adoc

@@ -24,6 +24,8 @@ Build-time tests include the following security-focused tests:
 
 You can also create your own build-time tests. To add a custom build-time test for a component, xref:/how-tos/configuring/customizing-the-build.adoc[customize its build pipeline] to include the test as another Tekton task. 
 
+These tests are coupled with the building of artifacts. In order to rerun the tests, the build pipeline will need to be rerun and the newly produced artifact will be tested as described in xref:/how-tos/configuring/rerunning.adoc[retriggering build pipelines].
+
 == Integration tests
 
 Integration tests ensure that all components within an application are able to work together at the same time. You can xref:./integration/adding.adoc[add an integration test], simply by giving {ProductName} the address to a GitHub repo, and the path within that repo to an IntegrationTestScenario (ITS). An ITS is a YAML file, one that contains a Tekton Pipeline that defines an integration test.
@@ -33,3 +35,5 @@ Integration tests ensure that all components within an application are able to w
 As with build-time tests, you can also create your own integration tests.  To add your own test that runs on all components of an application, xref:./integration/creating.adoc[create a custom integration test].
 
 The integration service provides users with the ability to reset their component's Global Candidate List to a desired state with a manually created `override`, you can xref:./integration/creatingoverridesnapshot.adoc[create an override snapshot] and provide a valid container image for component to reset the component's Global Candidate List.
+
+While these tests are triggered after new artifacts are built (for example after build pipelines have successfully completed), their execution can be retriggered without building new artifacts. This process is described in xref:./integration/rerunning.adoc[retriggering integration tests].

docs/modules/ROOT/pages/how-tos/testing/integration/rerunning.adoc

@@ -2,6 +2,8 @@
 
 Integration test scenarios for a given snapshot can be re-triggered by adding a label to the snapshot.
 
+See also xref:/how-tos/configuring/rerunning.adoc[Retriggering build pipelines].
+
 .Prerequisites
 - You have a snapshot that has completed all its initial tests. All initial tests must be finished before you trigger subsequent tests.