grim/convey

Add a bunch of updates on how environment variable stacking works and other cleanups

2018-01-07, Gary Kramlich
a005e09151fc
Parents 3005ba6231b7
Children 598a722a4678
Add a bunch of updates on how environment variable stacking works and other cleanups
1 files changed, 58 insertions(+), 12 deletions(-)
  • +58 -12
    REFERENCE.md
    • --- a/REFERENCE.md Sun Jan 07 03:46:40 2018 -0600
    +++ b/REFERENCE.md Sun Jan 07 03:46:56 2018 -0600
    @@ -507,6 +507,56 @@
    - BUILD=development
    - SECRET_TOKEN
    +### Stacking
    +
    +Since there are multiple places where environment variables can be set, they must all be merged together before being passed to a task.
    +
    +Environment variables can be set at the `global-base`, `global`, `global-override`, `plan`, `stage`, `task`, and command line levels. The are merged in that order, with the last one taking precedence over the previous.
    +
    +#### Examples
    +
    +In the following example, when the `env1` task is run, the `FOO` environment variable will be set to `baz`, but when the `env2` task is run, the `FOO` environment variable will be set to bar
    +
    + environment:
    + - FOO=bar
    + tasks:
    + env1:
    + type: docker/run
    + image: alpine:edge
    + environment:
    + - FOO=baz
    + env2:
    + type: docker/run
    + image: alpine:Edge
    + plans:
    + default:
    + stages:
    + - tasks:
    + - env1
    + - env2
    +
    +In the next example, the stage is overriding the global value. So `env1` still has a value of `baz` for the environment variable `FOO`, while `env2` has a value of `qux`.
    +
    + environment:
    + - FOO=bar
    + tasks:
    + env1:
    + type: docker/run
    + image: alpine:edge
    + environment:
    + - FOO=baz
    + env2:
    + type: docker/run
    + image: alpine:Edge
    + plans:
    + default:
    + stages:
    + - environment:
    + - FOO=qux
    + tasks:
    + - env1
    + - env2
    +
    ----
    ## Plans
    @@ -567,6 +617,14 @@
    There is currently no support for nesting meta plans.
    +Meta plans contain a single attribute which is the list of `plans` to run.
    +
    +### Attributes
    +
    +| Name | Required | Description |
    +| ----------- | -------- | ----------- |
    +| plans | Yes | A list of `plans` to run in the order they should be run in. |
    +
    ### Example
    meta-plans:
    @@ -575,15 +633,3 @@
    - plan1
    - plan2
    - plan3
    -
    -----
    -
    -## Meta Plan
    -
    -Meta plans contain a single attribute which is the list of `plans` to run.
    -
    -### Attributes
    -
    -| Name | Required | Description |
    -| ----------- | -------- | ----------- |
    -| plans | Yes | A list of `plans` to run in the order they should be run in. |