Merging latest from internal repo

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:12.20.1-alpine
+FROM node:16-alpine
 LABEL SCM_URL https://github.com/salesforce/cix
 USER root
 

README.md

@@ -1,5 +1,4 @@
-CIX - CI Executor
-======
+# CIX - CI Executor
 
 **[Official Documentation](https://opensource.salesforce.com/cix/)** 👈 Check out our Doc Site
 

docs/development.md

@@ -3,13 +3,17 @@
 ## Set up your local development environment
 - Install required system dependencies
 	- [Install Docker on your workstation](install-docker.md)
-	- Install Node.js v12
-		- Using Brew
+	- Install volta (Warning: remove existing node if facing issues installing volta)
+		- install and link volta
 		```bash
-		brew install node@12
-		brew link node
+		curl https://get.volta.sh | bash
+		export VOLTA_HOME=~/.volta
+		export PATH=$VOLTA_HOME/bin:$PATH
+		```
+		- install correct node version
+		```bash
+		volta install node@16.20.0 (Warning: you might have to get off Cisco Anyconnect VPN for this step. you can reconnect after this step)
 		```
-		- Or download the appropriate package from the [Node.js web site](https://nodejs.org/en/download/).
 	- If you haven't already, [setup](https://confluence.internal.salesforce.com/pages/viewpage.action?spaceKey=NEXUS&title=Nexus+NPM+Repositories) access to the Nexus npm repositories
 - Clone the CIX repo
 	```bash

docs/examples/commands-output.yaml

@@ -0,0 +1,20 @@
+version: 2.1
+pipeline:
+  - step:
+      name: minimal
+      image: alpine:3.9
+      commands-output: minimal
+      commands:
+        - echo "You will only see stdout/stderr (minimal)"
+  - step:
+      name: echo
+      image: alpine:3.9
+      commands-output: echo
+      commands:
+        - echo "This echo command will be echo'd (echo without a timestamp)"
+  - step:
+      name: timestamp
+      image: alpine:3.9
+      commands-output: timestamp
+      commands:
+        - echo "This echo command will be echo'd (echo with a timestamp)"

docs/examples/conditional.yaml

@@ -325,9 +325,32 @@ pipeline:
       when:
         - operator: INCLUDES
           value: $$FOO_INCLUDES # example value FOO_INCLUDES=foo,bar,baz
+          value-default: foo,bar,baz
           other: foo
       commands:
         - echo "yay 14"
+  - step:
+      name: INCLUDESFail
+      image: alpine:3.9
+      when:
+        - operator: INCLUDES
+          value: $$FOO_INCLUDES # example value FOO_INCLUDES=foo,bar,baz
+          value-default: foo,bar,baz
+          other: ''
+      commands:
+        - echo "shouldn't run"
+        - exit 1
+  - step:
+      name: INCLUDESFail_2
+      image: alpine:3.9
+      when:
+        - operator: INCLUDES
+          value: $$FOO_INCLUDES # example value FOO_INCLUDES=foo,bar,baz
+          value-default: foo,bar,baz
+          other: ' '
+      commands:
+        - echo "shouldn't run"
+        - exit 1
   - step:
       name: NOT_INCLUDESPass
       image: alpine:3.9
@@ -378,4 +401,75 @@ pipeline:
           other: foo
       commands:
         - echo "shouldn't run"
-        - exit 1
+        - exit 1
+  - step:
+      name: ANDPass
+      image: alpine:3.9
+      when:
+        - operator: AND
+          conditions:
+          - operator: ENDS_WITH
+            value: $$FOO_ENDS_WITH # example value FOO_ENDS_WITH=foobar
+            value-default: foobar
+            other: bar
+          - operator: EQ
+            value: $$FOO_CONDITION_VALUE
+            value-default: 1
+            other: $$BAR_CONDITION_VALUE
+            other-default: 1
+      commands:
+        - echo "yay 18"
+  - step:
+      name: ANDFail_1
+      image: alpine:3.9
+      when:
+        - operator: AND
+          conditions:
+          - operator: ENDS_WITH
+            value: $$FOO_ENDS_WITH # example value FOO_ENDS_WITH=foobar
+            value-default: foobar
+            other: foo
+          - operator: EQ
+            value: $$FOO_CONDITION_VALUE
+            value-default: 1
+            other: $$BAR_CONDITION_VALUE
+            other-default: 2
+      commands:
+        - echo "shouldn't run"
+        - exit 1
+  - step:
+      name: ANDFail_2
+      image: alpine:3.9
+      when:
+        - operator: AND
+          conditions:
+          - operator: ENDS_WITH
+            value: $$FOO_ENDS_WITH # example value FOO_ENDS_WITH=foobar
+            value-default: foobar
+            other: bar
+          - operator: EQ
+            value: $$FOO_CONDITION_VALUE
+            value-default: 1
+            other: $$BAR_CONDITION_VALUE
+            other-default: 2
+      commands:
+        - echo "shouldn't run"
+        - exit 1
+  - step:
+      name: ANDFail_3
+      image: alpine:3.9
+      when:
+        - operator: AND
+          conditions:
+          - operator: ENDS_WITH
+            value: $$FOO_ENDS_WITH # example value FOO_ENDS_WITH=foobar
+            value-default: foobar
+            other: foo
+          - operator: EQ
+            value: $$FOO_CONDITION_VALUE
+            value-default: 2
+            other: $$BAR_CONDITION_VALUE
+            other-default: 2
+      commands:
+        - echo "shouldn't run"
+        - exit 1

docs/examples/environment-built-ins.yaml

@@ -11,3 +11,17 @@ pipeline:
         - echo $CIX_NETWORK_NAME
         - echo $CIX_CONTAINER_NAME
         - echo $CIX_EXECUTION_ID
+        - echo $CIX_SERVER_PORT
+        - pwd
+        - echo $CIX_WORKDIR
+        - echo $CIX_WORKSPACE
+        - echo $CIX_TEMP
+  - step:
+      name: override-work-dir
+      image: alpine:3.9
+      working-dir: /bin
+      workspace-mount-point: /tmp
+      commands:
+        - pwd
+        - echo $CIX_WORKDIR
+        - echo $CIX_WORKSPACE

docs/examples/environment.yaml

@@ -5,13 +5,18 @@ pipeline:
       image: alpine:3.9
       environment:
         - name: FOO
-          value: $$FOO_FROM_COMMAND # if passed with -e option, $$ literals will be replaced
-          default: foo_default
+          # value passed in via '-e FOO=foo'
+          value: $$FOO
         - name: BAR
-          value: $$BAR_FROM_COMMAND
+          # value passed in via '-e BAR=bar'
+          value: $$BAR
+          # default passed in via '-e BAR_DEFAULT=bar-default'
           default: $$BAR_DEFAULT
-        # not passing these properties will not cause any failures
-        # the environment variables would be the $$ literals during exec, or the default, if specified
+        - name: BAZ
+          # when value is omitted, value == $$BAZ,
+          # passed in via '-e BAZ=baz'
+          default: baz-default
       commands:
         - echo $FOO
         - echo $BAR
+        - echo $BAZ

docs/examples/import/imports.yaml

@@ -5,9 +5,15 @@ imports:
   library:
     src: ./library.yaml
   #
-  # Following is how http(s) based imports can be specified. The token is optional if needed, e.g.,
-  # needed in order to fetch from git.soma
+  # Following is how Git based http(s) imports can be specified. A personal access token is required
+  # with Git, there are two options 1) use the special HTTP_AUTHORIZATION_TOKEN secret 2) specifiy the 
+  # YAML attribute http-authorization-token and feed in any environment variable
   #
+  # (Option 1: HTTP_AUTHORIZATION_TOKEN secret)
+  # library: 
+  #   src: https://github.com/raw/ci/cix/master/docs/examples/import/library.yaml
+  #
+  # (Option 2: Use any other secret with YAML)
   # library:
   #   src: https://github.com/raw/ci/cix/master/docs/examples/import/library.yaml
   #   http_authorization_token: $$CIX_GIT_TOKEN # must be passed via -s

docs/examples/loop.yaml

@@ -1,9 +1,11 @@
 version: 2.1
 pipeline:
   - step:
-      name: loop
-      image: alpine:3.9
+      name: for-each-empty
+      image: alpine:3.9   
+      for-each: $$FOO
+      element-variable: ELEMENT
+      parallel: true
+      commands-output: minimal
       commands:
-        - "[ $((RANDOM % 10)) -ge 8 ] && exit 1 || exit 0" # occasionally fail the command
-        # entire pipeline will fail, if any command in any of the loops fails (unlike retry)
-      loop: $$LOOPS
+        - echo $ELEMENT

docs/examples/phased-exec.yaml

@@ -27,4 +27,4 @@ pipeline:
       name: fifth
       image: alpine:3.9
       commands:
-        - hostname
+        - hostname

docs/examples/secrets.yaml

@@ -5,10 +5,10 @@ pipeline:
       image: alpine:3.9
       environment:
         - name: FOO
-          value: $$SECRET_FOO_FROM_COMMAND
+          value: $$SECRET_FOO
         - name: BAR
-          value: $$SECRET_BAR_FROM_COMMAND
+          value: $$SECRET_BAR
       commands:
         - echo $FOO
         - echo $BAR
-        - echo Multiple secrets such as $FOO, $FOO, and $BAR on the same line should be masked
+        - echo Multiple secrets such as $FOO, $FOO, and $BAR on the same line will be masked

docs/examples/user.yaml

@@ -0,0 +1,21 @@
+version: 2.1
+pipeline:
+  - step:
+      name: set-user
+      image: alpine:3.9
+      user: 12300
+      commands:
+        - id
+  - step:
+      name: set-uid-and-gid
+      image: alpine:3.9
+      user: 12300:12300
+      commands:
+        - id
+  - step:
+      name: set-user-string
+      image: alpine:3.9
+      # 'games' is a user listed in the alpine image's /etc/passwd file
+      user: games
+      commands:
+        - id

docs/getting-started/concepts.md

@@ -10,7 +10,7 @@ Your pipeline definition (YAML) files are also expected to be accessible from un
 
 ## Container Network
 
-In Docker mode, CIX creates a private network for the containers of a pipeline. This allows the containers to communicate
+In Docker mode, CIX creates an ephemeral private network for the containers of a pipeline. This allows the containers to communicate
 freely with each other, while being isolated from other containers on the host.
 
 It also allows for private DNS resolution, so that containers may refer to each other by their simple step names and
@@ -19,6 +19,17 @@ It also allows for private DNS resolution, so that containers may refer to each
 Containers in the same pipeline can also communicate with each other without need to export or specify ports. Containers
 can connect to other concurrent containers on any port.
 
+You can provide your own network or switch to `host` networking by exporting the environment variable `DOCKER_NETWORK` before running CIX. This will skip creating the ephemeral network.
+
+>! For `host` networking, DNS resolution and container communication may not have full feature parity with an ephemeral docker network.
+
+```sh
+DOCKER_NETWORK=host cix exec
+# OR
+docker network create my-network
+DOCKER_NETWORK=my-network cix exec 
+```
+
 These topics are covered in more detail in the [Background Services](tutorials/background) tutorial.
 
 ---