OSDOCS-71-75 add build environment modules

Author: bmcelvee

builds/creating-build-inputs.adoc

@@ -90,3 +90,9 @@ include::modules/builds-custom-strategy.adoc[leveloffset=+2]
 include::modules/builds-using-external-artifacts.adoc[leveloffset=+1]
 
 include::modules/builds-docker-credentials-private-registries.adoc[leveloffset=+1]
+
+include::modules/builds-build-environment.adoc[leveloffset=+1]
+
+include::modules/builds-using-build-fields-as-environment-variables.adoc[leveloffset=+2]
+
+include::modules/builds-using-secrets-as-environment-variables.adoc[leveloffset=+2]

modules/builds-build-environment.adoc

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+
+[id='builds-build-environment-{context}']
+= Build environments
+
+As with pod environment variables, build environment variables can be defined in
+terms of references to other resources or variables using the Downward API.
+There are some exceptions, which are noted.
+
+You can also manage environment variables defined in the `BuildConfig` with the
+`oc set env` command.
+
+[NOTE]
+====
+Referencing container resources using `valueFrom` in build environment variables
+is not supported as the references are resolved before the container is created.
+====

modules/builds-using-build-fields-as-environment-variables.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+
+[id='builds-using-build-fields-as-environments-{context}']
+= Using build fields as environment variables
+
+You can inject information about the build object by setting the `fieldPath`
+environment variable source to the `JsonPath` of the field from which you are
+interested in obtaining the value.
+
+[NOTE]
+====
+Jenkins Pipeline strategy does not support `valueFrom` syntax for environment
+variables.
+====
+
+.Procedure
+
+* Set the `fieldPath` environment variable source to the `JsonPath` of the field
+from which you are interested in obtaining the value:
++
+[source,yaml]
+----
+env:
+  - name: FIELDREF_ENV
+    valueFrom:
+      fieldRef:
+        fieldPath: metadata.name
+----

modules/builds-using-secrets-as-environment-variables.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+
+[id='builds-using-secrets-as-environment-variables-{context}']
+= Using secrets as environment variables
+
+You can make key values from Secrets available as environment variables using
+the `valueFrom` syntax.
+
+.Procedure
+
+* To use a secret as an environment variable, set the `valueFrom` syntax:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: BuildConfig
+metadata:
+  name: secret-example-bc
+spec:
+  strategy:
+    sourceStrategy:
+      env:
+      - name: MYVAL
+        valueFrom:
+          secretKeyRef:
+            key: myval
+            name: mysecret
+----