SHIP-0004: Build Environment Variables

content/en/docs/api/build.md

@@ -24,6 +24,7 @@ A `Build` resource allows the user to define:
 - builder
 - dockerfile
 - output
+- envs
 
 A `Build` is available within a namespace.
 
@@ -54,6 +55,8 @@ In order to prevent users from triggering `BuildRuns` (_execution of a Build_) t
 | MultipleSecretRefNotFound | More than one secret is missing. At the moment, only three paths on a Build can specify a secret. |
 | RuntimePathsCanNotBeEmpty | The Runtime feature is used, but the runtime path was not defined. This is mandatory. |
 | RemoteRepositoryUnreachable | The defined `spec.source.url` was not found. This validation only take place for http/https protocols. |
+| SpecEnvNameCanNotBeBlank | Indicates that the name for a user provided environment variable is blank. |
+| SpecEnvValueCanNotBeBlank | Indicates that the value for a user provided environment variable is blank. |
 
 ## Configuring a Build
 
@@ -75,6 +78,7 @@ The `Build` definition supports the following fields:
   - `spec.sources` - [Sources](#Sources) describes a slice of artifacts that will be imported into project context, before the actual build process starts.
   - `spec.runtime` - Runtime-Image settings, to be used for a multi-stage build. ⚠️ Deprecated
   - `spec.timeout` - Defines a custom timeout. The value needs to be parsable by [ParseDuration](https://golang.org/pkg/time/#ParseDuration), for example `5m`. The default is ten minutes. The value can be overwritten in the `BuildRun`.
+  - `spec.env` - Specifies additional environment variables that should be passed to the build container.
   - `metadata.annotations[build.shipwright.io/build-run-deletion]` - Defines if delete all related BuildRuns when deleting the Build. The default is `false`.
 
 ### Defining the Source
@@ -144,6 +148,24 @@ spec:
     contextDir: docker-build
 ```
 
+Example of a `Build` that specifies environment variables:
+
+```yaml
+apiVersion: shipwright.io/v1alpha1
+kind: Build
+metadata:
+  name: buildah-golang-build
+spec:
+  source:
+    url: https://github.com/shipwright-io/sample-go
+    contextDir: docker-build
+  env:
+    - name: EXAMPLE_VAR_1
+      value: "example-value-1"
+    - name: EXAMPLE_VAR_2
+      value: "example-value-2"
+```
+
 ### Defining the Strategy
 
 A `Build` resource can specify the `BuildStrategy` to use, these are:

content/en/docs/api/buildrun.md

@@ -55,6 +55,7 @@ The `BuildRun` definition supports the following fields:
   - `spec.timeout` - Defines a custom timeout. The value needs to be parsable by [ParseDuration](https://golang.org/pkg/time/#ParseDuration), for example `5m`. The value overwrites the value that is defined in the `Build`.
   - `spec.output.image` - Refers to a custom location where the generated image would be pushed. The value will overwrite the `output.image` value which is defined in `Build`. ( Note: other properties of the output, for example, the credentials cannot be specified in the buildRun spec. )
   - `spec.output.credentials.name` - Reference an existing secret to get access to the container registry. This secret will be added to the service account along with the ones requested by the `Build`.
+  - `spec.env` - Specifies additional environment variables that should be passed to the build container. Overrides any environment variables that are specified in the `Build` resource.
 
 ### Defining the BuildRef
 
@@ -86,6 +87,25 @@ spec:
     name: pipeline
 ```
 
+### Specifying Environment Variables
+
+A `BuildRun` resource can reference a `Build` resource, that indicates what image to build. For example:
+
+```yaml
+apiVersion: shipwright.io/v1alpha1
+kind: BuildRun
+metadata:
+  name: buildpack-nodejs-buildrun-namespaced
+spec:
+  buildRef:
+    name: buildpack-nodejs-build-namespaced
+  env:
+    - name: EXAMPLE_VAR_1
+      value: "example-value-1"
+    - name: EXAMPLE_VAR_2
+      value: "example-value-2"
+```
+
 You can also use set the `spec.serviceAccount.generate` path to `true`. This will generate the service account during runtime for you.
 
 _**Note**_: When the SA is not defined, the `BuildRun` will default to the `default` SA in the namespace.