Document jobs.<job_id>.defaults.run.working-directory

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.<job_id>.defaults.run.shell`
+
+{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-run-shell %}
+
+## `jobs.<job_id>.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.<job_id>.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.<job_id>.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.<job_id>.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.<job_id>.defaults.run.shell`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrunshell)."
 
 ### Example: Running a command using Bash
 

data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-job-run.md

@@ -1,5 +1,7 @@
-Use `jobs.<job_id>.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.<job_id>.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.<job_id>.defaults.run` and `jobs.<job_id>.steps[*].run` levels.
+
 {% data reusables.actions.defaults-override %}

data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-run-shell.md

@@ -0,0 +1,10 @@
+Use `shell` to define the `shell` for a step. {% data reusables.actions.reusable-keyword %}
+
+{% data reusables.actions.supported-shells %}
+
+The `shell` for a step is taken from the first defined in this list:
+1. The step `jobs.<job_id>.steps[*].run.shell`. See [`jobs.<job_id>.steps[*].shell`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell).
+1. The job `jobs.<job_id>.defaults.run.shell`. See [`jobs.<job_id>.defaults.run.shell`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrunshell).
+1. The workflow `defaults.run.shell`. See [`defaults.run.shell`](/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrunshell).
+
+{% data reusables.actions.defaults-override %}

data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-run-working-directory.md

@@ -0,0 +1,10 @@
+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 %}
+
+The `working-directory` for a step is taken from the first defined in this list:
+1. The step `jobs.<job_id>.steps[*].run.working-directory`. See [`jobs.<job_id>.steps[*].working-directory`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsworking-directory).
+1. The job `jobs.<job_id>.defaults.run.working-directory`. See [`jobs.<job_id>.defaults.run.working-directory`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrunworking-directory).
+1. The workflow `defaults.run.working-directory`. See [`defaults.run.working-directory`](/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrunworking-directory).
+
+{% data reusables.actions.defaults-override %}

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)."

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}'"`.                |

data/reusables/actions/working-directory-must-exist.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** If the `working-directory` does not exist, the step will probably fail to run the `shell`.
+
+{% endnote %}