jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-22 19:34:15 -05:00
Code Issues Projects Releases Wiki Activity

WIP: Adds the raw powershell equivalents.

Browse Source
This commit is contained in:
Jesse Houwing
2022-02-11 16:52:34 +01:00
parent 141e1c3373
commit 515fcfe0c0
1 changed files with 137 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
content/actions/using-workflows/workflow-commands-for-github-actions.md
View File

@@ -26,10 +26,14 @@ Actions can communicate with the runner machine to set environment variables, ou
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)
``` bash
```bash
echo "::workflow-command parameter1={data},parameter2={data}::{command value}"
```
```pwsh
Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}"
```
{% note %}
**Note:** Workflow command and parameter names are not case-sensitive.
@@ -62,6 +66,16 @@ You can use the `set-output` command in your workflow to set the same value:
```
{% endraw %}
{% raw %}
``` yaml
- name: Set selected color
run: Write-Output "::set-output name=SELECTED_COLOR::green"
id: random-color-generator
- name: Get color
run: Write-Output "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"
```
{% endraw %}
The following table shows which toolkit functions are available within a workflow:
| Toolkit function | Equivalent workflow command |
@@ -95,10 +109,14 @@ Optionally, you can also declare output parameters in an action's metadata file.
### Example
``` bash
```bash
echo "::set-output name=action_fruit::strawberry"
```
```pwsh
Write-Output "::set-output name=action_fruit::strawberry"
```
## Setting a debug message
```
@@ -109,10 +127,14 @@ Prints a debug message to the log. You must create a secret named `ACTIONS_STEP_
### Example
``` bash
```bash
echo "::debug::Set the Octocat variable"
```
```pwsh
Write-Output "::debug::Set the Octocat variable"
```
{% ifversion fpt or ghes > 3.2 or ghae-issue-4929 or ghec %}
## Setting a notice message
@@ -127,10 +149,14 @@ Creates a notice message and prints the message to the log. {% data reusables.ac
### Example
``` bash
```bash
echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
```
```pwsh
Write-Output "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
```
{% endif %}
## Setting a warning message
@@ -145,10 +171,14 @@ Creates a warning message and prints the message to the log. {% data reusables.a
### Example
``` bash
```bash
echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
```
```pwsh
Write-Output "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
```
## Setting an error message
```
@@ -161,10 +191,14 @@ Creates an error message and prints the message to the log. {% data reusables.ac
### Example
``` bash
```bash
echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
```
```pwsh
Write-Output "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
```
## Grouping log lines
```
@@ -182,6 +216,12 @@ echo "Inside group"
echo "::endgroup::"
```
```pwsh
echo "::group::My title"
echo "Inside group"
echo "::endgroup::"
```
![Foldable group in workflow run log](/assets/images/actions-log-group.png)
## Masking a value in log
@@ -200,6 +240,10 @@ When you print `"Mona The Octocat"` in the log, you'll see `"***"`.
echo "::add-mask::Mona The Octocat"
```
```bash
Write-Output "::add-mask::Mona The Octocat"
```
### Example masking an environment variable
When you print the variable `MY_NAME` or the value `"Mona The Octocat"` in the log, you'll see `"***"` instead of `"Mona The Octocat"`.
@@ -209,6 +253,11 @@ MY_NAME="Mona The Octocat"
echo "::add-mask::$MY_NAME"
```
```pwsh
$env:MY_NAME="Mona The Octocat"
Write-Output "::add-mask::$env:MY_NAME"
```
## Stopping and starting workflow commands
`::stop-commands::{endtoken}`
@@ -245,6 +294,22 @@ jobs:
echo '::warning:: this is a warning again'
```
```yaml
jobs:
workflow-command-job:
runs-on: ubuntu-latest
steps:
- name: disable workflow commands
run: |
Write-Output '::warning:: this is a warning'
# PowerShell lacks a simple function to create a hash from a string unfortunately.
$stopMarker = New-Guid
Write-Output "::stop-commands::$stopMarker"
Write-Output '::warning:: this will NOT be a warning'
Write-Output "::$stopMarker::"
Write-Output '::warning:: this is a warning again'
```
{% endraw %}
## Echoing command outputs
@@ -278,6 +343,20 @@ jobs:
echo '::set-output name=action_echo::disabled'
```
```yaml
jobs:
workflow-command-job:
runs-on: ubuntu-latest
steps:
- name: toggle workflow command echoing
run: |
write-output "::set-output name=action_echo::disabled"
write-output "::echo::on"
write-output "::set-output name=action_echo::enabled"
write-output "::echo::off"
write-output "::set-output name=action_echo::disabled"
```
The step above prints the following lines to the log:
```
@@ -323,11 +402,20 @@ jobs:
uses: windows-2019
steps:
- shell: powershell
run: echo "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
run: "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
```
Alternatively, you can use PowerShell Core (`shell: pwsh`), which defaults to UTF-8.
```yaml
jobs:
legacy-powershell-example:
uses: windows-2019
steps:
- shell: pwsh
run: "mypath" >> $env:GITHUB_PATH
```
{% endwarning %}
## Setting an environment variable
@@ -336,6 +424,14 @@ Alternatively, you can use PowerShell Core (`shell: pwsh`), which defaults to UT
echo "{environment_variable_name}={value}" >> $GITHUB_ENV
```
``` pwsh
"{environment_variable_name}={value}" >> $env:GITHUB_ENV
```
``` powershell
"{environment_variable_name}={value}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
```
You can make an environment variable available to any subsequent steps in a workflow job by defining or updating the environment variable and writing this to the `GITHUB_ENV` environment file. The step that creates or updates the environment variable does not have access to the new value, but all subsequent steps in a job will have access. The names of environment variables are case-sensitive, and you can include punctuation. For more information, see "[Environment variables](/actions/learn-github-actions/environment-variables)."
### Example
@@ -354,6 +450,20 @@ steps:
```
{% endraw %}
{% raw %}
```
steps:
- name: Set the value
id: step_one
run: |
"action_state=yellow" >> $env:GITHUB_ENV
- name: Use the value
id: step_two
run: |
Write-Output "${{ env.action_state }}" # This will output 'yellow'
```
{% endraw %}
### Multiline strings
For multiline strings, you may use a delimiter with the following syntax.
@@ -377,12 +487,27 @@ steps:
echo 'EOF' >> $GITHUB_ENV
```
```yaml
steps:
- name: Set the value
id: step_one
run: |
"JSON_RESPONSE<<EOF" >> $env:GITHUB_ENV
(Invoke-WebRequest -Uri "google.com").Content >> $env:GITHUB_ENV
"EOF" >> $env:GITHUB_ENV
shell: pwsh
```
## Adding a system path
``` bash
echo "{path}" >> $GITHUB_PATH
```
``` pwsh
"{path}" >> $env:GITHUB_PATH
```
Prepends a directory to the system `PATH` variable and automatically makes it available to all subsequent actions in the current job; the currently running action cannot access the updated path variable. To see the currently defined paths for your job, you can use `echo "$PATH"` in a step or an action.
### Example
@@ -392,3 +517,8 @@ This example demonstrates how to add the user `$HOME/.local/bin` directory to `P
``` bash
echo "$HOME/.local/bin" >> $GITHUB_PATH
```
This example demonstrates how to add the user `$env:HOMEPATH/.local/bin` directory to `PATH`:
``` pwsh
"$env:HOMEPATH/.local/bin" >> $env:GITHUB_PATH
```