Merge pull request #87 from tkdchen/add-doc-build-with-args

Add doc: Passing build arguments

Author: arewm

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

@@ -9,6 +9,7 @@
 *** 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/configuring/build-with-args.adoc[Passing buildah arguments]
 ** xref:how-tos/testing/index.adoc[Testing your components and applications]
 *** xref:how-tos/testing/build/index.adoc[Build-time tests]
 **** xref:how-tos/testing/build/snyk.adoc[Enabling Snyk]

docs/modules/ROOT/pages/how-tos/configuring/build-with-args.adoc

@@ -0,0 +1,77 @@
+= Passing buildah arguments
+
+{ProductName} buildah task accepts link:https://github.com/konflux-ci/build-definitions/blob/main/task/buildah/0.1/buildah.yaml#L78[`BUILD_ARGS` parameter] that allows passing build arguments to the underlying `buildah` command through `--build-arg` flag. To enable this, make the following changes to the PipelineRuns under the `.tekton/` directory:
+
+. Define a `build-args` Pipeline parameter (if not already present) in `.spec.pipelineSpec.params` to accept the passed-in build arguments.
+
++
+[source,yaml]
+--
+spec:
+  # ...
+  pipelineSpec:
+    params:
+    # ...
+    - name: build-args
+      type: array
+      default: []
+--
+
+. Pass the argument to link:https://github.com/konflux-ci/build-definitions/tree/main/task/buildah/[buildah task]. Add `BUILD_ARGS` to `build-container.params` (if not already present):
+
++
+[source,yaml]
+--
+spec:
+  # ...
+  pipelineSpec:
+    tasks:
+    # ...
+    - name: build-container
+      params:
+      # ...
+      - name: BUILD_ARGS
+        value: ["$(params.build-args[*])"]
+--
+
++
+The value can also be in form `tasks.<taskName>.results.<resultName>[*]` if it is generated by another task dynamically.
+
++
+For example, you can do more creative things with the `BUILD_ARGS` parameter like this snippet of a pipeline that allows passing `build-args` through the pipeline parameter (as described above) but also incorporates `build-args` generated dynamically by other tasks:
+
++
+[source,yaml]
+--
+spec:
+  # ...
+  pipelineSpec:
+    tasks:
+    # ...
+    - name: build-container
+      params:
+      # ...
+      - name: BUILD_ARGS
+        value:
+        # pass the build args array from the pipeline param
+        - $(params.build-args[*])
+        # and a dynamically generated array of build args
+        - $(tasks.my-build-arg-generator-task.results.BUILD_ARGS[*])
+        # and a build arg with a static name and dynamic value
+        - VERSION=$(tasks.my-get-version-task.results.VERSION)
+--
+
++
+NOTE: Ensure that the value of `BUILD_ARGS` has the correct syntax as described in link:https://tekton.dev/docs/pipelines/variables/[Variable Substitutions Supported by Tasks and Pipelines].
+
+. Pass the desired build arguments in the PipelineRun `.spec.params`:
+
++
+[source,yaml]
+--
+spec:
+  params:
+  # ...
+  - name: build-args
+    value: ["ARG1=val", "ARG2=val"]  # Add real argument name and value of each build argument
+--