diff --git a/content/actions/using-workflows/workflow-syntax-for-github-actions.md b/content/actions/using-workflows/workflow-syntax-for-github-actions.md index 51692b26204d3..df0d2f9f6f7a9 100644 --- a/content/actions/using-workflows/workflow-syntax-for-github-actions.md +++ b/content/actions/using-workflows/workflow-syntax-for-github-actions.md @@ -264,6 +264,14 @@ env: {% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-run %} +## `defaults.run.shell` + +{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-run-shell %} + +## `defaults.run.working-directory` + +{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-run-working-directory %} + ## `concurrency` {% data reusables.actions.jobs.section-using-concurrency %} @@ -345,6 +353,14 @@ jobs: {% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-job-run %} +## `jobs..defaults.run.shell` + +{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-run-shell %} + +## `jobs..defaults.run.working-directory` + +{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-run-working-directory %} + ### Example: Setting default `run` step options for a job {% data reusables.actions.jobs.setting-default-run-value-for-job-example %} @@ -616,24 +632,17 @@ Using the `working-directory` keyword, you can specify the working directory of working-directory: ./temp ``` -Alternatively, you can specify a default working directory for all `run` steps in a job, or for all `run` steps in the entire workflow. For more information, see "[`defaults.run`](/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun)" and "[`jobs..defaults.run`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrun)." +Alternatively, you can specify a default working directory for all `run` steps in a job, or for all `run` steps in the entire workflow. For more information, see "[`defaults.run.working-directory`](/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrunworking-directory)" and "[`jobs..defaults.run.working-directory`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrunworking-directory)." You can also use a `run` step to run a script. For more information, see "[AUTOTITLE](/actions/learn-github-actions/essential-features-of-github-actions#adding-scripts-to-your-workflow)." ## `jobs..steps[*].shell` -You can override the default shell settings in the runner's operating system using the `shell` keyword. You can use built-in `shell` keywords, or you can define a custom set of shell options. The shell command that is run internally executes a temporary file that contains the commands specified in the `run` keyword. - -| Supported platform | `shell` parameter | Description | Command run internally | -| ------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | -| Linux / macOS | unspecified | The default shell on non-Windows platforms. Note that this runs a different command to when `bash` is specified explicitly. If `bash` is not found in the path, this is treated as `sh`. | `bash -e {0}` | -| All | `bash` | The default shell on non-Windows platforms with a fallback to `sh`. When specifying a bash shell on Windows, the bash shell included with Git for Windows is used. | `bash --noprofile --norc -eo pipefail {0}` | -| All | `pwsh` | The PowerShell Core. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `pwsh -command ". '{0}'"` | -| All | `python` | Executes the python command. | `python {0}` | -| Linux / macOS | `sh` | The fallback behavior for non-Windows platforms if no shell is provided and `bash` is not found in the path. | `sh -e {0}` | -| Windows | `cmd` | {% data variables.product.prodname_dotcom %} appends the extension `.cmd` to your script name and substitutes for `{0}`. | `%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""`. | -| Windows | `pwsh` | This is the default shell used on Windows. The PowerShell Core. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. If your self-hosted Windows runner does not have _PowerShell Core_ installed, then _PowerShell Desktop_ is used instead. | `pwsh -command ". '{0}'"`. | -| Windows | `powershell` | The PowerShell Desktop. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `powershell -command ". '{0}'"`. | +You can override the default shell settings in the runner's operating system and the job's default using the `shell` keyword. You can use built-in `shell` keywords, or you can define a custom set of shell options. The shell command that is run internally executes a temporary file that contains the commands specified in the `run` keyword. + +{% data reusables.actions.supported-shells %} + +Alternatively, you can specify a default shell for all `run` steps in a job, or for all `run` steps in the entire workflow. For more information, see "[`defaults.run.shell`](/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrunshell)" and "[`jobs..defaults.run.shell`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrunshell)." ### Example: Running a command using Bash diff --git a/data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-job-run.md b/data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-job-run.md index 6b3e12ded1680..8d9c030e98cc2 100644 --- a/data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-job-run.md +++ b/data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-job-run.md @@ -1,5 +1,7 @@ -Use `jobs..defaults.run` to provide default `shell` and `working-directory` to all `run` steps in the job. This keyword can reference several contexts. For more information, see "[Contexts](/actions/learn-github-actions/contexts#context-availability)." +Use `jobs..defaults.run` to provide default `shell` and `working-directory` to all `run` steps in the job. You can provide default `shell` and `working-directory` options for all [`run`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun) steps in a job. You can also set default settings for `run` for the entire workflow. For more information, see [`defaults.run`](/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun). +These can be overriden at the `jobs..defaults.run` and `jobs..steps[*].run` levels. + {% data reusables.actions.defaults-override %} diff --git a/data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-run-shell.md b/data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-run-shell.md new file mode 100644 index 0000000000000..d233a30cbc8b7 --- /dev/null +++ b/data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-run-shell.md @@ -0,0 +1,4 @@ +Use `shell` to define the `shell` for a step. {% data reusables.actions.reusable-keyword %} + +{% data reusables.actions.supported-shells %} +{% data reusables.actions.defaults-override %} diff --git a/data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-run-working-directory.md b/data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-run-working-directory.md new file mode 100644 index 0000000000000..fe875ca479035 --- /dev/null +++ b/data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-run-working-directory.md @@ -0,0 +1,4 @@ +Use `working-directory` to define the working directory for the `shell` for a step. {% data reusables.actions.reusable-keyword %} + +{% data reusables.actions.working-directory-must-exist %} +{% data reusables.actions.defaults-override %} diff --git a/data/reusables/actions/reusable-keyword.md b/data/reusables/actions/reusable-keyword.md new file mode 100644 index 0000000000000..a91ec70ae60c0 --- /dev/null +++ b/data/reusables/actions/reusable-keyword.md @@ -0,0 +1 @@ +This keyword can reference several contexts. For more information, see "[Contexts](/actions/learn-github-actions/contexts#context-availability)." diff --git a/data/reusables/actions/supported-shells.md b/data/reusables/actions/supported-shells.md new file mode 100644 index 0000000000000..8189709701e42 --- /dev/null +++ b/data/reusables/actions/supported-shells.md @@ -0,0 +1,10 @@ +| Supported platform | `shell` parameter | Description | Command run internally | +| ------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | +| Linux / macOS | unspecified | The default shell on non-Windows platforms. Note that this runs a different command to when `bash` is specified explicitly. If `bash` is not found in the path, this is treated as `sh`. | `bash -e {0}` | +| All | `bash` | The default shell on non-Windows platforms with a fallback to `sh`. When specifying a bash shell on Windows, the bash shell included with Git for Windows is used. | `bash --noprofile --norc -eo pipefail {0}` | +| All | `pwsh` | The PowerShell Core. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `pwsh -command ". '{0}'"` | +| All | `python` | Executes the python command. | `python {0}` | +| Linux / macOS | `sh` | The fallback behavior for non-Windows platforms if no shell is provided and `bash` is not found in the path. | `sh -e {0}` | +| Windows | `cmd` | {% data variables.product.prodname_dotcom %} appends the extension `.cmd` to your script name and substitutes for `{0}`. | `%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""`. | +| Windows | `pwsh` | This is the default shell used on Windows. The PowerShell Core. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. If your self-hosted Windows runner does not have _PowerShell Core_ installed, then _PowerShell Desktop_ is used instead. | `pwsh -command ". '{0}'"`. | +| Windows | `powershell` | The PowerShell Desktop. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `powershell -command ". '{0}'"`. | diff --git a/data/reusables/actions/working-directory-must-exist.md b/data/reusables/actions/working-directory-must-exist.md new file mode 100644 index 0000000000000..2c7a381ba1623 --- /dev/null +++ b/data/reusables/actions/working-directory-must-exist.md @@ -0,0 +1,5 @@ +{% note %} + +**Tip:** Ensure the `working-directory` you assign exists on the runner before you run your shell in it. + +{% endnote %}