openshift · eromanova97 · Jan 13, 2026 · Oct 14, 2025
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -55,15 +55,17 @@ Topics:
   File: configuring-build-strategies
 - Name: Configuring build runs
   File: configuring-build-runs
-- Name: Using Builds in a network-restricted environment
-  File: using-builds-in-a-network-restricted-environment
 ---
 Name: Work with Builds
 Dir: work_with_builds
 Distros: openshift-builds
 Topics:
-- Name: Managing Builds
-  File: using-builds
+- Name: Creating container images
+  File: creating-container-images
+- Name: Creating container images in a network restricted environment
+  File: creating-container-images-in-a-network-restricted-environment
+- Name: Managing builds
+  File: managing-builds
 ---
 Name: Work with Shared Resources
 Dir: work_with_shared_resources

diff --git a/configuring/using-builds-in-a-network-restricted-environment.adoc b/configuring/using-builds-in-a-network-restricted-environment.adoc
diff --git a/installing/installing-openshift-builds.adoc b/installing/installing-openshift-builds.adoc
@@ -20,4 +20,4 @@ include::modules/ob-disabling-shipwrightBuilds-components.adoc[leveloffset=+1]
 == Additional resources
 
 * link:https://docs.openshift.com/container-platform/latest/operators/admin/olm-adding-operators-to-cluster.html#olm-adding-operators-to-a-cluster[Adding Operators to a cluster]
-* xref:../work_with_builds/using-builds.adoc[Managing Builds]
+* xref:../work_with_builds/creating-container-images.adoc[Creating container images]
diff --git a/modules/ob-creating-a-build-with-oci-artifacts.adoc b/modules/ob-creating-a-build-with-oci-artifacts.adoc
@@ -3,11 +3,11 @@
 // * work-with-builds/using-builds.adoc
 
 :_mod-docs-content-type: PROCEDURE
-[id="Creating-a-build-with-OCI-artifacts_{context}"]
+[id="ob-creating-a-build-with-OCI-artifacts_{context}"]
 = Creating a build with OCI artifacts
 
 [role="_abstract"]
-You can create a build using an Open Container Initiative(OCI) artifact as your source code. An OCI artifact, also known as a scratch image, contains only the source code and is not intended to run as a container. You can pull the OCI artifact from a container registry and extract its contents to use as source code to run the build.
+Use Open Container Initiative (OCI) artifacts, also called scratch images, that you store in a registry as source code to build a container image. Pull and extract them to use as the source for your build; they contain only source code, not a runnable container.
 
 .Prerequisites
 
@@ -25,36 +25,42 @@ $ oc apply -f - <<EOF
 apiVersion: shipwright.io/v1beta1
 kind: Build
 metadata:
-  name: my-oci-build #<1>
+  name: <build_resource_name>
 spec:
   source:
     type: OCI
     ociArtifact:
-      image: <quay.io/org/image:tag> #<2>
+      image: <quay.io/org/image:tag>
   strategy:
-    name: <strategy-name> # <3>
+    name: <strategy_name>
     kind: ClusterBuildStrategy
   output: 
-    image: <target-image-registry/repository/image:tag> #<4>
-    pushSecret: <secret-name-for-credentials> #<5>
+    image: <target_image_registry/repository/image:tag> 
+    pushSecret: <secret_name_for_credentials>
 EOF
 ----
-<1> Defines the name of the `Build` resource.
-<2> Replace `<quay.io/org/image:tag>` with the location of the OCI artifact source image.
-<3> Replace `<strategy-name>` with the name of the build strategy to build the container (`buildah` or `source-to-image`).
-<4> Replace `<target-image-registry/repository/image:tag>` with the location where you want to push the built image.
-<5> Optional: Replace `<secret-name-for-credentials>` with the secret name that stores the credentials for pushing container images. To generate a secret for a private registry for authentication, see link:https://docs.redhat.com/en/documentation/builds_for_red_hat_openshift/1.5/html-single/authentication/index#ob-authentication-to-container-registries_understanding-authentication-at-runtime[Authentication to container registries]
++
+where:
+
+`<build_resource_name>`:: Specifies the name of the `Build` resource.
+`<quay.io/org/image:tag>`:: Specifies the location of the OCI artifact source image.
+`<strategy_name>`:: Specifies the name of the build strategy to build the container.
+`<target_image_registry/repository/image:tag>`:: Specifies the location where you want to push the built image.
+`<secret_name_for_credentials>`:: (Optional) Specifies the secret name that stores the credentials for pushing container images. To generate a secret for a private registry for authentication, see link:https://docs.redhat.com/en/documentation/builds_for_red_hat_openshift/1.5/html-single/authentication/index#ob-authentication-to-container-registries_understanding-authentication-at-runtime[Authentication to container registries].
 
 . Choose one of the following methods to upload your source code to the required registry and run the build:
-* Use the `shp` CLI:
+* Upload the source code using the `shp` CLI:
 
 ** Run the following command in the directory containing the local source code. It packages your source code into a scratch container image, pushes it to the required registry, and runs the build:
 +
 [source,terminal]
 ----
-$ shp build upload my-oci-build # <1>
+$ shp build upload <build_resource_name>
 ----
-<1> Defines the name of the `Build` resource.
++
+where:
+
+`<build_resource_name>`:: Specifies the name of the `Build` resource.
 
 * Upload the OCI artifact manually: 
 
@@ -70,22 +76,138 @@ COPY . /
 +
 [source,terminal]
 ----
-$ podman build -t <registry-path>/<image-name>:<tag> # <1>
+$ podman build -t <registry_path>/<image_name>:<tag> .
+----
++
+where:
+
+`<registry_path>`:: Specifies the build location for the registry where the image is stored.
+`<image_name>`:: Specifies the name of the container image.
+`<tag>`:: Specifies the tag of the image.
++
+
+When the container image is built successfully, a success message is displayed. See the following example command and output:
++
+[source,terminal]
+----
+podman build -t quay.io/example/oci:latest .
+----
++
+[source,terminal]
+----
+STEP 1/2: FROM scratch
+STEP 2/2: COPY . /
+--> Using cache 31f2530b092a8e0d75586407052900e9946043eca09deb9a2c9e50c2541bfcfd
+COMMIT quay.io/example/oci:latest
+--> 31f2530b092a
+Successfully tagged quay.io/example/oci:latest
+31f2530b092a8e0d75586407052900e9946043eca09deb9a2c9e50c2541bfcfd
 ----
-<1> Replace <registry-path>/<image-name>:<tag> with the build location for the container image.
 
 .. Push the container image to the required location using the following command:
 +
 [source,terminal]
 ----
-$ podman push <registry-path>/<image-name>:<tag>  # <1>
+$ podman push <registry_path>/<image_name>:<tag>
 ----
-<1> Replace <registry-path>/<image-name>:<tag> with the location where you want to push the built image.
++
+where:
+
+`<registry_path>`:: Specifies the build location for the registry where the image is stored.
+`<image_name>`:: Specifies the name of the container image.
+`<tag>`:: Specifies the tag of the image.
 
 .. Run the build using the following command:
 +
 [source,terminal]
 ----
-$ shp build run my-oci-build # <1>
+$ shp build run <build_resource_name>
+----
++
+where:
+
+`<build_resource_name>`:: Specifies the name of the `Build` resource.
+
+.Verification
+
+After all the containers complete their tasks, verify the statuses of 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
+oci-artifact-buildrun-pxg9w-pod     2/2     Running    0          58s
+oci-artifact-buildrun-pxg9w-pod     0/2     Completed  0          1m42s
+----
+
+. Check whether the respective `TaskRun` resource shows the `SUCCEEDED` field as `True`:
++
+[source,terminal]
+----
+$ oc get tr
+----
++
+Example output:
++
+[source,terminal]
+----
+NAME                           SUCCEEDED  REASON     STARTTIME   COMPLETIONTIME
+oci-artifact-buildrun-pxg9w    True       Succeeded  2m10s       28s
+----
+
+. Check whether the respective `BuildRun` resource shows the `SUCCEEDED` field as `True`:
++
+[source,terminal]
+----
+$ oc get br
+----
++
+Example output:
++
+[source,terminal]
+----
+NAME                     SUCCEEDED   REASON       STARTTIME     COMPLETIONTIME
+oci-artifact-buildrun    True        Succeeded    2m12s         30s
+----
+
+. 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. Log in to the registry and run the following command to pull the image:
++
+[source,terminal]
+----
+$ podman manifest inspect image-registry.openshift-image-registry.svc:5000/oci-artifacts-example/taxi-app
+----
++
+In the previous example, the project name is `oci-artifacts-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"
+            }
+     ]
 ----
-<1> Defines the name of the `Build` resource.
diff --git a/modules/ob-creating-a-buildah-build-in-a-network-restricted-environment.adoc b/modules/ob-creating-a-buildah-build-in-a-network-restricted-environment.adoc
@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+//* builds/work-with-builds.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 `oc` 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.
+`<image_name>`:: Specifies the name of the image.
+`<tag>`:: Specifies the tag of the image.
+
+. Perform the steps mentioned in the "Creating a buildah build" section.