Merge branch 'patch-126' into 'master'

Improve CI variables Syntax of env variables section

Closes gitlab-runner#4115

See merge request gitlab-org/gitlab!32922

doc/ci/variables/README.md

@@ -242,13 +242,15 @@ In most cases `bash` or `sh` is used to execute the job script.
 
 To access environment variables, use the syntax for your Runner's [shell](https://docs.gitlab.com/runner/executors/).
 
-| Shell                | Usage           |
-|----------------------|-----------------|
-| bash/sh              | `$variable`     |
-| windows batch        | `%variable%`    |
-| PowerShell           | `$env:variable` |
+| Shell                | Usage                                    |
+|----------------------|------------------------------------------|
+| bash/sh              | `$variable`                              |
+| PowerShell           | `$env:variable` (primary) or `$variable` |
+| Windows Batch        | `%variable%`                             |
 
-To access environment variables in bash, prefix the variable name with (`$`):
+### Bash
+
+To access environment variables in **bash**, prefix the variable name with (`$`):
 
 ```yaml
 job_name:
@@ -256,32 +258,54 @@ job_name:
     - echo $CI_JOB_ID
 ```
 
-To access environment variables in **Windows Batch**, surround the variable
-with (`%`):
+### PowerShell
+
+To access environment variables in a **Windows PowerShell** environment, prefix
+the variable name with (`$env:`). For environment variables set by GitLab CI, including those set by [`variables`](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/ci/yaml/README.md#variables)
+parameter, they can also be accessed by prefixing the variable name with (`$`)
+as of [GitLab Runner 1.0.0](https://gitlab.com/gitlab-org/gitlab-runner/-/commit/abc44bb158008cd3a49c0d8173717c38dadb29ae#47afd7e8f12afdb8f0246262488f24e6dd071a22).
+System set environment variables however must be accessed using (`$env:`).
 
 ```yaml
 job_name:
   script:
-    - echo %CI_JOB_ID%
+    - echo $env:CI_JOB_ID
+    - echo $CI_JOB_ID
+    - echo $env:PATH
 ```
 
-To access environment variables in a **Windows PowerShell** environment, prefix
-the variable name with (`$env:`):
+In [some cases](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4115#note_157692820)
+environment variables may need to be surrounded by quotes to expand properly:
 
 ```yaml
 job_name:
   script:
-    - echo $env:CI_JOB_ID
+    - D:\\qislsf\\apache-ant-1.10.5\\bin\\ant.bat "-DsosposDailyUsr=$env:SOSPOS_DAILY_USR" portal_test
 ```
 
-You can also list all environment variables with the `export` command,
-but be aware that this will also expose the values of all the variables
+### Windows Batch
+
+To access environment variables in **Windows Batch**, surround the variable
+with (`%`):
+
+```yaml
+job_name:
+  script:
+    - echo %CI_JOB_ID%
+```
+
+### List all environment variables
+
+You can also list all environment variables with the `export` command in Bash
+or `dir env:` command in PowerShell.
+Be aware that this will also expose the values of all the variables
 you set, in the job log:
 
 ```yaml
 job_name:
   script:
     - export
+    # - 'dir env:' # use this for PowerShell
 ```
 
 Example values: