1. Resources
  2. /
  3. Plugins
  4. /
  5. ssh-buildkite-plugin

SSH Buildkite Plugin

LintingTests
Build status-

This plugin enables pipelines to execute commands or scripts on remote servers via SSH.

To define the commands or scripts that should be executed via SSH, you can configure the commands in your pipeline as if you wanted to execute them on the agent. The plugin overrides the command hook, parses the commands from the pipeline file and executes them on the remote server. The source of a pipeline command can be a command or executable file on the server as well as a command or executable file on the agent. If a command or executable file is available on the server as well as on the agent, the one on the server will be preferred. The option to define scripts and commands that are located on the agent to be executed on the server enables even more reuse of scripts defined by library plugins.

The plugin tries its best to detect errors in the configuration before executing any of the defined commands. The plugin verifies every command and script for its existence on the server and the agent. Also, it sends a test command via SSH to verify that the connection properties are valid.

Example

Single inline command example

steps:
  - command: 'echo "Hello World"'
    env:
      SSH_PRIVATE_KEY: "--- PRIVATE KEY ---"
    plugins:
      - adabay/ssh#v0.9.4:
          server_address: "127.0.0.1"
          username: "admin"
          private_key_env_variable: "SSH_PRIVATE_KEY"

Multiple inline commands example

steps:
  - command:
      - 'echo "Hello World"'
      - 'echo "Hello World 2"'
    env:
      SSH_PRIVATE_KEY: "--- PRIVATE KEY ---"
    plugins:
      - adabay/ssh#v0.9.4:
          server_address: "127.0.0.1"
          username: "admin"
          private_key_env_variable: "SSH_PRIVATE_KEY"

Agent script example

In this example, .buildkite/scripts/hello-world is the path to a script on the agent.

steps:
  - command: '.buildkite/scripts/hello-world'
    env:
      SSH_PRIVATE_KEY: "--- PRIVATE KEY ---"
    plugins:
      - adabay/ssh#v0.9.4:
          server_address: "127.0.0.1"
          username: "admin"
          private_key_env_variable: "SSH_PRIVATE_KEY"

Server script example

In this example, /opt/scripts/hello-world is the path to a script on the server.

steps:
  - command: '/opt/scripts/hello-world'
    env:
      SSH_PRIVATE_KEY: "--- PRIVATE KEY ---"
    plugins:
      - adabay/ssh#v0.9.4:
          server_address: "127.0.0.1"
          username: "admin"
          private_key_env_variable: "SSH_PRIVATE_KEY"

Buildkite library plugin example

In this example, the clean-directory command will be resolved to the script path that belongs to the library plugin adabay/utilities.

steps:
  - command: 'clean-directory /var/www/html'
    env:
      SSH_PRIVATE_KEY: "--- PRIVATE KEY ---"
    plugins:
      - adabay/utilities#master: ~
      - adabay/ssh#v0.9.4:
          server_address: "127.0.0.1"
          username: "admin"
          private_key_env_variable: "SSH_PRIVATE_KEY"

Environment variable injection example

In this example, .buildkite/scripts/hello-world is the path to a script on the agent, and the script depends on an environment variable called TEST. The environment variable TEST from the client is injected into the SSH session, so it’s available when the script is executed on the remote server.

steps:
  - command: '.buildkite/scripts/hello-world'
    env:
      SSH_PRIVATE_KEY: "--- PRIVATE KEY ---"
      TEST: "test"
    plugins:
      - adabay/ssh#v0.9.4:
          server_address: "127.0.0.1"
          username: "admin"
          private_key_env_variable: "SSH_PRIVATE_KEY"
          injected_env_variables:
            - TEST

Configuration

server_address (Required, string)

The ip address or FQDN of the server where the commands should be executed.

username (Required, string)

The username that should be used for the SSH connection.

private_key_env_variable (Required, string)

The name of the environment variable that contains the private key which should be used for authentication with the server.

port (Optional, string)

The server port which should be used for the SSH connection. Defaults to “22”.

injected_env_variables (Optional, array)

A list of names of environment variables that should be injected into the SSH session.

Developing

To run the linter:

docker run -it --rm -v "${PWD}:/plugin:ro" buildkite/plugin-linter --id adabay/ssh

The plugins listed on this webpage are provided for informational purposes only. They have not undergone any formal security review or assessment. While we strive to provide useful resources, we cannot guarantee the safety, reliability, or integrity of these plugins. Users are strongly advised to conduct their own security evaluations before downloading, installing, or using any plugin. By using these plugins, you acknowledge and accept any risks associated with their use. We disclaim any liability for any harm or damages arising from the use of the plugins listed.

Start turning complexity into an advantage

Create an account to get started with a 30-day free trial. No credit card required.

Buildkite Pipelines

Platform

  1. Pipelines
  2. Pipeline templates
  3. Public pipelines
  4. Test Engine
  5. Package Registries
  6. Mobile Delivery Cloud
  7. Pricing

Hosting options

  1. Self-hosted agents
  2. Mac hosted agents
  3. Linux hosted agents

Resources

  1. Docs
  2. Blog
  3. Changelog
  4. Webinars
  5. Plugins
  6. Case studies
  7. Events
  8. Migration Services
  9. Comparisons

Company

  1. About
  2. Careers
  3. Press
  4. Brand assets
  5. Contact

Solutions

  1. Replace Jenkins
  2. Workflows for AI/ML
  3. Testing at scale
  4. Monorepo mojo
  5. Bazel orchestration

Legal

  1. Terms of Service
  2. Acceptable Use Policy
  3. Privacy Policy
  4. Subprocessors
  5. Service Level Agreement

Support

  1. System status
  2. Forum
© Buildkite Pty Ltd 2025