Document set-output and save-state environment file commands (#31196)

Co-authored-by: Lucas Costi <lucascosti@users.noreply.github.com>

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

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'