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 from the Job Tools panel.
- In the job editor, select the Job Definition tab.
- Select Show Job Types.
- In the job type catalog, under Script, select Run Script.
- Under Job Parameters, choose the Script Type and enter your Script Content.
- Set any optional settings (see below).
- Select Save & Close.
Settings
| Setting | Notes |
|---|---|
| Script Type | PowerShell, Bash, Python, or Shell. Shell is the default. |
| 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 fails the job. Turn off and the exit code never fails it. |
| Exit Criteria | Up to five exit-code conditions that mark the job failed. Set any and Fail on Error no longer applies. |
| 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. - A job the platform stops — a timeout, or a cancel — always fails, whatever your exit criteria say.
Related topics
- Run Script job — full configuration reference and troubleshooting
- Run a command (Builder)
- Prepare agents for connectors (Administrator)