English | 繁體中文 | 简体中文

• 🚀 SSH for GitHub Actions
  • Table of Contents
  • 📖 Introduction
  • 🧩 Core Concepts & Input Parameters
    • 🔌 Connection Settings
    • 🛠️ SSH Command Settings
    • 🌐 Proxy Settings
  • ⚡ Quick Start
  • 🔑 SSH Key Setup & OpenSSH Compatibility
    • Setting Up SSH Keys
      • Generate RSA key
      • Generate ED25519 key
    • OpenSSH Compatibility
  • 🛠️ Usage Scenarios & Advanced Examples
    • Using password authentication
    • Using private key authentication
    • Multiple commands
    • Run commands from a file
    • Multiple hosts
    • Multiple hosts with different ports
    • Synchronous execution on multiple hosts
    • Pass environment variables to shell script
  • 🌐 Proxy & Jump Host Usage
  • 🛡️ Security Best Practices
    • Protecting Your Private Key
    • Host Fingerprint Verification
  • 🚨 Error Handling & Troubleshooting
    • Q&A
      • Command not found (npm or other command)
  • 🤝 Contributing
  • 📝 License

SSH for GitHub Actions is a powerful GitHub Action for executing remote SSH commands easily and securely in your CI/CD workflows.
Built with Golang and drone-ssh, it supports a wide range of SSH scenarios, including multi-host, proxy, and advanced authentication.

This action provides flexible SSH command execution with a rich set of configuration options.

For full details, see action.yml.

These parameters control how the action connects to your remote host.

These parameters control the commands executed on the remote host and related behaviors.

These parameters control the use of a proxy (jump host) for connecting to your target host.

Note: To mimic the removed script_stop option, add set -e at the top of your shell script.

Run remote SSH commands in your workflow with minimal configuration:

name: Remote SSH Command on: [push] jobs: build: name: Build runs-on: ubuntu-latest steps: - name: Execute remote SSH commands using password uses: appleboy/ssh-action@v1 with: host: ${{ secrets.HOST }} username: linuxserver.io password: ${{ secrets.PASSWORD }} port: ${{ secrets.PORT }} script: whoami

Output:

======CMD====== whoami ======END====== linuxserver.io =============================================== ✅ Successfully executed commands to all hosts. ===============================================

It is best practice to create SSH keys on your local machine (not on a remote server). Log in with the username specified in GitHub Secrets and generate a key pair:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"

Add the new public key to the authorized keys on your server. Learn more about authorized keys.

# Add RSA key cat .ssh/id_rsa.pub | ssh user@host 'cat >> .ssh/authorized_keys' # Add ED25519 key cat .ssh/id_ed25519.pub | ssh user@host 'cat >> .ssh/authorized_keys'

Copy the private key content and paste it into GitHub Secrets.

# macOS pbcopy < ~/.ssh/id_rsa # Ubuntu xclip < ~/.ssh/id_rsa

Tip: Copy from -----BEGIN OPENSSH PRIVATE KEY----- to -----END OPENSSH PRIVATE KEY----- (inclusive).

For ED25519:

# macOS pbcopy < ~/.ssh/id_ed25519 # Ubuntu xclip < ~/.ssh/id_ed25519

See more: SSH login without a password.

Note: Depending on your SSH version, you may also need to:

• Place the public key in .ssh/authorized_keys2
• Set .ssh permissions to 700
• Set .ssh/authorized_keys2 permissions to 640

If you see this error:

ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey]

On Ubuntu 20.04+ you may need to explicitly allow the ssh-rsa algorithm. Add this to your OpenSSH daemon config (/etc/ssh/sshd_config or a drop-in under /etc/ssh/sshd_config.d/):

CASignatureAlgorithms +ssh-rsa

Alternatively, use ED25519 keys (supported by default):

ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"

This section covers common and advanced usage patterns, including multi-host, proxy, and environment variable passing.

- name: Execute remote SSH commands using password uses: appleboy/ssh-action@v1 with: host: ${{ secrets.HOST }} username: ${{ secrets.USERNAME }} password: ${{ secrets.PASSWORD }} port: ${{ secrets.PORT }} script: whoami

- name: Execute remote SSH commands using SSH key uses: appleboy/ssh-action@v1 with: host: ${{ secrets.HOST }} username: ${{ secrets.USERNAME }} key: ${{ secrets.KEY }} port: ${{ secrets.PORT }} script: whoami

- name: Multiple commands uses: appleboy/ssh-action@v1 with: host: ${{ secrets.HOST }} username: ${{ secrets.USERNAME }} key: ${{ secrets.KEY }} port: ${{ secrets.PORT }} script: |  whoami  ls -al

- name: File commands uses: appleboy/ssh-action@v1 with: host: ${{ secrets.HOST }} username: ${{ secrets.USERNAME }} key: ${{ secrets.KEY }} port: ${{ secrets.PORT }} script_path: scripts/script.sh

 - name: Multiple hosts uses: appleboy/ssh-action@v1 with: - host: "foo.com" + host: "foo.com,bar.com" username: ${{ secrets.USERNAME }} key: ${{ secrets.KEY }} port: ${{ secrets.PORT }} script: | whoami ls -al

Default port is 22.

 - name: Multiple hosts uses: appleboy/ssh-action@v1 with: - host: "foo.com" + host: "foo.com:1234,bar.com:5678" username: ${{ secrets.USERNAME }} key: ${{ secrets.KEY }} script: | whoami ls -al

 - name: Multiple hosts uses: appleboy/ssh-action@v1 with: host: "foo.com,bar.com" + sync: true username: ${{ secrets.USERNAME }} key: ${{ secrets.KEY }} port: ${{ secrets.PORT }} script: | whoami ls -al

 - name: Pass environment uses: appleboy/ssh-action@v1 + env: + FOO: "BAR" + BAR: "FOO" + SHA: ${{ github.sha }} with: host: ${{ secrets.HOST }} username: ${{ secrets.USERNAME }} key: ${{ secrets.KEY }} port: ${{ secrets.PORT }} + envs: FOO,BAR,SHA script: | echo "I am $FOO" echo "I am $BAR" echo "sha: $SHA"

All environment variables in the env object must be strings. Using integers or other types may cause unexpected results.

You can connect to remote hosts via a proxy (jump host) for advanced network topologies.

+--------+ +----------+ +-----------+ | Laptop | <--> | Jumphost | <--> | FooServer | +--------+ +----------+ +-----------+

Example ~/.ssh/config:

Host Jumphost HostName Jumphost User ubuntu Port 22 IdentityFile ~/.ssh/keys/jump_host.pem Host FooServer HostName FooServer User ubuntu Port 22 ProxyCommand ssh -q -W %h:%p Jumphost

GitHub Actions YAML:

 - name: SSH proxy command uses: appleboy/ssh-action@v1 with: host: ${{ secrets.HOST }} username: ${{ secrets.USERNAME }} key: ${{ secrets.KEY }} port: ${{ secrets.PORT }} + proxy_host: ${{ secrets.PROXY_HOST }} + proxy_username: ${{ secrets.PROXY_USERNAME }} + proxy_key: ${{ secrets.PROXY_KEY }} + proxy_port: ${{ secrets.PROXY_PORT }} script: | mkdir abc/def ls -al

A passphrase encrypts your private key, making it useless to attackers if leaked. Always store your private key securely.

 - name: SSH key passphrase uses: appleboy/ssh-action@v1 with: host: ${{ secrets.HOST }} username: ${{ secrets.USERNAME }} key: ${{ secrets.KEY }} port: ${{ secrets.PORT }} + passphrase: ${{ secrets.PASSPHRASE }} script: | whoami ls -al

Verifying the SSH host fingerprint helps prevent man-in-the-middle attacks. To get your host's fingerprint (replace ed25519 with your key type and example.com with your host):

ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' ' -f2

Update your config:

 - name: SSH key passphrase uses: appleboy/ssh-action@v1 with: host: ${{ secrets.HOST }} username: ${{ secrets.USERNAME }} key: ${{ secrets.KEY }} port: ${{ secrets.PORT }} + fingerprint: ${{ secrets.FINGERPRINT }} script: | whoami ls -al

If you encounter "command not found" errors, see this issue comment about interactive vs non-interactive shells.

On many Linux distros, /etc/bash.bashrc contains:

# If not running interactively, don't do anything [ -z "$PS1" ] && return

Comment out this line or use absolute paths for your commands.

Contributions are welcome! Please submit a pull request to help improve appleboy/ssh-action.

This project is licensed under the MIT License.