⚠️ This action is not maintained anymore. You can find alternative actions here.

---

SSH

This Github action allows to run commands over SSH.

You can:

• run multiple commands over SSH
• run those commands on multiple hosts
• easily configure the SSH configuration
• or provide your own SSH config both simply or in details

Disclaimer

This Github action is rather young and it might not be as stable and battle-tested as you need: use it at your own risk.

Usage examples

Basic usage

steps:
- name: Run a command remotely
  uses: docker://evaneos/ssh-action:0.1.0
  with:
    hosts: example.com
    user: john-doe
    private_key: ${{ secrets.PRIVATE_SSH_KEY }}
    knock_sequence: ${{ secrets.KNOCK_SEQUENCE }}
    commands: echo "Hello world!"

Alternative usage

steps:
- name: Multiple commands over multiple hosts with custom SSH config
  uses: docker://evaneos/ssh-action:0.1.0
  with:
    hosts: |
        host1.example.com
        host2.example.com
    private_key: ${{ secrets.PRIVATE_SSH_KEY }}
    known_hosts: ${{ secrets.KNOWN_HOSTS }}
    ssh_config: |
      Host host1.example.com
        User your-user1
        ProxyCommand ssh jump-host1.example.com -W %h:%p
      Host host2.example.com
        User your-user2
        ProxyCommand ssh jump-host2.example.com -W %h:%p
    commands: |
      echo "I can run..."
      echo "...multiple commands"

Inputs

Parameter	Required	Description
hosts	Yes	Remote host(s) to connect to
commands	Yes	One or multiple commands to run on the remote host(s)
user	Sometimes	Remote user to connect with
port	Sometimes	Remote port to connect to (default: 22)
private_key	Sometimes	Private SSH key to connect with
password	Sometimes	Password to connect with
known_hosts	No	Known hosts keys that SSH can rely on to connect to the remote hosts
knock_sequence	No	Knock sequence performed onto remote host(s) before connecting to it
ssh_config	No	SSH config to use to connect to remote host(s)

Outputs

No output is generated.

Configuration

Hosts

Specify the remote host(s) - they all must share the same authentication - to run the commands on via the hosts input.

Private SSH key

To authenticate yourself, you can use a private SSH key with the private_key input using a PEM format. The script will dump the SSH private key to ~/.ssh/id_rsa.

Note if you both password and private_key, password will be ignored.

Known hosts

You can specify explicit one or multiple known hosts keys using the known_host input.

When not specifying known_hosts, the option StrictHostKeyChecking=no is added in the ssh_config: in such cases, you are exposing yourself to security risks! ⚠️

Knock sequence

If your remote host needs a knocking sequence (see man knock), you can specify the sequence through the knock_sequence input.

For example, with a knock_sequence of 111 222 333, the action will create an SSH config with a ProxyCommand that will knock the host until it is reachable or will fail after 10 attemps.

You can change this behaviour by specifying your own SSH config (see the SSH config section).

SSH config

To have complete control over the connection behaviour, you can specify a ssh_config input with a compliant SSH config (man ssh_config) which will be dumped as is in ~/.ssh/config.

Beware, the user, port & knock_sequence inputs will be ignored, specify them explicitely in your ssh_config. Also note that you cannot declare the IdentityFile as its location is hard-coded (~/.ssh/id_rsa).

Limitations

Use environment variables

⚠️ You cannot use the env syntax to use environment variables within the command.

This is due to the fact that, for stability and security reasons, environment variables are not passed to the remote host.

You can overcome this issue by declaring them explicitely in the commands input, like so:

steps:
- name: Run commands remotely
  uses: ./.github/workflows/actions/ssh
  with:
    # [...]
    commands: |
      export COMMIT_SHA_1=${{ github.event.pull_request.head.sha }}
      export YOUR_SECRET=${{ secrets.YOUR_SECRET }}

      # [...]

One authentication for every hosts

You cannot have multiple SSH keys or passwords for all the hosts: they must share the same authentication method AND the same credential (i.e. same password or same private_key).

Troubleshooting

"Not a valid RSA private key file"

You need to use a PEM-formatted SSH private key because paramiko, one of the library behind this action, does not support the newest key formats [reference]:

ssh-keygen -t rsa -b 4096 -C "email@email.com" -m PEM