Install SSH Key

This action installs SSH key in ~/.ssh.

Useful for SCP, SFTP, and rsync over SSH in deployment script.

Works on all virtual environment -- Windows, macOS, Ubuntu and Ubuntu 16.04.

Usage

Add your SSH key to your product secrets by clicking Settings - Secrets - Add a new secret beforehand.

NOTE: OPENSSH format (key begins with -----BEGIN OPENSSH PRIVATE KEY-----) may not work due to OpenSSH version on VM. Please use PEM format (begins with -----BEGIN RSA PRIVATE KEY-----) instead.

runs-on: ubuntu-latest
steps:
- name: Install SSH key
  uses: shimataro/ssh-key-action@v1
  with:
    private-key: ${{ secrets.SSH_KEY }}
    name: id_rsa # optional
    known-hosts: ${{ secrets.KNOWN_HOSTS }} # known_hosts; optional
    config: ${{ secrets.CONFIG }} # ssh_config; optional
- name: rsync over ssh
  run: rsync ./foo/ user@remote:bar/

See Workflow syntax for GitHub Actions for details.

Install multiple keys

If you want to install multiple keys, call this action multiple times. It is useful for port forwarding.

NOTE: When this action is called multiple times, the contents of known-hosts and config will be appended. private-key must be saved as different name, by using name option.

runs-on: ubuntu-latest
steps:
- name: Install SSH key of bastion
  uses: shimataro/ssh-key-action@v1
  with:
    private-key: ${{ secrets.SSH_KEY_OF_BASTION }}
    name: id_rsa-bastion
    known-hosts: ${{ secrets.KNOWN_HOSTS_OF_BASTION }}
    config: |
      Host bastion
        HostName xxx.xxx.xxx.xxx
        User user-of-bastion
        IdentityFile ~/.ssh/id_rsa-bastion
- name: Install SSH key of target
  uses: shimataro/ssh-key-action@v1
  with:
    private-key: ${{ secrets.SSH_KEY_OF_TARGET }}
    name: id_rsa-target
    known-hosts: ${{ secrets.KNOWN_HOSTS_OF_TARGET }} # will be appended!
    config: |                                         # will be appended!
      Host target
        HostName yyy.yyy.yyy.yyy
        User user-of-target
        IdentityFile ~/.ssh/id_rsa-target
        ProxyCommand ssh -W %h:%p bastion
- name: SCP via port-forwarding
  run: scp ./foo/ target:bar/

FAQ

SSH failed even though key has been installed.

Check belows:

• Load key "/HOME/.ssh/id_rsa": invalid format:
  • OPENSSH format (key begins with -----BEGIN OPENSSH PRIVATE KEY-----) may not work.
  • Use PEM format (begins with -----BEGIN RSA PRIVATE KEY-----).
• Host key verification failed.:
  • Set known-hosts option or use ssh -o StrictHostKeyChecking=no.
  • The former is HIGHLY recommended for security reason.
  • I'm planning to make known-hosts required in v2.

How do I use encrypted SSH key?

This action doesn't support encrypted key directly. Here are some methods:

• decrypting key beforehand: best bet, and works any VM
• sshpass command: next best bet, but not supported in Windows
• expect command: please be careful not to expose passphrase to console
• SSH_ASKPASS environment variable: it may be troublesome

Which one is the best way for transferring files, "direct SCP/SFTP/rsync" or "SCP/SFTP/rsync via bastion"?

I recommend rsync via bastion. It has some advantages over other methods:

• You only need to use this action only once even if it is necessary to transfer to multiple servers.
  • Other methods require to use it multiple times in order to connect to each servers.
  • Of course, it is necessary to install bastion public key on servers, and server keys on bastion. But you don't have to update workflow files and secrets even if number of servers changed.
• rsync:
  • is faster than others.
  • will NOT break files even if disconnected during transferring.
  • can remove files that don't exist in server.
• SCP is deprecated by OpenSSH due to outdated and inflexible protocol.
• Using bastion is more secure because:
  • it is not necessarily to expose SSH port on servers to public.
  • it requires to shutdown only bastion when security incident ―e.g., private key leaked, GitHub jacked― occurs.

License

The scripts and documentation in this project are released under the MIT License

Changelog

See CHANGELOG.md.