Clarify how to run a script from a workflow (#42163)

Co-authored-by: Siara <108543037+SiaraMist@users.noreply.github.com>

content/actions/hosting-your-own-runners/managing-self-hosted-runners/customizing-the-containers-used-by-jobs.md

@@ -500,7 +500,7 @@ When the resulting `index.js` is triggered by {% data variables.product.prodname
 
 ## Triggering the customization script
 
-The custom script must be located on the runner, but should not be stored in the self-hosted runner application directory. The scripts are executed in the security context of the service account that's running the runner service.
+The custom script must be located on the runner, but should not be stored in the self-hosted runner application directory (that is, the directory into which you downloaded and unpacked the runner software). The scripts are executed in the security context of the service account that's running the runner service.
 
 {% note %}
 

content/actions/hosting-your-own-runners/managing-self-hosted-runners/running-scripts-before-or-after-a-job.md

@@ -55,14 +55,24 @@ The scripts are automatically executed when the runner has the following environ
 - `ACTIONS_RUNNER_HOOK_JOB_STARTED`: The script defined in this environment variable is triggered when a job has been assigned to a runner, but before the job starts running.
 - `ACTIONS_RUNNER_HOOK_JOB_COMPLETED`: The script defined in this environment variable is triggered after the job has finished processing.
 
-To set these environment variables, you can either add them to the operating system, or add them to a file named `.env` within the self-hosted runner application directory. For example, the following `.env` entry will have the runner automatically run a script named `cleanup_script.sh` before each job runs:
+To set these environment variables, you can either add them to the operating system, or add them to a file named `.env` within the self-hosted runner application directory (that is, the directory into which you downloaded and unpacked the runner software). For example, the following `.env` entry will have the runner automatically run a script, saved as `/opt/runner/cleanup_script.sh` on the runner machine, before each job runs:
 
 ```bash
-ACTIONS_RUNNER_HOOK_JOB_STARTED=/cleanup_script.sh
+ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/runner/cleanup_script.sh
 ```
 
 ## Troubleshooting
 
+### Permission denied
+
+If you get a "permission denied" error when you attempt to run a script, make sure that the script is executable. For example, in a terminal on Linux or MacOS you can use the following command to make a file executable.
+
+```bash
+chmod +x PATH/TO/FILE
+```
+
+For information about using workflows to run scripts, see "[AUTOTITLE](/actions/learn-github-actions/essential-features-of-github-actions#adding-scripts-to-your-workflow)."
+
 ### No timeout setting
 
 There is currently no timeout setting available for scripts executed by `ACTIONS_RUNNER_HOOK_JOB_STARTED` or `ACTIONS_RUNNER_HOOK_JOB_COMPLETED`. As a result, you could consider adding timeout handling to your script.

content/actions/hosting-your-own-runners/managing-self-hosted-runners/using-a-proxy-server-with-self-hosted-runners.md

@@ -41,9 +41,9 @@ On Windows machines, the proxy environment variable names are case insensitive.
 
 ## Using a .env file to set the proxy configuration
 
-If setting environment variables is not practical, you can set the proxy configuration variables in a file named _.env_ in the self-hosted runner application directory. For example, this might be necessary if you want to configure the runner application as a service under a system account. When the runner application starts, it reads the variables set in _.env_ for the proxy configuration.
+If setting environment variables is not practical, you can set the proxy configuration variables in a file named `.env` in the self-hosted runner application directory (that is, the directory into which you downloaded and unpacked the runner software). For example, this might be necessary if you want to configure the runner application as a service under a system account. When the runner application starts, it reads the variables set in `.env` for the proxy configuration.
 
-An example _.env_ proxy configuration is shown below:
+### Example `.env` proxy configuration
 
 ```ini
 https_proxy=http://proxy.local:8080

content/actions/learn-github-actions/essential-features-of-github-actions.md

@@ -37,27 +37,55 @@ For more information, see "[AUTOTITLE](/actions/learn-github-actions/variables#d
 
 ## Adding scripts to your workflow
 
-You can use actions to run scripts and shell commands, which are then executed on the assigned runner. This example demonstrates how an action can use the `run` keyword to execute `npm install -g bats` on the runner.
+You can use a {% data variables.product.prodname_actions %} workflow to run scripts and shell commands, which are then executed on the assigned runner. This example demonstrates how to use the `run` keyword to execute the command `npm install -g bats` on the runner.
 
 ```yaml
 jobs:
   example-job:
+    runs-on: ubuntu-latest
     steps:
       - run: npm install -g bats
 ```
 
-For example, to run a script as an action, you can store the script in your repository and supply the path and shell type.
+To use a workflow to run a script stored in your repository you must first check out the repository to the runner. Having done this, you can use the `run` keyword to run the script on the runner. The following example runs two scripts, each in a separate job step. The location of the scripts on the runner is specified by setting a default working directory for run commands. For more information, see "[AUTOTITLE](/actions/using-jobs/setting-default-values-for-jobs)."
 
 ```yaml
 jobs:
   example-job:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./scripts
     steps:
-      - name: Run build script
+      - name: Check out the repository to the runner
-        run: ./.github/scripts/build.sh
+        uses: {% data reusables.actions.action-checkout %}  
-        shell: bash
+      - name: Run a script
+        run: ./my-script.sh
+      - name: Run another script
+        run: ./my-other-script.sh
 ```
 
-For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun)."
+Any scripts that you want a workflow job to run must be executable. You can do this either within the workflow by passing the script as an argument to the interpreter that will run the script - for example, `run: bash script.sh` - or by making the file itself executable. You can give the file the execute permission by using the command `git update-index --chmod=+x PATH/TO/YOUR/script.sh` locally, then committing and pushing the file to the repository. Alternatively, for workflows that are run on Linux and Mac runners, you can add a command to give the file the execute permission in the workflow job, prior to running the script:
+
+```yaml
+jobs:
+  example-job:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./scripts
+    steps:
+      - name: Check out the repository to the runner
+        uses: {% data reusables.actions.action-checkout %}  
+      - name: Make the script files executable
+        run: chmod +x my-script.sh my-other-script.sh
+      - name: Run the scripts
+        run: |
+          ./my-script.sh
+          ./my-other-script.sh
+```
+
+For more information about the `run` keyword, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun)."
 
 ## Sharing data between jobs
 

content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-jenkins-to-github-actions.md

@@ -226,5 +226,5 @@ jobs:
           node-version: 16
       - run: npm install -g bats
       - run: bats tests
-        working-directory: scripts/myapp
+        working-directory: ./scripts/myapp
 ```

content/actions/using-workflows/workflow-syntax-for-github-actions.md

@@ -623,6 +623,10 @@ 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)."
+
+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.
@@ -638,51 +642,51 @@ You can override the default shell settings in the runner's operating system usi
 | 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}'"`. |
 
-### Example: Running a script using bash
+### Example: Running a command using Bash
 
 ```yaml
 steps:
   - name: Display the path
-    run: echo $PATH
     shell: bash
+    run: echo $PATH
 ```
 
-### Example: Running a script using Windows `cmd`
+### Example: Running a command using Windows `cmd`
 
 ```yaml
 steps:
   - name: Display the path
-    run: echo %PATH%
     shell: cmd
+    run: echo %PATH%
 ```
 
-### Example: Running a script using PowerShell Core
+### Example: Running a command using PowerShell Core
 
 ```yaml
 steps:
   - name: Display the path
-    run: echo ${env:PATH}
     shell: pwsh
-```
-
-### Example: Using PowerShell Desktop to run a script
-
-```yaml
-steps:
-  - name: Display the path
     run: echo ${env:PATH}
-    shell: powershell
 ```
 
-### Example: Running a python script
+### Example: Using PowerShell Desktop to run a command
 
 ```yaml
 steps:
   - name: Display the path
+    shell: powershell
+    run: echo ${env:PATH}
+```
+
+### Example: Running an inline Python script
+
+```yaml
+steps:
+  - name: Display the path
+    shell: python
     run: |
       import os
       print(os.environ['PATH'])
-    shell: python
 ```
 
 ### Custom shell
@@ -694,9 +698,9 @@ For example:
 ```yaml
 steps:
   - name: Display the environment variables and their values
+    shell: perl {0}
     run: |
       print %ENV
-    shell: perl {0}
 ```
 
 The command used, `perl` in this example, must be installed on the runner.

content/admin/github-actions/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise.md

@@ -32,7 +32,7 @@ For the steps required to install a certificate, refer to the documentation for
 
 Most actions are written in JavaScript and run using Node.js, which does not use the operating system certificate store. For the self-hosted runner application to use the certificate, you must set the `NODE_EXTRA_CA_CERTS` environment variable on the runner machine.
 
-You can set the environment variable as a system environment variable, or declare it in a file named _.env_ in the self-hosted runner application directory.
+You can set the environment variable as a system environment variable, or declare it in a file called `.env` in the self-hosted runner application directory (that is, the directory into which you downloaded and unpacked the runner software).
 
 For example:
 

data/reusables/actions/jobs/setting-default-run-value-for-job-example.md

@@ -5,5 +5,5 @@ jobs:
     defaults:
       run:
         shell: bash
-        working-directory: scripts
+        working-directory: ./scripts
 ```

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

@@ -8,5 +8,5 @@ You can use `defaults.run` to provide default `shell` and `working-directory` op
 defaults:
   run:
     shell: bash
-    working-directory: scripts
+    working-directory: ./scripts
 ```

data/reusables/actions/self-hosted-runner-reusing.md

@@ -1 +1 @@
-Alternatively, if you don't have access to the repository{% ifversion fpt %} or organization{% elsif ghes or ghec or ghae %}, organization, or enterprise{% endif %} on {% data variables.product.product_name %} to remove a runner, but you would like to re-use the runner machine, then you can delete the `.runner` file inside the self-hosted runner application directory. This allows the runner to be registered without having to re-download the self-hosted runner application.
+Alternatively, if you don't have access to the repository{% ifversion fpt %} or organization{% elsif ghes or ghec or ghae %}, organization, or enterprise{% endif %} on {% data variables.product.product_name %} to remove a runner, but you would like to re-use the runner machine, then you can delete the `.runner` file inside the self-hosted runner application directory (that is, the directory into which you downloaded and unpacked the runner software). This allows the runner to be registered without having to re-download the self-hosted runner application.