Install Extra Tools at Run Start

When a workflow needs a tool that your agent image doesn’t ship (PowerShell, a specific linter, an internal CLI), you don’t have to register a custom image. Add a Run Script step as the first step of the workflow and install the tool there. Every later step in the same run, including agent steps and the scripts your skills call, can then use it.

How it works

All steps in a run execute in the same container. Anything a setup step installs stays available until the run ends:

Run Script steps, agent shell commands, skill scripts, and stdio MCP servers all run in that container.
On the system images (Universal and Universal 6), the run user has passwordless sudo, so you can use apt-get, write to /usr/local/bin, and install global packages.
The home directory persists across steps. Environment changes such as export PATH=... do not, because each step starts a new shell. Put binaries on the default PATH (for example, symlink them into /usr/local/bin) instead of exporting variables.

The tool is installed again on every run, so the setup step adds its install time to each run. When a tool takes minutes to install or you need it in many workflows, consider a custom agent image instead.

Add a setup step

Add a Run Script step first

In Workflow Builder, add a Run Script action and connect it as the first step, before the steps that need the tool.

Install the tool

In Bash Script, install the tool and place it on the default PATH. Start with set -euo pipefail so a failed install fails the run immediately instead of surfacing later as command not found.

Verify the install

End the script with a version check, such as pwsh --version. The output appears in the step’s run log.

Example: PowerShell 7

Download the official PowerShell release for Linux, extract it, and link pwsh onto the default PATH so every later step can use it. The install takes about 15 seconds and doesn’t depend on any SDK in the image.

steps:
  - id: "setup-tools"
    name: "Setup Tools"
    action: "script.run"
    params:
      timeoutSeconds: 600
      script: |
        set -euo pipefail
        PWSH_VERSION=7.5.4
        curl -fsSL -o /tmp/pwsh.tar.gz \
          "https://github.com/PowerShell/PowerShell/releases/download/v${PWSH_VERSION}/powershell-${PWSH_VERSION}-linux-x64.tar.gz"
        sudo mkdir -p /opt/microsoft/powershell/7
        sudo tar -xzf /tmp/pwsh.tar.gz -C /opt/microsoft/powershell/7
        sudo chmod +x /opt/microsoft/powershell/7/pwsh
        sudo ln -sf /opt/microsoft/powershell/7/pwsh /usr/local/bin/pwsh
        pwsh --version

  - id: "remediate-packages"
    name: "Remediate Packages"
    action: "agent.run"
    instruction: |
      Use the package-sca-remediation skill to find the next approved package versions.

Skills and later steps can now call PowerShell scripts directly, for example pwsh -NoProfile -File ./scripts/Find-NextApprovedPackage.ps1. Pin PWSH_VERSION to the release you want and update it when you upgrade.

Other tools

The same pattern works for any package manager available in the image:

set -euo pipefail

# OS packages
sudo apt-get update -qq
sudo apt-get install -y -qq jq shellcheck

# Node.js CLIs
npm install --global @redocly/cli

# Python CLIs
pip install --user yamllint
sudo ln -sf "$HOME/.local/bin/yamllint" /usr/local/bin/yamllint

# Standalone binaries
curl -fsSL -o /tmp/tool.tar.gz "https://example.com/releases/tool-linux-amd64.tar.gz"
sudo tar -xzf /tmp/tool.tar.gz -C /usr/local/bin tool

Keep the tool list in your repository

To let each team manage its own tools, commit a setup script to the repository and run it from the workflow. Clone the repository first, then run the script from the cloned folder:

steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "{{trigger.repository.fullName}}"

  - id: "setup-tools"
    name: "Setup Tools"
    action: "script.run"
    params:
      cwd: "{{outputs.clone-repo.workspacePath}}"
      script: |
        set -euo pipefail
        if [ -f .overcut/setup.sh ]; then
          bash .overcut/setup.sh
        else
          echo "No .overcut/setup.sh found, skipping tool setup"
        fi

Adding a tool is then a pull request to .overcut/setup.sh, with no workflow change.

Things to know

Network access. The setup step downloads packages, so the run needs access to the package source (NuGet, apt mirrors, npm, PyPI, or your internal registry). For private registries, attach a secret from the Vault and read it as an environment variable in the script.
Custom images. On a custom agent image, sudo and package managers are only available if your image provides them. Without sudo, install into the home directory and call the tool by its full path.
Timeouts. Large installs can exceed the default timeout. Raise Timeout Seconds (optional) on the setup step if needed.

Run Script Action: Configuration fields, environment variables, and failure behavior.
Agent Images: Register an image when a toolchain is too large to install on every run.
Git Clone Action: Clone the repository before running a repository-owned setup script.

Get Started

Concepts

Quick Starts

Security & Compliance

Workflows and Actions

Orchestrations

Reference

Integrations

Repositories

Install Extra Tools at Run Start

How it works

Add a setup step

Example: PowerShell 7

Other tools

Keep the tool list in your repository

Things to know

​How it works

​Add a setup step

​Example: PowerShell 7

​Other tools

​Keep the tool list in your repository

​Things to know

​Related documentation

How it works

Add a setup step

Example: PowerShell 7

Other tools

Keep the tool list in your repository

Things to know

Related documentation