Script Runner

The Script Runner executes multi-line scripts using a selected shell or scripting environment. It supports complex logic, conditional execution, loops, and reusable automation, making it suitable for advanced build steps and sophisticated workflow orchestration.

When to Use

Use the Script Runner when you need to:

• Implement complex logic, including conditional branching and loops.
• Execute multiple commands that depend on runtime conditions or previous results.
• Create reusable automation scripts that can be maintained across multiple builds.
• Support cross-platform execution across different operating systems and environments.
• Improve readability, structure, and error handling compared to inline command execution.

Parameters

Parameter	Description
Step Name	Optional name for the build step. Defaults to the runner name if not specified.
Working Directory	Directory where the script will be executed.
Shell in Which to Run the Script	The shell or scripting environment used to execute the script. Supported options include: Bash: Default shell on most Linux systems; supports advanced scripting features. Shell (sh): POSIX-compliant shell with basic scripting support; best for portability. Zsh: Feature-rich shell with enhanced scripting and customization (if installed on the agent). Command Prompt: Windows command-line interpreter for running .cmd or .bat scripts. PowerShell: Cross-platform automation shell for Windows-based and cloud workflows. PowerShell 7: Modern, cross-platform PowerShell with improved performance and compatibility.
Script	The script content to execute during the build step. Enter the script directly, using the selected shell syntax.

Typical Use Cases

Common scenarios for using the Script Runner include:

• Implementing complex automation workflows with conditional logic and loops.
• Orchestrating multi-step processes that involve multiple tools or services.
• Performing environment validation and pre-deployment checks.
• Automating conditional deployments based on runtime parameters or build results.
• Creating reusable scripts shared across projects and teams.

Example

This example demonstrates how to execute conditional build logic using the Script Runner with a Bash shell.

Scenario
Run different build commands based on the deployment environment.

Configuration settings:

• Step Name: Conditional Build

• Working Directory: /workspace/app

• Shell in Which to Run the Script: Bash

• Script:

  if [ "$ENV" = "production" ]; then
    echo "Running production build"
    npm run build
  else
    echo "Running development build"
    npm run build:dev
  fi

  This configuration evaluates the environment variable and executes the appropriate build command accordingly.

Limitations

• Scripts can become difficult to maintain as complexity increases.
• Requires familiarity with the selected scripting language and shell environment.
• Debugging often relies on log output, which may slow troubleshooting.
• Differences between operating systems and shell implementations can affect script behavior and portability.
• Long or tightly coupled scripts may reduce readability and reuse.

Best Practices

• Keep scripts modular and focused on a single responsibility.
• Add meaningful comments and logging to improve readability and troubleshooting.
• Store scripts in version control to track changes and enable collaboration.
• Validate and test scripts locally before running them in builds.
• Avoid hard-coded values by using environment variables or configuration files.
• Use consistent naming and formatting conventions to improve maintainability.