appleboy/ssh-action

Use an SSH Key Passphrase

If your private key is encrypted, provide the passphrase using the passphrase input.

Verify Host Fingerprint

To prevent man-in-the-middle attacks, verify the host's fingerprint using the fingerprint input. You can obtain the fingerprint for your host using: ssh <hostname> ssh-keygen -l -f /etc/ssh/ssh_host_<type>_key.pub | cut -d ' ' -f2

  - 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

You can execute multiple commands by using a multi-line string in the script input, or by pointing to a script file using the script_path input.

Using multi-line script:

script: |
  whoami
  ls -al

Using a script file:

script_path: scripts/script.sh

- 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

To run commands on multiple hosts, provide a comma-separated list to the host input. You can also specify different ports for each host using the host:port format.

Multiple hosts (default port 22): host: "foo.com,bar.com"

Multiple hosts with custom ports: host: "foo.com:1234,bar.com:5678"

Synchronous execution: By default, commands run on multiple hosts in parallel. To run them synchronously (one after another), set sync: true.

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

To make GitHub Actions environment variables available to your remote SSH script, you must perform two steps:

1. Define the variables in the env block of the step.
2. List the names of the variables to be passed in the envs input (comma-separated string).

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

  - 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"

To execute a remote command using password authentication, use the appleboy/ssh-action@v1 in your GitHub Actions workflow. You must provide the host, username, password, and optionally the port (defaults to 22).

name: Remote SSH Command
on: [push]
jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: 执行远程 SSH 命令（密码认证）
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USERNAME }}
          password: ${{ secrets.PASSWORD }}
          port: ${{ secrets.PORT }}
          script: whoami

You can authenticate to remote hosts using either a password or a private key. When using a password, provide the password input. When using a key, provide the key input.

# Password Authentication
- name: Execute remote SSH command (Password)
  uses: appleboy/ssh-action@v1
  with:
    host: ${{ secrets.HOST }}
    username: ${{ secrets.USERNAME }}
    password: ${{ secrets.PASSWORD }}
    port: ${{ secrets.PORT }}
    script: whoami

# Private Key Authentication
- name: Execute remote SSH command (Private Key)
  uses: appleboy/ssh-action@v1
  with:
    host: ${{ secrets.HOST }}
    username: ${{ secrets.USERNAME }}
    key: ${{ secrets.KEY }}
    port: ${{ secrets.PORT }}
    script: whoami

To connect to a remote host through a jump host (proxy), use the proxy_host, proxy_username, proxy_key, and proxy_port inputs.

- 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

To connect to a remote host through a proxy or jump host, provide the proxy connection details using the following parameters:

• proxy_host
• proxy_username
• proxy_key
• proxy_port

- 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

To connect to a remote host through a proxy or jump host, provide the proxy connection details using the following inputs:

• proxy_host
• proxy_username
• proxy_key
• proxy_port

  - 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

To use private key authentication, generate a key pair locally and add the public key to the remote server's authorized_keys file.

Generate RSA Key:

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

Generate ED25519 Key:

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

Add Public Key to Server:

# For RSA
cat .ssh/id_rsa.pub | ssh user@host 'cat >> .ssh/authorized_keys'

# For ED25519
cat .ssh/id_ed25519.pub | ssh user@host 'cat >> .ssh/authorized_keys'

Copy Private Key to GitHub Secrets: Copy the entire content, including the -----BEGIN ...----- and -----END ...----- lines.

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

For secure authentication, use SSH keys instead of passwords.

1. Generate Keys: Use ssh-keygen locally.
   • RSA: ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
   • ED25519: ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
2. Add Public Key to Server: Append the .pub content to the server's ~/.ssh/authorized_keys file.
3. Add Private Key to GitHub: Copy the entire content of the private key (including -----BEGIN ...----- and -----END ...-----) and save it as a GitHub Secret.

To use environment variables within your remote script, you must define them in the env block of the step and then list their names in the envs input parameter.

Note: All values in the env object must be strings. Passing integers or other types may cause unexpected results.

- name: Pass environment variables
  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"