docs(examples): add example for needs.environment pipeline feature

The example can be used as test to ensure:
- the environment is injected correctly to build and test parent
pipelines
- in case of existing environment variables the pipeline-level environment
field wins over needs.environment.

Signed-off-by: Massimiliano Giovagnoli <massimiliano.giovagnoli@chainguard.dev>

Author: maxgio92

examples/needs-environment.yaml

@@ -0,0 +1,87 @@
+# SPDX-FileCopyrightText: 2022 Chainguard, Inc
+# SPDX-License-Identifier: Apache-2.0
+#
+# This is a sample configuration file to demonstrate how to use the
+# pipeline needs.environment feature for build and test pipelines,
+# to inject transparently environment variables to the parent pipeline.
+#
+# For more information about melange's built-in golang support check out:
+# https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-PROCESS.md
+#
+package:
+  name: example
+  version: 0.1.0
+  epoch: 0
+
+environment:
+  contents:
+    packages:
+      - busybox
+      - ca-certificates-bundle
+    keyring:
+      - https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
+    repositories:
+      - https://packages.wolfi.dev/os
+
+pipeline:
+  - name: Expect an environment.
+    environment:
+      FOO: "foo"
+    runs: |
+      set -u
+      echo "FOO: ${FOO}"
+      if [[ "${FOO}" != "foo" ]]; then
+        echo "Expected FOO=foo, got FOO=${FOO}"
+        exit 1
+      fi
+
+  - name: Expect an environment.
+    runs: |
+      set -u
+      echo "BAZ: ${BAZ}"
+      if [[ "${BAZ}" != "baz" ]]; then
+        echo "Expected BAZ=baz, got BAZ=${FOO}"
+        exit 1
+      fi
+
+  - name: Inject an environment transparently to the parent pipeline.
+    needs:
+      environment:
+        FOO: "bar"
+        BAZ: "baz"
+
+test:
+  environment:
+    contents:
+      packages:
+        - busybox
+      keyring:
+        - https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
+        - local-melange.rsa.pub
+      repositories:
+        - https://packages.wolfi.dev/os
+        - packages
+  pipeline:
+    - name: Expect an environment.
+      environment:
+        FOO: "foo"
+      runs: |
+        set -u
+        echo "FOO: ${FOO}"
+        if [[ "${FOO}" != "foo" ]]; then
+          echo "Expected FOO=foo, got FOO=${FOO}"
+          exit 1
+        fi
+    - name: Expect an environment.
+      runs: |
+        set -u
+        echo "BAZ: ${BAZ}"
+        if [[ "${BAZ}" != "baz" ]]; then
+          echo "Expected BAZ=baz, got BAZ=${FOO}"
+          exit 1
+        fi
+    - name: Inject an environment transparently to the parent pipeline.
+      needs:
+        environment:
+          FOO: "bar"
+          BAZ: "baz"