From d527fe6730fc1ff8718f96c25e955e68d0c481b6 Mon Sep 17 00:00:00 2001
From: Olga Tikhomirova <85509260+missmesss@users.noreply.github.com>
Date: Thu, 9 May 2024 17:34:41 -0700
Subject: [PATCH] adding-hermetic-builds

---
 .../how-tos/configuring/hermetic-builds.adoc  | 66 ++++++++++++++++++-
 1 file changed, 65 insertions(+), 1 deletion(-)

diff --git a/docs/modules/ROOT/pages/how-tos/configuring/hermetic-builds.adoc b/docs/modules/ROOT/pages/how-tos/configuring/hermetic-builds.adoc
index ece1160a..27baa5af 100644
--- a/docs/modules/ROOT/pages/how-tos/configuring/hermetic-builds.adoc
+++ b/docs/modules/ROOT/pages/how-tos/configuring/hermetic-builds.adoc
@@ -1 +1,65 @@
-= Enabling hermetic builds
\ No newline at end of file
+= Enabling hermetic builds
+
+A hermetic build is a secure, self-contained build process that doesn't depend on anything outside of the build environment. This means that it does not have network access, is not vulnerable to external influences, and cannot fetch dependencies at run time. Instead, you must declare all required resources and dependencies in your build definition. 
+
+In {ProductName}, you can block network access to the build process and run a hermetic build by setting the `*hermetic*` parameter in your pipeline definition file to `true`. This means that you must fetch all dependencies _before_ the build can start. The following is an example code snippet:
+
+[source,yaml]
+----
+kind: PipelineRun
+spec:
+  params:
+    ...
+  - name: hermetic
+    value: "true"
+    ...
+----
+
+[IMPORTANT]
+====
+* Hermetic builds disable network access, so a build with dependencies outside of its Git repository--including supported languages--might fail. To prevent this, or to pull in dependencies from a package manager for one of the xref:how-tos/configuring/prefetching-dependencies.adoc#supported-languages[supported languages], follow the instructions in link:https://konflux-ci.dev/docs/how-tos/configuring/prefetching-dependencies/[Prefetching the package manager dependencies for the hermetic build].
++
+Similarly, with a link:https://github.com/redhat-appstudio/build-definitions/blob/main/task/buildah/0.1/buildah.yaml[Buildah] task for a non-Java application, when you set the `*hermetic*` parameter to `true`, you’re isolating the build from the network, which restricts it to building only from dependencies listed in your Git repository. 
+
+* Do not add these parameters to the link:https://github.com/burrsutter/partner-catalog-stage/blob/e2ebb05ba8b4e842010710898d555ed3ba687329/.tekton/partner-catalog-stage-wgxd-pull-request.yaml#L87[`**pipelineSpec.params**`] section, as it should always display the default values for hermetic builds.
+====
+
+.Procedure
+
+To create a hermetic build for a component, complete the following steps:
+
+. Go to the `.tekton` directory in your component's repository and find the `.yaml` files related to your `*pull request*` and `*push*` processes.
+
+. To configure the hermetic pipeline in both the `.yaml` files, add the following hermetic pipeline parameters to the `spec.params` section:
+
++
+[source,yaml]
+----
+spec:
+    params:
+        -   ...
+        -   name: hermetic
+            value: "true"
+----
+
++
+. Commit your changes to the component repository and create a pull request.
+
+. Verify that your build was successful, then merge your pull request.
+
+.Verification
+* From the {ProductName} *Applications* view, go to *Activity > Pipeline runs*.
+** Look at the pipeline run with *Build* in the *Type* column and confirm that the `build-container` stage displays a green checkmark. This indicates that the build process successfully fetched all dependencies.
+* From the {ProductName} *Applications* view, go to *Activity > Latest commits*.
+
+.Troubleshooting
+If your build fails, be sure to look at your logs:
+
+In {ProductName}, from the *Applications* view, select the application build you want to troubleshoot, then from the resulting *Overview* page, select the *Activity* tab. From there, under *Activity By*, select *Pipeline runs*. From the *Name* column, select the build whose logs you want to check, then from the resulting *Pipeline run details* view, do one of the following:
+
+* Select the *Logs* tab.
+* Alternatively, you can click *build-container*. When the right panel opens, select the *Logs* tab to see a partial view of the log for that build.
+
+== Additional resources
+
+For more information about the importance of provenance, see link:https://konflux-ci.dev/docs/discover/slsa-conformity/[Supply chain security through SLSA conformity].