Skip to main content

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:

  1. Go to Workflows and open the workflow you want to edit.
  2. 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.
  3. In the job editor, select the Job Definition tab.
  4. In the Job Type list, choose Run Script.
  5. Under Job Parameters, choose the Script Type and enter your Script Content.
  6. Set any optional settings (see below).
  7. Select Save.

Settings​

SettingNotes
Script Typepowershell, bash, python or shell. Required. A new Run Script job starts on shell, and saves with it unless you choose another.
Script ContentThe script to run. Required.
Script ArgumentsArguments passed to the script.
Working DirectoryWhere the script runs. Defaults to the agent's working directory.
Environment VariablesExtra environment variables for the script.
Fail on ErrorOn 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 CriteriaUp to five exit-code conditions that mark the job failed. If any one matches, the job fails.
Output ParsingUp 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