Run a script
The Run Script job runs an embedded PowerShell, Bash, Python, or Shell script on the agent. Use it instead of Run Command when the logic is more than a single command line. It's built in, so there's nothing to set up.
What this solves
A step needs real logic: several commands, a loop, a conditional. Kept in a separate script file on some server, that logic drifts from the job and no one remembers where it lives or what it assumes.
Use it when
- Your step needs several commands, conditionals, or loops.
- You want to keep the script with the job rather than as a separate file.
Add a Run Script job to a workflow
To add a Run Script job, complete the following steps:
- Go to Workflows and open the workflow you want to edit.
- Add a job: on an empty workflow select First Job, otherwise select New Job (Null) in the tool panel on the left of the editor.
- In the job editor, select the Job Definition tab.
- In the Job Type list, choose Run Script.
- Under Job Parameters, choose the Script Type and enter your Script Content.
- Set any optional settings (see below).
- Select Save.
Settings
| Setting | Notes |
|---|---|
| Script Type | powershell, bash, python or shell. Required. A new Run Script job starts on shell, and saves with it unless you choose another. |
| Script Content | The script to run. Required. |
| Script Arguments | Arguments passed to the script. |
| Working Directory | Where the script runs. Defaults to the agent's working directory. |
| Environment Variables | Extra environment variables for the script. |
| Fail on Error | On by default: a non-zero exit code (after any output-parsing rule has set it) fails the job. Turn off and the exit code never fails it. Ignored when Exit Criteria are set. |
| Exit Criteria | Up to five exit-code conditions that mark the job failed. If any one matches, the job fails. |
| Output Parsing | Up to five rules that search the job output for text and set an exit code, which the exit criteria then judge. |
Good to know
- The interpreter your script uses must be installed on the agent — PowerShell 7 (
pwsh) on Linux/macOS, Python, or Bash. Shell is the exception: it is always available. If a script won't start, confirm the interpreter with your administrator. - PowerShell scripts run without your profile and with execution policy bypassed. Make the script self-contained rather than relying on a console's setup.
- Like Run Command, scripts can't read the agent's stored secrets from the environment. Pass what you need as Environment Variables or use a connection-based connector.
- Exit Criteria and Output Parsing are available here too, and work exactly as they do on Run a command. But a script you own can just call
exit 8— reach for them when the script is one you can't change, or when the signal is only in its output. - Every Run Script job has a fixed one-hour timeout, and no setting changes it. At the hour the agent stops the script, and a job the agent stops always fails, whatever your exit criteria say. A job that is stopped this way, whether by the timeout or by a cancel, reports exit code
128. Kill does not stop the script on a Universal Agent sooner.
Related topics
- Run Script job — full configuration reference and troubleshooting
- Run a command (Builder)
- Prepare agents for connectors (Administrator)