From 677a53319f8aa8c007bd025dd0327a1915ed29a9 Mon Sep 17 00:00:00 2001 From: Thomas Boop <52323235+thboop@users.noreply.github.com> Date: Wed, 30 Sep 2020 15:41:06 -0400 Subject: [PATCH] Add Environment File Docs (#15777) --- .../metadata-syntax-for-github-actions.md | 2 +- .../reference/environment-variables.md | 2 +- .../workflow-commands-for-github-actions.md | 88 +++++++++++++++++-- 3 files changed, 83 insertions(+), 9 deletions(-) diff --git a/content/actions/creating-actions/metadata-syntax-for-github-actions.md b/content/actions/creating-actions/metadata-syntax-for-github-actions.md index 2bc2b2b1c064..3e5a815817c5 100644 --- a/content/actions/creating-actions/metadata-syntax-for-github-actions.md +++ b/content/actions/creating-actions/metadata-syntax-for-github-actions.md @@ -244,7 +244,7 @@ For more information, see "[`github context`](/actions/reference/context-and-exp ##### **`runs.steps.env`** -**Optional** Sets a `map` of environment variables for only that step. If you want to modify the environment variable stored in the workflow, use `echo "::set-env name={name}::{value}"` in a composite run step. +**Optional** Sets a `map` of environment variables for only that step. If you want to modify the environment variable stored in the workflow, use {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %}`echo "{name}={value}" >> $GITHUB_ENV`{% else %}`echo "::set-env name={name}::{value}"`{% endif %} in a composite run step. ##### **`runs.steps.working-directory`** diff --git a/content/actions/reference/environment-variables.md b/content/actions/reference/environment-variables.md index 914e330321f0..4ace66924b45 100644 --- a/content/actions/reference/environment-variables.md +++ b/content/actions/reference/environment-variables.md @@ -30,7 +30,7 @@ steps: Last_Name: Octocat ``` -You can also use the `set-env` workflow command to set an environment variable that the following steps in a workflow can use. The `set-env` command can be used directly by an action or as a shell command in a workflow file using the `run` keyword. For more information, see "[Workflow commands for {% data variables.product.prodname_actions %}](/actions/reference/workflow-commands-for-github-actions/#setting-an-environment-variable)." +You can also use the {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %}`GITHUB_ENV` environment file{% else %} `set-env` workflow command{% endif %} to set an environment variable that the following steps in a workflow can use. The {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %}environment file{% else %} `set-env` command{% endif %} can be used directly by an action or as a shell command in a workflow file using the `run` keyword. For more information, see "[Workflow commands for {% data variables.product.prodname_actions %}](/actions/reference/workflow-commands-for-github-actions/#setting-an-environment-variable)." ### Default environment variables diff --git a/content/actions/reference/workflow-commands-for-github-actions.md b/content/actions/reference/workflow-commands-for-github-actions.md index eef88359b315..9b738bab6ddb 100644 --- a/content/actions/reference/workflow-commands-for-github-actions.md +++ b/content/actions/reference/workflow-commands-for-github-actions.md @@ -21,7 +21,11 @@ versions: Actions can communicate with the runner machine to set environment variables, output values used by other actions, add debug messages to the output logs, and other tasks. +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} +Most workflow commands use the `echo` command in a specific format, while others are invoked by writing to a file. For more information, see ["Environment files".](#environment-files) +{% else %} Workflow commands use the `echo` command in a specific format. +{% endif %} ``` bash echo "::workflow-command parameter1={data},parameter2={data}::{command value}" @@ -41,30 +45,31 @@ echo "::workflow-command parameter1={data},parameter2={data}::{command value}" ### Using workflow commands to access toolkit functions -The [actions/toolkit](https://github.com/actions/toolkit) includes a number of functions that can be executed as workflow commands. Use the `::` syntax to run the workflow commands within your YAML file; these commands are then sent to the runner over `stdout`. For example, instead of using code to set an environment variable, as below: +The [actions/toolkit](https://github.com/actions/toolkit) includes a number of functions that can be executed as workflow commands. Use the `::` syntax to run the workflow commands within your YAML file; these commands are then sent to the runner over `stdout`. For example, instead of using code to set an output, as below: ```javascript -core.exportVariable('SELECTED_COLOR', 'green'); +core.setOutput('SELECTED_COLOR', 'green'); ``` -You can use the `set-env` command in your workflow to set the same value: +You can use the `set-output` command in your workflow to set the same value: ``` yaml - name: Set selected color - run: echo '::set-env name=SELECTED_COLOR::green' + run: echo '::set-output name=SELECTED_COLOR::green' + id: random-color-generator - name: Get color - run: echo 'The selected color is' $SELECTED_COLOR + run: echo 'The selected color is' ${steps.random-color-generator.outputs.SELECTED_COLOR} ``` The following table shows which toolkit functions are available within a workflow: | Toolkit function| Equivalent workflow command| | ------------- | ------------- | -| `core.addPath` | `add-path` | +| `core.addPath` | {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %}Accessible using environment file `GITHUB_PATH`{% else %} `add-path` {% endif %} | | `core.debug` | `debug` | | `core.error` | `error` | | `core.endGroup` | `endgroup` | -| `core.exportVariable` | `set-env` | +| `core.exportVariable` | {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %}Accessible using environment file `GITHUB_ENV`{% else %} `set-env` {% endif %} | | `core.getInput` | Accessible using environment variable `INPUT_{NAME}` | | `core.getState` | Accessible using environment variable `STATE_{NAME}` | | `core.isDebug` | Accessible using environment variable `RUNNER_DEBUG` | @@ -75,6 +80,7 @@ The following table shows which toolkit functions are available within a workflo | `core.startGroup` | `group` | | `core.warning` | `warning file` | +{% if currentVersion ver_lt "enterprise-server@2.23" %} ### Setting an environment variable `::set-env name={name}::{value}` @@ -86,6 +92,7 @@ Creates or updates an environment variable for any actions running next in a job ``` bash echo "::set-env name=action_state::yellow" ``` +{% endif %} ### Setting an output parameter @@ -101,6 +108,7 @@ Optionally, you can also declare output parameters in an action's metadata file. echo "::set-output name=action_fruit::strawberry" ``` +{% if currentVersion ver_lt "enterprise-server@2.23" %} ### Adding a system path `::add-path::{path}` @@ -112,6 +120,7 @@ Prepends a directory to the system `PATH` variable for all subsequent actions in ``` bash echo "::add-path::/path/to/dir" ``` +{% endif %} ### Setting a debug message @@ -213,3 +222,68 @@ The `STATE_processID` variable is then exclusively available to the cleanup scri ``` javascript console.log("The running PID from the main action is: " + process.env.STATE_processID); ``` + +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} +## Environment Files + +During the execution of a workflow, the runner generates temporary files that can be used to perform certain actions. The path to these files are exposed via environment variables. You will need to use UTF-8 encoding when writing to these files to ensure proper processing of the commands. Multiple commands can be written to the same file, separated by newlines. + +{% warning %} + +**Warning:** Powershell does not use UTF-8 by default. Make sure you write files using the correct encoding. For example, you need to set UTF-8 encoding when you set the path: + +``` +steps: + - run: echo "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 +``` + +{% endwarning %} + +### Setting an environment variable + +`echo "{name}={value}" >> $GITHUB_ENV` + +Creates or updates an environment variable for any actions running next in a job. The action that creates or updates the environment variable does not have access to the new value, but all subsequent actions in a job will have access. Environment variables are case-sensitive and you can include punctuation. + +#### Example + +```bash +echo "action_state=yellow" >> $GITHUB_ENV +``` + +Running `$action_state` in a future step will now return `yellow` + +#### Multline strings +For multiline strings, you may use a delimeter with the following syntax. + +``` +{name}<<{delimeter} +{value} +{delimeter} +``` + +#### Example +In this example, we use `EOF` as a delimiter and set the `JSON_RESPONSE` environment variable to the value of the curl response. +``` +steps: + - name: Set the value + id: step_one + run: | + echo 'JSON_RESPONSE<> $GITHUB_ENV + curl https://httpbin.org/json >> $GITHUB_ENV + echo 'EOF' >> $GITHUB_ENV +``` + + +### Adding a system path + +`echo "{path}" >> $GITHUB_PATH` + +Prepends a directory to the system `PATH` variable for all subsequent actions in the current job. The currently running action cannot access the new path variable. + +#### Example + +``` bash +echo "/path/to/dir" >> $GITHUB_PATH +``` +{% endif %}