diff --git a/components/article/ToolPicker.tsx b/components/article/ToolPicker.tsx index 2f05ef820d..b28b6adfe4 100644 --- a/components/article/ToolPicker.tsx +++ b/components/article/ToolPicker.tsx @@ -20,6 +20,8 @@ const supportedTools = [ 'vscode', 'importer_cli', 'graphql', + 'powershell', + 'bash', ] const toolTitles = { webui: 'Web browser', @@ -30,6 +32,8 @@ const toolTitles = { vscode: 'Visual Studio Code', importer_cli: 'GitHub Enterprise Importer CLI', graphql: 'GraphQL API', + powershell: 'PowerShell', + bash: 'Bash', } as Record // Imperatively modify article content to show only the selected tool diff --git a/content/README.md b/content/README.md index 1f37f95462..de6ce8ba17 100644 --- a/content/README.md +++ b/content/README.md @@ -228,7 +228,7 @@ defaultPlatform: linux ### `defaultTool` - Purpose: Override the initial tool selection for a page, where tool refers to the application the reader is using to work with GitHub (such as GitHub.com's web UI, the GitHub CLI, or GitHub Desktop) or the GitHub APIs (such as cURL or the GitHub CLI). For more information about the tool selector, see [Markup reference for GitHub Docs](../contributing/content-markup-reference.md#tool-tags). If this frontmatter is omitted, then the tool-specific content matching the GitHub web UI is shown by default. If a user has indicated a tool preference (by clicking on a tool tab), then the user's preference will be applied instead of the default value. -- Type: `String`, one of: `webui`, `cli`, `desktop`, `curl`, `codespaces`, `vscode`, `importer_cli`, `graphql`. +- Type: `String`, one of: `webui`, `cli`, `desktop`, `curl`, `codespaces`, `vscode`, `importer_cli`, `graphql`, `powershell`, `bash`. - Optional. ```yaml 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 d9c7e21aa1..33f4bbdedd 100644 --- a/content/actions/using-workflows/workflow-commands-for-github-actions.md +++ b/content/actions/using-workflows/workflow-commands-for-github-actions.md @@ -2,6 +2,7 @@ title: Workflow commands for GitHub Actions shortTitle: Workflow commands intro: You can use workflow commands when running shell commands in a workflow or in an action's code. +defaultTool: bash redirect_from: - /articles/development-tools-for-github-actions - /github/automating-your-workflow-with-github-actions/development-tools-for-github-actions @@ -26,10 +27,24 @@ 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 +### Example + +{% bash %} + +```bash{:copy} echo "::workflow-command parameter1={data},parameter2={data}::{command value}" ``` +{% endbash %} + +{% powershell %} + +```pwsh{:copy} +Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}" +``` + +{% endpowershell %} + {% note %} **Note:** Workflow command and parameter names are not case-sensitive. @@ -46,14 +61,18 @@ echo "::workflow-command parameter1={data},parameter2={data}::{command value}" 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 +```javascript{:copy} core.setOutput('SELECTED_COLOR', 'green'); ``` +### Example: Setting a value + You can use the `set-output` command in your workflow to set the same value: +{% bash %} + {% raw %} -``` yaml +```yaml{:copy} - name: Set selected color run: echo '::set-output name=SELECTED_COLOR::green' id: random-color-generator @@ -62,6 +81,22 @@ You can use the `set-output` command in your workflow to set the same value: ``` {% endraw %} +{% endbash %} + +{% powershell %} + +{% raw %} +```yaml{:copy} + - 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 %} + +{% endpowershell %} + The following table shows which toolkit functions are available within a workflow: | Toolkit function | Equivalent workflow command | @@ -85,186 +120,336 @@ The following table shows which toolkit functions are available within a workflo ## Setting an output parameter -``` +Sets an action's output parameter. + +```{:copy} ::set-output name={name}::{value} ``` -Sets an action's output parameter. - Optionally, you can also declare output parameters in an action's metadata file. For more information, see "[Metadata syntax for {% data variables.product.prodname_actions %}](/articles/metadata-syntax-for-github-actions#outputs-for-docker-container-and-javascript-actions)." -### Example +### Example: Setting an output parameter -``` bash +{% bash %} + +```bash{:copy} echo "::set-output name=action_fruit::strawberry" ``` -## Setting a debug message +{% endbash %} +{% powershell %} + +```pwsh{:copy} +Write-Output "::set-output name=action_fruit::strawberry" ``` -::debug::{message} -``` + +{% endpowershell %} + +## Setting a debug message Prints a debug message to the log. You must create a secret named `ACTIONS_STEP_DEBUG` with the value `true` to see the debug messages set by this command in the log. For more information, see "[Enabling debug logging](/actions/managing-workflow-runs/enabling-debug-logging)." -### Example +```{:copy} +::debug::{message} +``` -``` bash +### Example: Setting a debug message + +{% bash %} + +```bash{:copy} echo "::debug::Set the Octocat variable" ``` +{% endbash %} + +{% powershell %} + +```pwsh{:copy} +Write-Output "::debug::Set the Octocat variable" +``` + +{% endpowershell %} + {% ifversion fpt or ghes > 3.2 or ghae-issue-4929 or ghec %} ## Setting a notice message -``` +Creates a notice message and prints the message to the log. {% data reusables.actions.message-annotation-explanation %} + +```{:copy} ::notice file={name},line={line},endLine={endLine},title={title}::{message} ``` -Creates a notice message and prints the message to the log. {% data reusables.actions.message-annotation-explanation %} - {% data reusables.actions.message-parameters %} -### Example +### Example: Setting a notice message -``` bash +{% bash %} + +```bash{:copy} echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon" ``` +{% endbash %} + +{% powershell %} + +```pwsh{:copy} +Write-Output "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon" +``` + +{% endpowershell %} {% endif %} ## Setting a warning message -``` +Creates a warning message and prints the message to the log. {% data reusables.actions.message-annotation-explanation %} + +```{:copy} ::warning file={name},line={line},endLine={endLine},title={title}::{message} ``` -Creates a warning message and prints the message to the log. {% data reusables.actions.message-annotation-explanation %} - {% data reusables.actions.message-parameters %} -### Example +### Example: Setting a warning message -``` bash +{% bash %} + +```bash{:copy} echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon" ``` +{% endbash %} + +{% powershell %} + +```pwsh{:copy} +Write-Output "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon" +``` + +{% endpowershell %} ## Setting an error message -``` +Creates an error message and prints the message to the log. {% data reusables.actions.message-annotation-explanation %} + +```{:copy} ::error file={name},line={line},endLine={endLine},title={title}::{message} ``` -Creates an error message and prints the message to the log. {% data reusables.actions.message-annotation-explanation %} - {% data reusables.actions.message-parameters %} -### Example +### Example: Setting an error message -``` bash +{% bash %} + +```bash{:copy} echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon" ``` +{% endbash %} + +{% powershell %} + +```pwsh{:copy} +Write-Output "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon" +``` + +{% endpowershell %} ## Grouping log lines -``` +Creates an expandable group in the log. To create a group, use the `group` command and specify a `title`. Anything you print to the log between the `group` and `endgroup` commands is nested inside an expandable entry in the log. + +```{:copy} ::group::{title} ::endgroup:: ``` -Creates an expandable group in the log. To create a group, use the `group` command and specify a `title`. Anything you print to the log between the `group` and `endgroup` commands is nested inside an expandable entry in the log. +### Example: Grouping log lines -### Example +{% bash %} -```bash -echo "::group::My title" -echo "Inside group" -echo "::endgroup::" +```yaml{:copy} +jobs: + bash-example: + runs-on: ubuntu-latest + steps: + - name: Group of log lines + run: | + echo "::group::My title" + echo "Inside group" + echo "::endgroup::" ``` +{% endbash %} + +{% powershell %} + +```yaml{:copy} +jobs: + powershell-example: + runs-on: windows-latest + steps: + - name: Group of log lines + run: | + Write-Output "::group::My title" + Write-Output "Inside group" + Write-Output "::endgroup::" +``` + +{% endpowershell %} + ![Foldable group in workflow run log](/assets/images/actions-log-group.png) ## Masking a value in log -``` +```{:copy} ::add-mask::{value} ``` Masking a value prevents a string or variable from being printed in the log. Each masked word separated by whitespace is replaced with the `*` character. You can use an environment variable or string for the mask's `value`. -### Example masking a string +### Example: Masking a string When you print `"Mona The Octocat"` in the log, you'll see `"***"`. -```bash +{% bash %} + +```bash{:copy} echo "::add-mask::Mona The Octocat" ``` -### Example masking an environment variable +{% endbash %} + +{% powershell %} + +```pwsh{:copy} +Write-Output "::add-mask::Mona The Octocat" +``` + +{% endpowershell %} + +### 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"`. -```bash -MY_NAME="Mona The Octocat" -echo "::add-mask::$MY_NAME" +{% bash %} + +```yaml{:copy} +jobs: + bash-example: + runs-on: ubuntu-latest + env: + MY_NAME: "Mona The Octocat" + steps: + - name: bash-version + run: echo "::add-mask::$MY_NAME" ``` +{% endbash %} + +{% powershell %} + +```yaml{:copy} +jobs: + powershell-example: + runs-on: windows-latest + env: + MY_NAME: "Mona The Octocat" + steps: + - name: powershell-version + run: Write-Output "::add-mask::$env:MY_NAME" +``` + +{% endpowershell %} + ## Stopping and starting workflow commands -`::stop-commands::{endtoken}` - Stops processing any workflow commands. This special command allows you to log anything without accidentally running a workflow command. For example, you could stop logging to output an entire script that has comments. +```{:copy} +::stop-commands::{endtoken} +``` + To stop the processing of workflow commands, pass a unique token to `stop-commands`. To resume processing workflow commands, pass the same token that you used to stop workflow commands. {% warning %} -**Warning:** Make sure the token you're using is randomly generated and unique for each run. As demonstrated in the example below, you can generate a unique hash of your `github.token` for each run. +**Warning:** Make sure the token you're using is randomly generated and unique for each run. {% endwarning %} -``` +```{:copy} ::{endtoken}:: ``` -### Example stopping and starting workflow commands +### Example: Stopping and starting workflow commands + +{% bash %} {% raw %} -```yaml +```yaml{:copy} jobs: workflow-command-job: runs-on: ubuntu-latest steps: - - name: disable workflow commands + - name: Disable workflow commands run: | - echo '::warning:: this is a warning' - echo "::stop-commands::`echo -n ${{ github.token }} | sha256sum | head -c 64`" - echo '::warning:: this will NOT be a warning' - echo "::`echo -n ${{ github.token }} | sha256sum | head -c 64`::" - echo '::warning:: this is a warning again' + echo '::warning:: This is a warning message, to demonstrate that commands are being processed.' + stopMarker=$(uuidgen) + echo "::stop-commands::$stopMarker" + echo '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.' + echo "::$stopMarker::" + echo '::warning:: This is a warning again, because stop-commands has been turned off.' +``` +{% endraw %} + +{% endbash %} + +{% powershell %} + +{% raw %} +```yaml{:copy} +jobs: + workflow-command-job: + runs-on: windows-latest + steps: + - name: Disable workflow commands + run: | + Write-Output '::warning:: This is a warning message, to demonstrate that commands are being processed.' + $stopMarker = New-Guid + Write-Output "::stop-commands::$stopMarker" + Write-Output '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.' + Write-Output "::$stopMarker::" + Write-Output '::warning:: This is a warning again, because stop-commands has been turned off.' ``` {% endraw %} +{% endpowershell %} + ## Echoing command outputs -``` +Enables or disables echoing of workflow commands. For example, if you use the `set-output` command in a workflow, it sets an output parameter but the workflow run's log does not show the command itself. If you enable command echoing, then the log shows the command, such as `::set-output name={name}::{value}`. + +```{:copy} ::echo::on ::echo::off ``` -Enables or disables echoing of workflow commands. For example, if you use the `set-output` command in a workflow, it sets an output parameter but the workflow run's log does not show the command itself. If you enable command echoing, then the log shows the command, such as `::set-output name={name}::{value}`. - Command echoing is disabled by default. However, a workflow command is echoed if there are any errors processing the command. The `add-mask`, `debug`, `warning`, and `error` commands do not support echoing because their outputs are already echoed to the log. You can also enable command echoing globally by turning on step debug logging using the `ACTIONS_STEP_DEBUG` secret. For more information, see "[Enabling debug logging](/actions/managing-workflow-runs/enabling-debug-logging)". In contrast, the `echo` workflow command lets you enable command echoing at a more granular level, rather than enabling it for every workflow in a repository. -### Example toggling command echoing +### Example: Toggling command echoing -```yaml +{% bash %} + +```yaml{:copy} jobs: workflow-command-job: runs-on: ubuntu-latest @@ -278,9 +463,29 @@ jobs: echo '::set-output name=action_echo::disabled' ``` -The step above prints the following lines to the log: +{% endbash %} +{% powershell %} + +```yaml{:copy} +jobs: + workflow-command-job: + runs-on: windows-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" ``` + +{% endpowershell %} + +The example above prints the following lines to the log: + +```{:copy} ::set-output name=action_echo::enabled ::echo::off ``` @@ -297,13 +502,13 @@ The `save-state` command can only be run within an action, and is not available This example uses JavaScript to run the `save-state` command. The resulting environment variable is named `STATE_processID` with the value of `12345`: -``` javascript +```javascript{:copy} console.log('::save-state name=processID::12345') ``` 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: -``` javascript +```javascript{:copy} console.log("The running PID from the main action is: " + process.env.STATE_processID); ``` @@ -311,37 +516,70 @@ console.log("The running PID from the main action is: " + process.env.STATE_pro 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 %} +{% powershell %} -**Warning:** On Windows, legacy PowerShell (`shell: powershell`) does not use UTF-8 by default. +{% note %} -When using `shell: powershell`, you must specify UTF-8 encoding. For example: +**Note:** PowerShell versions 5.1 and below (`shell: powershell`) do not use UTF-8 by default, so you must specify the UTF-8 encoding. For example: -```yaml +```yaml{:copy} jobs: legacy-powershell-example: - uses: windows-2019 + runs-on: windows-latest 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. +PowerShell Core versions 6 and higher (`shell: pwsh`) use UTF-8 by default. For example: -{% endwarning %} +```yaml{:copy} +jobs: + powershell-core-example: + runs-on: windows-latest + steps: + - shell: pwsh + run: | + "mypath" >> $env:GITHUB_PATH +``` + +{% endnote %} + +{% endpowershell %} ## Setting an environment variable -``` bash +{% bash %} + +```bash{:copy} echo "{environment_variable_name}={value}" >> $GITHUB_ENV ``` +{% endbash %} + +{% powershell %} + +- Using PowerShell version 6 and higher: +```pwsh{:copy} +"{environment_variable_name}={value}" >> $env:GITHUB_ENV +``` + +- Using PowerShell version 5.1 and below: +```powershell{:copy} +"{environment_variable_name}={value}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append +``` + +{% endpowershell %} + 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 +{% bash %} + {% raw %} -``` +```yaml{:copy} steps: - name: Set the value id: step_one @@ -354,11 +592,31 @@ steps: ``` {% endraw %} +{% endbash %} + +{% powershell %} + +{% raw %} +```yaml{:copy} +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 %} + +{% endpowershell %} + ### Multiline strings For multiline strings, you may use a delimiter with the following syntax. -``` +```{:copy} {name}<<{delimiter} {value} {delimiter} @@ -366,29 +624,75 @@ For multiline strings, you may use a delimiter with the following syntax. #### Example -In this example, we use `EOF` as a delimiter and set the `JSON_RESPONSE` environment variable to the value of the curl response. -```yaml +This example uses `EOF` as a delimiter, and sets the `JSON_RESPONSE` environment variable to the value of the `curl` response. + +{% bash %} + +```yaml{:copy} steps: - - name: Set the value + - name: Set the value in bash id: step_one run: | echo 'JSON_RESPONSE<> $GITHUB_ENV - curl https://httpbin.org/json >> $GITHUB_ENV + curl https://example.lab >> $GITHUB_ENV echo 'EOF' >> $GITHUB_ENV ``` -## Adding a system path +{% endbash %} -``` bash -echo "{path}" >> $GITHUB_PATH +{% powershell %} + +```yaml{:copy} +steps: + - name: Set the value in pwsh + id: step_one + run: | + "JSON_RESPONSE<> $env:GITHUB_ENV + (Invoke-WebRequest -Uri "https://example.lab").Content >> $env:GITHUB_ENV + "EOF" >> $env:GITHUB_ENV + shell: pwsh ``` +{% endpowershell %} + +## Adding a system 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. +{% bash %} + +```bash{:copy} +echo "{path}" >> $GITHUB_PATH +``` +{% endbash %} + +{% powershell %} + +```pwsh{:copy} +"{path}" >> $env:GITHUB_PATH +``` + +{% endpowershell %} + ### Example This example demonstrates how to add the user `$HOME/.local/bin` directory to `PATH`: -``` bash +{% bash %} + +```bash{:copy} echo "$HOME/.local/bin" >> $GITHUB_PATH ``` + +{% endbash %} + + +This example demonstrates how to add the user `$env:HOMEPATH/.local/bin` directory to `PATH`: + +{% powershell %} + +```pwsh{:copy} +"$env:HOMEPATH/.local/bin" >> $env:GITHUB_PATH +``` + +{% endpowershell %} diff --git a/contributing/content-markup-reference.md b/contributing/content-markup-reference.md index 8d71dffedd..7d8fe5dd2e 100644 --- a/contributing/content-markup-reference.md +++ b/contributing/content-markup-reference.md @@ -196,6 +196,22 @@ These instructions are pertinent to GraphQL API users. {% endgraphql %} ``` +``` +{% powershell %} + +These instructions are pertinent to `pwsh` and `powershell` commands. + +{% endpowershell %} +``` + +``` +{% bash %} + +These instructions are pertinent to Bash shell commands. + +{% endbash %} +``` + You can define a default tool in the frontmatter. For more information, see the [content README](../content/README.md#defaulttool). ## Reusable and variable strings of text diff --git a/lib/frontmatter.js b/lib/frontmatter.js index 5f8a673ad6..0d14fabc2f 100644 --- a/lib/frontmatter.js +++ b/lib/frontmatter.js @@ -181,7 +181,18 @@ export const schema = { // Tool-specific content preference defaultTool: { type: 'string', - enum: ['webui', 'cli', 'desktop', 'curl', 'codespaces', 'vscode', 'importer_cli', 'graphql'], + enum: [ + 'webui', + 'cli', + 'desktop', + 'curl', + 'codespaces', + 'vscode', + 'importer_cli', + 'graphql', + 'powershell', + 'bash', + ], }, // Documentation contributed by a third party, such as a GitHub Partner contributor: { diff --git a/lib/liquid-tags/extended-markdown.js b/lib/liquid-tags/extended-markdown.js index 507b8b83c2..20eec54659 100644 --- a/lib/liquid-tags/extended-markdown.js +++ b/lib/liquid-tags/extended-markdown.js @@ -10,6 +10,8 @@ export const tags = { vscode: '', importer_cli: '', graphql: '', + powershell: '', + bash: '', all: '', tip: 'border rounded-1 mb-4 p-3 color-border-accent-emphasis color-bg-accent f5', note: 'border rounded-1 mb-4 p-3 color-border-accent-emphasis color-bg-accent f5', diff --git a/lib/page.js b/lib/page.js index 0041c699ab..6e66b4f02e 100644 --- a/lib/page.js +++ b/lib/page.js @@ -294,6 +294,8 @@ class Page { 'vscode', `importer_cli`, `graphql`, + 'powershell', + 'bash', ].filter((tool) => html.includes(`extended-markdown ${tool}`) || html.includes(`tool-${tool}`)) this.includesToolSpecificContent = this.detectedTools.length > 0 diff --git a/lib/schema-event.js b/lib/schema-event.js index 4d4e94a624..ec9564573e 100644 --- a/lib/schema-event.js +++ b/lib/schema-event.js @@ -146,7 +146,18 @@ const context = { }, application_preference: { type: 'string', - enum: ['webui', 'cli', 'desktop', 'curl', 'codespaces', 'vscode', 'importer_cli', 'graphql'], + enum: [ + 'webui', + 'cli', + 'desktop', + 'curl', + 'codespaces', + 'vscode', + 'importer_cli', + 'graphql', + 'powershell', + 'bash', + ], description: 'The application selected by the user.', }, color_mode_preference: { @@ -449,6 +460,8 @@ const preferenceSchema = { 'vscode', 'importer_cli', 'graphql', + 'powershell', + 'bash', 'dark', 'light', 'auto',