diff --git a/content/actions/using-workflows/workflow-commands-for-github-actions.md b/content/actions/using-workflows/workflow-commands-for-github-actions.md index 34308f8f03..5a6de2d67d 100644 --- a/content/actions/using-workflows/workflow-commands-for-github-actions.md +++ b/content/actions/using-workflows/workflow-commands-for-github-actions.md @@ -59,7 +59,42 @@ Write-Output "::workflow-command parameter1={data},parameter2={data}::{command v ## 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 output, 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`. + +{%- ifversion actions-save-state-set-output-envs %} +For example, instead of using code to create an error annotation, as below: + +```javascript{:copy} +core.error('Missing semicolon', {file: 'app.js', startLine: 1}) +``` + +### Example: Creating an annotation for an error + +You can use the `error` command in your workflow to create the same error annotation: + +{% bash %} + +{% raw %} +```yaml{:copy} + - name: Create annotation for build error + run: echo "::error file=app.js,line=1::Missing semicolon" +``` +{% endraw %} + +{% endbash %} + +{% powershell %} + +{% raw %} +```yaml{:copy} + - name: Create annotation for build error + run: Write-Output "::error file=app.js,line=1::Missing semicolon" +``` +{% endraw %} + +{% endpowershell %} +{%- else %} +For example, instead of using code to set an output, as below: ```javascript{:copy} core.setOutput('SELECTED_COLOR', 'green'); @@ -97,6 +132,8 @@ You can use the `set-output` command in your workflow to set the same value: {% endpowershell %} +{% endif %} + The following table shows which toolkit functions are available within a workflow: | Toolkit function | Equivalent workflow command | @@ -113,14 +150,15 @@ The following table shows which toolkit functions are available within a workflo {%- ifversion actions-job-summaries %} | `core.summary` | Accessible using environment variable `GITHUB_STEP_SUMMARY` | {%- endif %} -| `core.saveState` | `save-state` | +| `core.saveState` | {% ifversion actions-save-state-set-output-envs %}Accessible using environment variable `GITHUB_STATE`{% else %}`save-state`{% endif %} | | `core.setCommandEcho` | `echo` | | `core.setFailed` | Used as a shortcut for `::error` and `exit 1` | -| `core.setOutput` | `set-output` | +| `core.setOutput` | {% ifversion actions-save-state-set-output-envs %}Accessible using environment variable `GITHUB_OUTPUT`{% else %}`set-output`{% endif %} | | `core.setSecret` | `add-mask` | | `core.startGroup` | `group` | | `core.warning` | `warning` | +{% ifversion actions-save-state-set-output-envs %}{% else %} ## Setting an output parameter Sets an action's output parameter. @@ -148,6 +186,7 @@ Write-Output "::set-output name=action_fruit::strawberry" ``` {% endpowershell %} +{% endif %} ## Setting a debug message @@ -504,17 +543,31 @@ Only the second `set-output` and `echo` workflow commands are included in the lo ## Sending values to the pre and post actions -You can use the `save-state` command to create environment variables for sharing with your workflow's `pre:` or `post:` actions. For example, you can create a file with the `pre:` action, pass the file location to the `main:` action, and then use the `post:` action to delete the file. Alternatively, you could create a file with the `main:` action, pass the file location to the `post:` action, and also use the `post:` action to delete the file. +{% ifversion actions-save-state-set-output-envs %}You can create environment variables for sharing with your workflow's `pre:` or `post:` actions by writing to the file located at `GITHUB_STATE`{% else %}You can use the `save-state` command to create environment variables for sharing with your workflow's `pre:` or `post:` actions{% endif %}. For example, you can create a file with the `pre:` action, pass the file location to the `main:` action, and then use the `post:` action to delete the file. Alternatively, you could create a file with the `main:` action, pass the file location to the `post:` action, and also use the `post:` action to delete the file. -If you have multiple `pre:` or `post:` actions, you can only access the saved value in the action where `save-state` was used. For more information on the `post:` action, see "[Metadata syntax for {% data variables.product.prodname_actions %}](/actions/creating-actions/metadata-syntax-for-github-actions#runspost)." +If you have multiple `pre:` or `post:` actions, you can only access the saved value in the action where {% ifversion actions-save-state-set-output-envs %}it was written to `GITHUB_STATE`{% else %}`save-state` was used{% endif %}. For more information on the `post:` action, see "[Metadata syntax for {% data variables.product.prodname_actions %}](/actions/creating-actions/metadata-syntax-for-github-actions#runspost)." -The `save-state` command can only be run within an action, and is not available to YAML files. The saved value is stored as an environment value with the `STATE_` prefix. +{% ifversion actions-save-state-set-output-envs %}The `GITHUB_STATE` file is only available within an action{% else %}The `save-state` command can only be run within an action, and is not available to YAML files{% endif %}. The saved value is stored as an environment value with the `STATE_` prefix. +{% ifversion actions-save-state-set-output-envs %} +This example uses JavaScript to write to the `GITHUB_STATE` file. The resulting environment variable is named `STATE_processID` with the value of `12345`: + +```javascript{:copy} +import * as fs from 'fs' +import * as os from 'os' + +fs.appendFileSync(process.env.GITHUB_STATE, `processID=12345${os.EOL}`, { + encoding: 'utf8' +}) +``` + +{% else %} This example uses JavaScript to run the `save-state` command. The resulting environment variable is named `STATE_processID` with the value of `12345`: ```javascript{:copy} console.log('::save-state name=processID::12345') ``` +{% endif %} The `STATE_processID` variable is then exclusively available to the cleanup script running under the `main` action. This example runs in `main` and uses JavaScript to display the value assigned to the `STATE_processID` environment variable: @@ -626,7 +679,7 @@ steps: ### Multiline strings -For multiline strings, you may use a delimiter with the following syntax. +For multiline strings, you may use a delimiter with the following syntax. ```{:copy} {name}<<{delimiter} @@ -673,6 +726,62 @@ steps: {% endpowershell %} +{% ifversion actions-save-state-set-output-envs %} +## Setting an output parameter + +Sets a step's output parameter. Note that the step will need an `id` to be defined to later retrieve the output value. + +{% bash %} + +```bash{:copy} +echo "{name}={value}" >> $GITHUB_OUTPUT +``` +{% endbash %} + +{% powershell %} + +```pwsh{:copy} +"{name}=value" >> $env:GITHUB_OUTPUT +``` + +{% endpowershell %} + +### Example + +{% bash %} + +This example demonstrates how to set the `SELECTED_COLOR` output parameter and later retrieve it: + +{% raw %} +```yaml{:copy} + - name: Set color + id: random-color-generator + run: echo "SELECTED_COLOR=green" >> $GITHUB_OUTPUT + - name: Get color + run: echo "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}" +``` +{% endraw %} + +{% endbash %} + +{% powershell %} + +{% raw %} +This example demonstrates how to set the `SELECTED_COLOR` output parameter and later retrieve it: + +```yaml{:copy} + - name: Set color + id: random-color-generator + run: | + "SELECTED_COLOR=green" >> $env:GITHUB_OUTPUT + - name: Get color + run: Write-Output "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}" +``` +{% endraw %} + +{% endpowershell %} +{% endif %} + {% ifversion actions-job-summaries %} ## Adding a job summary diff --git a/data/features/actions-save-state-set-output-envs.yml b/data/features/actions-save-state-set-output-envs.yml new file mode 100644 index 0000000000..ffadf60ce9 --- /dev/null +++ b/data/features/actions-save-state-set-output-envs.yml @@ -0,0 +1,7 @@ +# Reference: #8273 +# New Actions `save-state`` and `set-output` env file commands, which deprecates their stdout counterparts. +versions: + fpt: '*' + ghec: '*' + ghes: '>= 3.8' + ghae: '>= 3.8'