Updated docs as per CQA rules

modules/ob-about-buildrun.adoc

@@ -7,7 +7,7 @@
 = BuildRun resource
 
 [role="_abstract"]
-A `BuildRun` resource invokes a build on the cluster similar to a Tekton task run. It represents a workload that instantiates a build for execution with specific parameters. Each BuildRun defines a unique name for monitoring, references a Build instance, and specifies a service account within a namespace.
+A `BuildRun` resource invokes a build on the cluster similar to a Tekton task run. It represents a workload that instantiates a build for execution with specific parameters. Each `BuildRun` defines a unique name for monitoring, references a Build instance, and specifies a service account within a namespace.
 
 A `BuildRun` resource helps you to define the following elements:
 

modules/ob-basic-authentication.adoc

@@ -7,7 +7,7 @@
 = Basic authentication
 
 [role="_abstract"]
-Configure basic authentication credentials for a Git repository by creating a Kubernetes secret with a username and password. The following example shows a Git basic-auth secret referenced by a build:
+Configure Basic authentication credentials for a Git repository by creating a Kubernetes secret with a username and password. The following example shows a Git basic-auth secret referenced by a build:
 
 [source,yaml]
 ----
@@ -24,5 +24,5 @@ stringData:
 ----
 where:
 
-`type`:: Specifies the Kubernetes secret type. `kubernetes.io/basic-auth` indicates that the secret contains credentials for basic authentication.
-`stringData`:: Specifies the username and password used for basic authentication to the Git repository referenced by the build.
+`type`:: Specifies the Kubernetes secret type. `kubernetes.io/basic-auth` indicates that the secret contains credentials for Basic authentication.
+`stringData`:: Specifies the username and password used for Basic authentication to the Git repository referenced by the build.

modules/ob-build-run-status.adoc

@@ -10,7 +10,7 @@
 Monitor the progress and completion of your image builds by checking the status of the `BuildRun` custom resource (CR).
 A `BuildRun` CR stores status information in the status.conditions field. This field includes the status, the reason for that status, and a descriptive message. For example, a `Succeeded` condition type means the build finished successfully.
 
-The following examples show how to view the status of a specific BuildRun CR.
+The following examples show how to view the status of a specific `BuildRun` CR.
 
 Unknown status::
 An `Unknown` status indicates the build is still starting or in progress. The following example shows a `BuildRun` with `Unknown` status:

modules/ob-configuring-pods-in-build-run.adoc

@@ -11,7 +11,7 @@ Configure pod scheduling and placement for {builds-shortname} by using optional
 
 Use the following fields to configure {builds-shortname} pods:
 
-* `spec.tolerations`: Specifies pod tolerations. Note: Only the NoSchedule taint effect is supported.
+* `spec.tolerations`: Specifies pod tolerations. Note: Only the `NoSchedule` taint effect is supported.
 
 * `spec.nodeSelector`: Specifies the nodes where the pod must run.
 

modules/ob-configuring-pods-in-build.adoc

@@ -20,6 +20,6 @@ Use the following optional `Build` CR fields to configure {builds-shortname} pod
 
 [NOTE]
 ====
-If you define these fields in the Build and BuildRun CRs, the BuildRun values take priority.
+If you define these fields in the Build and `BuildRun` CRs, the `BuildRun` values take priority.
 ====
 

modules/ob-creating-a-buildah-build-network-restricted.adoc

@@ -0,0 +1,227 @@
+// Module included in the following assemblies:
+//
+// * work_with_builds/creating-container-images-in-a-network-restricted-environment.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id='ob-creating-a-buildah-build-in-a-network-restricted-environment_{context}']
+= Creating a buildah build in a network-restricted environment
+
+[role="_abstract"]
+Create a `buildah` build in a network-restricted environment by mirroring the images that `buildah` build strategy requires. Mirroring the images eliminates the need for public registry access. This ensures clusters use only images that comply with external content controls.
+
+.Prerequisites
+
+* You have installed the {builds-operator} on the {ocp-product-title} cluster.
+* You have installed the `oc` CLI.
+* Optional: You have installed the link:https://console.redhat.com/openshift/downloads[`shp` CLI].
+* Your cluster can connect and interact with the Git source that you can use to create the buildah build.
+* You have the builder-image required to create the `buildah` build in your local registry. If the builder-image is not present in the local registry, mirror the source image.
+
+.Procedure
+
+. Run the following command to mirror the images that `buildah` build strategy requires:
++
+[source,terminal]
+----
+$ oc image mirror --insecure -a <registry_authentication> registry.redhat.io/ubi8/buildah@sha256:1c89cc3cab0ac0fc7387c1fe5e63443468219aab6fd531c8dad6d22fd999819e <mirror_registry>/<repo>/ubi8_buildah
+----
++
+where:
+
+`<registry_authentication>`:: Specifies the authentication credentials used to access a container registry. This is required when pushing to or pulling from a private registry.
+`<mirror_registry>`:: Specifies the registry where the image you want to mirror is stored.
+
+. Create a `Build` resource and apply it to the {ocp-product-title} cluster. You can
+do so by using the `oc` command or the `shp` command:
++
+[source,terminal]
+----
+$ oc apply -f - <<EOF
+apiVersion: shipwright.io/v1beta1
+kind: Build
+metadata:
+  name: buildah-golang-build
+spec:
+  source:
+    type: Git
+    git:
+      url: https://github.com/shipwright-io/sample-go
+    contextDir: docker-build
+  strategy:
+    name: buildah
+    kind: ClusterBuildStrategy
+  paramValues:
+  - name: dockerfile
+    value: Dockerfile
+  output:
+    image: image-registry.openshift-image-registry.svc:5000/buildah-example/sample-go-app
+EOF
+----
++
+--
+where:
+
+`source`:: Defines the location where the source code is placed.
+`strategy`:: Defines the build strategy that you use to build the container.
+`paramValues`:: Defines the parameter defined in the build strategy. To set the value of the `dockerfile` strategy parameter, specify the Dockerfile location required to build the output image.
+`output`:: Defines the location where the built image is pushed. In this procedural example, the built image is pushed to the {ocp-product-title} cluster internal registry. `buildah-example` is the name of the current project. Ensure that the specified project exists to allow the image push.
+--
+
++
+[source,terminal]
+----
+$ shp build create buildah-golang-build \
+--source-url="https://github.com/redhat-openshift-builds/samples"
+--source-context-dir="buildah-build" \
+--strategy-name="buildah" \
+--dockerfile="Dockerfile" \
+--output-image="image-registry.openshift-image-registry.svc:5000/buildah-example/go-app"
+----
++
+where:
+
+`source-context-dir`:: Defines the location where the source code is placed.
+`strategy-name`:: Defines the build strategy that you use to build the container.
+`dockerfile`:: Defines the parameter defined in the build strategy. To set the value of the `dockerfile` strategy parameter, specifies the Dockerfile location required to build the output image.
+`output-image`:: Defines the location where the built image is pushed. In this procedural example, the built image is pushed to the {ocp-product-title} cluster internal registry. `buildah-example` is the name of the current project. Ensure that the specified project exists to allow the image push.
+
+. Check if the `Build` resource is created. You can do so by using the `oc` command or
+the `shp` command:
++
+[source,terminal]
+----
+$ oc get builds.shipwright.io buildah-golang-build
+----
+
++
+[source,terminal]
+----
+$ shp build list
+----
+
+. Create a `BuildRun` resource and apply it to the {ocp-product-title} cluster. You can do so by using the `oc` command or the `shp` command:
++
+[source,terminal]
+----
+$ oc apply -f - <<EOF
+apiVersion: shipwright.io/v1beta1
+kind: BuildRun
+metadata:
+  name: buildah-golang-buildrun
+spec:
+  build:
+    name: buildah-golang-build
+EOF
+----
++
+where:
+
+`spec.build.name`:: Defines the build to run, which is expected to be available in the same namespace.
+
++
+[source,terminal]
+----
+$ shp build run buildah-golang-build --follow
+----
+* `--follow`:: (Optional) Use the `--follow` flag to view the build logs in the output result.
+
+. Check if the `BuildRun` resource is created. You can do so by using the `oc` command or
+the `shp` command:
++
+[source,terminal]
+----
+$ oc get buildrun buildah-golang-buildrun
+----
+
++
+[source,terminal]
+----
+$ shp buildrun list
+----
++
+The `BuildRun` resource creates a `TaskRun` resource, which then creates the pods to execute build strategy steps.
+
+.Verification
+
+After all the containers complete their tasks, verify the following resources:
+
+. Check whether the pod shows the `STATUS` field as `Completed`:
++
+[source,terminal]
+----
+$ oc get pods -w
+----
++
+Example output:
++
+[source,terminal]
+----
+NAME                                READY   STATUS    RESTARTS   AGE
+buildah-golang-buildrun-dtrg2-pod   2/2     Running   0          4s
+buildah-golang-buildrun-dtrg2-pod   1/2     NotReady  0          7s
+buildah-golang-buildrun-dtrg2-pod   0/2     Completed 0          55s
+----
+
+. Check whether the required `TaskRun` resource shows the `SUCCEEDED` field as `True`:
++
+[source,terminal]
+----
+$ oc get tr
+----
++
+Example output:
++
+[source,terminal]
+----
+NAME                           SUCCEEDED  REASON     STARTTIME   COMPLETIONTIME
+buildah-golang-buildrun-dtrg2  True       Succeeded  11m         8m51s
+----
+
+. Check whether the required `BuildRun` resource shows the `SUCCEEDED` field as `True`:
++
+[source,terminal]
+----
+$ oc get br
+----
++
+Example output:
++
+[source,terminal]
+----
+NAME                     SUCCEEDED   REASON       STARTTIME     COMPLETIONTIME
+buildah-golang-buildrun  True        Succeeded    13m           11m
+----
+
+. During verification, if a build run fails, you can check the `status.failureDetails` field in your `BuildRun` resource to identify the exact point where the failure happened in the pod or container.
++
+[NOTE]
+====
+The pod might switch to a `NotReady` state because one of the containers has completed its task. This is an expected behavior.
+====
+
+. Validate whether the image has been pushed to the registry that is specified in the `build.spec.output.image` field. Run the following command to pull the image from a node that can access the internal registry:
++
+[source,terminal]
+----
+$ podman manifest inspect image-registry.openshift-image-registry.svc:5000/buildah-example/taxi-app
+----
++
+In the previous example, the project name is `buildah-example`, and the image name is `taxi-app`.
++
+Example output:
++
+[source,terminal]
+----
+   "schemaVersion": 2,
+    "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
+    "manifests": [
+        {
+            "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
+            "size": 594,
+            "digest": "sha256:6a05100e302c86c03fec6277f4b3107f1fdde6c69d3ca9a4207e4735a5213e32",
+            "platform": {
+                "architecture": "amd64",
+                "os": "linux"
+            }
+     ]
+----