feat: add environment tag for global injection (go-vela#235)

* chore: update homepage "learn more" link to tour

* feat: add environment tag for global injection

* fix: update phrasing from user feedback

content/reference/yaml/environment.md

@@ -0,0 +1,18 @@
+---
+title: "Environment"
+linkTitle: "Environment"
+weight: 1
+description: >
+  YAML tags for environment block
+---
+
+The environment tag is intended to be used to inject a global environment configuration into steps, services and secret containers. Control of which container types get the injected environment settings is available via the metadata block.
+
+```yaml
+---
+# This document is displaying using the environment tag with a map syntax.
+# Additionally, you can also use array syntax where the items in
+# they array are of pattern HELLO="Hello, Vela!"
+environment:
+  HELLO: "Hello, Vela!"
+```

content/reference/yaml/metadata.md

@@ -49,3 +49,14 @@ metadata:
   # Enables injecting the default clone process
   clone: true
 ```
+
+#### The `environment:` tag
+
+```yaml
+---
+metadata:
+  # By default, the below is populated into every pipeline with
+  # services, steps, and secrets. But, when the block exists the
+  # configuration specified is used during compile phase.
+  environment: [ steps, services, secrets ]
+```

content/usage/environment.md

@@ -5,7 +5,9 @@ description: >
   Learn about how to leverage the environment within your builds.
 ---
 
-Vela provides the ability to define environment variables scoped to individual steps, services and secrets. Pleas note the environment is design to be unique per container. Vela does inject a variety of default values from build, repo and user information.
+Vela provides the ability to define environment variables scoped to individual steps, services and secrets. Additionally, if you need global environment variables you can set it at the parent and have it injected to all containers.
+
+Please note the environment is designed to be unique per container. Vela does inject a variety of default values from build, repo and user information.
 
 Defaults:
 
@@ -32,21 +34,24 @@ If you do not want the pre-processor to evaluate your expression it must be esca
 
 ```diff
 version: "1"
++ environment:
++   GLOBAL_EXAMPLE: Hello, World Globally!
 services:
   - name: redis
 +   environment:
-+     EXAMPLE: Hello, World!
++     LOCAL_EXAMPLE: Hello, World!
     image: redis:latest
 
 steps:
   - name: check status
     image: redis:latest
 +   environment:
-+     EXAMPLE: Hello, World!
++     LOCAL_EXAMPLE: Hello, World!
     commands:
       # you can use bash commands in-line to set or override variables
       - export EXAMPLE="Hello World From Vela Team"
       - echo ${EXAMPLE}
+      - echo ${GLOBAL_EXAMPLE}
 
 secrets:
   - origin:
@@ -63,3 +68,55 @@ secrets:
           - source: secret/docker
             path: docker
 ```
+
+## Global Usage
+
+By default global injection affects all containers ran within the pipeline. However, if only want some container types to receive the configuration you can limit which types get them by adding the `environment` declaration into the metadata.
+
+{{% alert title="Note:" color="primary" %}}
+Valid values for metadata `environment:` YAML tag are `steps`, `services` and `secrets`.
+{{% /alert %}}
+
+```diff
+version: "1"
++ environment:
++   GLOBAL_EXAMPLE: Hello, World Globally!
+
+metadata:
+  environment: [ steps ]
+
+services:
+  # Global configuration is no longer available in services
+  - name: redis
++   environment:
++     LOCAL_EXAMPLE: Hello, World!
+    image: redis:latest
+
+steps:
+  - name: check status
+    image: redis:latest
++   environment:
++     LOCAL_EXAMPLE: Hello, World!
+    commands:
+      # you can local shell commands in-line to set or override variables
+      - export EXAMPLE="Hello World From Vela Team"
+      - echo ${EXAMPLE}
+      - echo ${GLOBAL_EXAMPLE}
+
+secrets:
+  # Global configuration is no longer available in secrets since "secrets"
+  # was removed as a value in the metadata.environment block.
+  - origin:
+      name: private vault
+      image: target/secret-vault:latest
++     environment:
++       EXAMPLE: Hello, World!
+      secrets: [ vault_token ]
+      parameters:
+        addr: vault.example.com
+        auth_method: token
+        username: octocat
+        items:
+          - source: secret/docker
+            path: docker
+```