|
| 1 | +--- |
| 2 | +title: Running scripts before or after a job |
| 3 | +intro: 'Scripts can automatically execute on a self-hosted runner, directly before or after a job.' |
| 4 | +versions: |
| 5 | + feature: 'job-hooks-for-runners' |
| 6 | +type: tutorial |
| 7 | +miniTocMaxHeadingLevel: 3 |
| 8 | +shortTitle: Run a script before or after a job |
| 9 | +--- |
| 10 | + |
| 11 | +{% note %} |
| 12 | + |
| 13 | +**Note**: This feature is currently in beta and is subject to change. |
| 14 | + |
| 15 | +{% endnote %} |
| 16 | + |
| 17 | +## About pre- and post-job scripts |
| 18 | + |
| 19 | +You can automatically execute scripts on a self-hosted runner, either before a job runs, or after a job finishes running. You could use these scripts to support the job's requirements, such as building or tearing down a runner environment, or cleaning out directories. You could also use these scripts to track telemetry of how your runners are used. |
| 20 | + |
| 21 | +The custom scripts are automatically triggered when a specific environment variable is set on the runner; the environment variable must contain the absolute path to the script. For more information, see "[Triggering the scripts](#triggering-the-scripts)" below. |
| 22 | + |
| 23 | +The following scripting languages are supported: |
| 24 | + |
| 25 | +- **Bash**: Uses `bash` and can fallback to `sh`. Executes by running `-e {pathtofile}`. |
| 26 | +- **PowerShell**: Uses `pwsh` and can fallback to `powershell`. Executes by running `-command \". '{pathtofile}'\"`. |
| 27 | + |
| 28 | +## Writing the scripts |
| 29 | + |
| 30 | +Your custom scripts can use the following features: |
| 31 | + |
| 32 | +- **Environment variables**: Scripts have access to the default environment variables. The full webhook event payload can be found in `GITHUB_EVENT_PATH`. For more information, see "[Environment variables](/actions/learn-github-actions/environment-variables#default-environment-variables)." |
| 33 | +- **Workflow commands**: Scripts can use workflow commands. For more information, see ["Workflow commands for {% data variables.product.prodname_actions %}"](/actions/using-workflows/workflow-commands-for-github-actions), with the exception of `save-state` and `set-output`, which are not supported by these scripts. Scripts can also use environment files. For more information, see [Environment files](/actions/using-workflows/workflow-commands-for-github-actions#environment-files). |
| 34 | + |
| 35 | +{% note %} |
| 36 | + |
| 37 | +**Note**: Avoid using your scripts to output sensitive information to the console, as anyone with read access to the repository might be able to see the output in the UI logs. |
| 38 | + |
| 39 | +{% endnote %} |
| 40 | + |
| 41 | +### Handling exit codes |
| 42 | + |
| 43 | +For pre-job scripts, exit code `0` indicates that the script completed successfully, and the job will then proceed to run. If there is any other exit code, the job will not run and will be marked as failed. To see the results of your pre-job scripts, check the logs for `Set up runner` entries. For more information on checking the logs, see "[Viewing logs to diagnose failures](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#viewing-logs-to-diagnose-failures)." |
| 44 | + |
| 45 | +The [`continue-on-error`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error) setting is not supported for use by these scripts. |
| 46 | + |
| 47 | +## Triggering the scripts |
| 48 | + |
| 49 | +The custom scripts must be located on the runner, but should not be stored in the `actions-runner` application directory. The scripts are executed in the security context of the service account that's running the runner service. |
| 50 | + |
| 51 | +{% note %} |
| 52 | + |
| 53 | +**Note**: The triggered scripts are processed synchronously, so they will block job execution while they are running. |
| 54 | + |
| 55 | +{% endnote %} |
| 56 | + |
| 57 | +The scripts are automatically executed when the runner has the following environment variables containing an absolute path to the script: |
| 58 | +- `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. |
| 59 | +- `ACTIONS_RUNNER_HOOK_JOB_COMPLETED`: The script defined in this environment variable is triggered after the job has finished processing. |
| 60 | + |
| 61 | +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: |
| 62 | + |
| 63 | +```bash |
| 64 | +ACTIONS_RUNNER_HOOK_JOB_STARTED=/cleanup_script.sh |
| 65 | +``` |
| 66 | + |
| 67 | +## Troubleshooting |
| 68 | + |
| 69 | + |
| 70 | +### No timeout setting |
| 71 | + |
| 72 | +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. |
| 73 | + |
| 74 | +### Reviewing the workflow run log |
| 75 | + |
| 76 | +To confirm whether your scripts are executing, you can review the logs for that job. The scripts will be listed within separate steps for either `Set up runner` or `Complete runner`, depending on which environment variable is triggering the script. For more information on checking the logs, see "[Viewing logs to diagnose failures](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#viewing-logs-to-diagnose-failures)." |
0 commit comments