Skip to content

Commit

Permalink
Document jobs.<job_id>.defaults.run.working-directory (#31970)
Browse files Browse the repository at this point in the history 
Co-authored-by: Siara <108543037+SiaraMist@users.noreply.github.com>
  • Loading branch information
@jsoref @SiaraMist
jsoref and SiaraMist committed Mar 12, 2024
1 parent 482edf6 commit bb5537e
Show file tree
Hide file tree
Showing 7 changed files with 49 additions and 14 deletions.
35 changes: 22 additions & 13 deletions content/actions/using-workflows/workflow-syntax-for-github-actions.md
View file
Expand Up @@ -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 %}
Expand Down Expand Up @@ -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 %}
Expand Down Expand Up @@ -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

Expand Down
4 changes: 3 additions & 1 deletion data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-job-run.md
View file
@@ -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 %}
4 changes: 4 additions & 0 deletions data/reusables/actions/jobs/setting-default-values-for-jobs-defaults-run-shell.md
View file
@@ -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 %}
4 changes: 4 additions & 0 deletions .../actions/jobs/setting-default-values-for-jobs-defaults-run-working-directory.md
View file
@@ -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 %}
1 change: 1 addition & 0 deletions data/reusables/actions/reusable-keyword.md
View file
@@ -0,0 +1 @@
This keyword can reference several contexts. For more information, see "[Contexts](/actions/learn-github-actions/contexts#context-availability)."
10 changes: 10 additions & 0 deletions data/reusables/actions/supported-shells.md
View file
@@ -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}'"`. |
5 changes: 5 additions & 0 deletions data/reusables/actions/working-directory-must-exist.md
View file
@@ -0,0 +1,5 @@
{% note %}

**Tip:** Ensure the `working-directory` you assign exists on the runner before you run your shell in it.

{% endnote %}

0 comments on commit bb5537e

Please sign in to comment.