dd0f09ca07
- Update the README table formatting to include an additional column separator - Add documentation for the SSH protocol version option in the README table Signed-off-by: Bo-Yi Wu <appleboy.tw@gmail.com>
405 lines
14 KiB
Markdown
405 lines
14 KiB
Markdown
# 🚀 SSH for GitHub Actions
|
||
|
||
[繁體中文](./README.zh-tw.md)
|
||
|
||
[GitHub Action](https://github.com/features/actions) for executing remote ssh commands.
|
||
|
||
|
||
|
||
[](https://github.com/appleboy/ssh-action/actions)
|
||
|
||
**Important**: Only support **Linux** [docker](https://www.docker.com/) container.
|
||
|
||
This thing is built using [Golang](https://go.dev) and [drone-ssh](https://github.com/appleboy/drone-ssh). 🚀
|
||
|
||
## Input variables
|
||
|
||
See [action.yml](./action.yml) for more detailed information.
|
||
|
||
| Input Parameter | Description | Default Value |
|
||
|---------------------------|------------------------------------------------------------------------------------------|---------------|
|
||
| host | SSH host address | |
|
||
| port | SSH port number | 22 |
|
||
| passphrase | SSH key passphrase | |
|
||
| username | SSH username | |
|
||
| password | SSH password | |
|
||
| protocol | SSH protocol version (tcp, tcp4, tcp6) | tcp |
|
||
| sync | Enable synchronous execution if multiple hosts | false |
|
||
| use_insecure_cipher | Include more ciphers with use_insecure_cipher | false |
|
||
| cipher | Allowed cipher algorithms. If unspecified, a sensible default | |
|
||
| timeout | Timeout duration for SSH to host | 30s |
|
||
| command_timeout | Timeout duration for SSH command | 10m |
|
||
| key | Content of SSH private key. e.g., raw content of ~/.ssh/id_rsa | |
|
||
| key_path | Path of SSH private key | |
|
||
| fingerprint | SHA256 fingerprint of the host public key | |
|
||
| proxy_host | SSH proxy host | |
|
||
| proxy_port | SSH proxy port | 22 |
|
||
| proxy_username | SSH proxy username | |
|
||
| proxy_password | SSH proxy password | |
|
||
| proxy_passphrase | SSH proxy key passphrase | |
|
||
| proxy_timeout | Timeout for SSH to proxy host | 30s |
|
||
| proxy_key | Content of SSH proxy private key | |
|
||
| proxy_key_path | Path of SSH proxy private key | |
|
||
| proxy_fingerprint | SHA256 fingerprint of the proxy host public key | |
|
||
| proxy_cipher | Allowed cipher algorithms for the proxy | |
|
||
| proxy_use_insecure_cipher | Include more ciphers with use_insecure_cipher for the proxy | false |
|
||
| script | Execute commands | |
|
||
| script_stop | Stop script after first failure | false |
|
||
| envs | Pass environment variables to shell script | |
|
||
| envs_format | Flexible configuration of environment value transfer | |
|
||
| debug | Enable debug mode | false |
|
||
| allenvs | pass the environment variables with prefix value of `GITHUB_` and `INPUT_` to the script | false |
|
||
| request_pty | Request a pseudo-terminal from the server | false |
|
||
|
||
## Usage
|
||
|
||
Executing remote ssh commands.
|
||
|
||
```yaml
|
||
name: remote ssh command
|
||
on: [push]
|
||
jobs:
|
||
|
||
build:
|
||
name: Build
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- name: executing remote ssh commands using password
|
||
uses: appleboy/ssh-action@v1.0.3
|
||
with:
|
||
host: ${{ secrets.HOST }}
|
||
username: ${{ secrets.USERNAME }}
|
||
password: ${{ secrets.PASSWORD }}
|
||
port: ${{ secrets.PORT }}
|
||
script: whoami
|
||
```
|
||
|
||
output:
|
||
|
||
```sh
|
||
======CMD======
|
||
whoami
|
||
======END======
|
||
out: ***
|
||
==============================================
|
||
✅ Successfully executed commands to all host.
|
||
==============================================
|
||
```
|
||
|
||
### Setting up a SSH Key
|
||
|
||
Make sure to follow the below steps while creating SSH Keys and using them.
|
||
The best practice is create the SSH Keys on local machine not remote machine.
|
||
Login with username specified in Github Secrets. Generate a RSA Key-Pair:
|
||
|
||
### Generate rsa key
|
||
|
||
```bash
|
||
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
|
||
```
|
||
|
||
### Generate ed25519 key
|
||
|
||
```bash
|
||
ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
||
```
|
||
|
||
Add newly generated key into Authorized keys. Read more about authorized keys [here](https://www.ssh.com/ssh/authorized_keys/).
|
||
|
||
### Add rsa key into Authorized keys
|
||
|
||
```bash
|
||
cat .ssh/id_rsa.pub | ssh b@B 'cat >> .ssh/authorized_keys'
|
||
```
|
||
|
||
### Add ed25519 key into Authorized keys
|
||
|
||
```bash
|
||
cat .ssh/id_ed25519.pub | ssh b@B 'cat >> .ssh/authorized_keys'
|
||
```
|
||
|
||
Copy Private Key content and paste in Github Secrets.
|
||
|
||
### Copy rsa Private key
|
||
|
||
```bash
|
||
clip < ~/.ssh/id_rsa
|
||
```
|
||
|
||
### Copy ed25519 Private key
|
||
|
||
```bash
|
||
clip < ~/.ssh/id_ed25519
|
||
```
|
||
|
||
See the detail information about [SSH login without password](http://www.linuxproblem.org/art_9.html).
|
||
|
||
**A note** from one of our readers: Depending on your version of SSH you might also have to do the following changes:
|
||
|
||
* Put the public key in `.ssh/authorized_keys2`
|
||
* Change the permissions of `.ssh` to 700
|
||
* Change the permissions of `.ssh/authorized_keys2` to 640
|
||
|
||
### If you are using OpenSSH
|
||
|
||
If you are currently using OpenSSH and are getting the following error:
|
||
|
||
```bash
|
||
ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey]
|
||
```
|
||
|
||
Make sure that your key algorithm of choice is supported. On Ubuntu 20.04 or later you must explicitly allow the use of the ssh-rsa algorithm. Add the following line to your OpenSSH daemon file (which is either `/etc/ssh/sshd_config` or a drop-in file under `/etc/ssh/sshd_config.d/`):
|
||
|
||
```bash
|
||
CASignatureAlgorithms +ssh-rsa
|
||
```
|
||
|
||
Alternatively, `ed25519` keys are accepted by default in OpenSSH. You could use this instead of rsa if needed:
|
||
|
||
```bash
|
||
ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
||
```
|
||
|
||
### Example
|
||
|
||
#### Executing remote ssh commands using password
|
||
|
||
```yaml
|
||
- name: executing remote ssh commands using password
|
||
uses: appleboy/ssh-action@v1.0.3
|
||
with:
|
||
host: ${{ secrets.HOST }}
|
||
username: ${{ secrets.USERNAME }}
|
||
password: ${{ secrets.PASSWORD }}
|
||
port: ${{ secrets.PORT }}
|
||
script: whoami
|
||
```
|
||
|
||
#### Using private key
|
||
|
||
```yaml
|
||
- name: executing remote ssh commands using ssh key
|
||
uses: appleboy/ssh-action@v1.0.3
|
||
with:
|
||
host: ${{ secrets.HOST }}
|
||
username: ${{ secrets.USERNAME }}
|
||
key: ${{ secrets.KEY }}
|
||
port: ${{ secrets.PORT }}
|
||
script: whoami
|
||
```
|
||
|
||
#### Multiple Commands
|
||
|
||
```yaml
|
||
- name: multiple command
|
||
uses: appleboy/ssh-action@v1.0.3
|
||
with:
|
||
host: ${{ secrets.HOST }}
|
||
username: ${{ secrets.USERNAME }}
|
||
key: ${{ secrets.KEY }}
|
||
port: ${{ secrets.PORT }}
|
||
script: |
|
||
whoami
|
||
ls -al
|
||
```
|
||
|
||
|
||
|
||
#### Multiple Hosts
|
||
|
||
```diff
|
||
- name: multiple host
|
||
uses: appleboy/ssh-action@v1.0.3
|
||
with:
|
||
- host: "foo.com"
|
||
+ host: "foo.com,bar.com"
|
||
username: ${{ secrets.USERNAME }}
|
||
key: ${{ secrets.KEY }}
|
||
port: ${{ secrets.PORT }}
|
||
script: |
|
||
whoami
|
||
ls -al
|
||
```
|
||
|
||
#### Multiple hosts with different port
|
||
|
||
```diff
|
||
- name: multiple host
|
||
uses: appleboy/ssh-action@v1.0.3
|
||
with:
|
||
- host: "foo.com"
|
||
+ host: "foo.com:1234,bar.com:5678"
|
||
username: ${{ secrets.USERNAME }}
|
||
key: ${{ secrets.KEY }}
|
||
script: |
|
||
whoami
|
||
ls -al
|
||
```
|
||
|
||
#### Synchronous execution on multiple hosts
|
||
|
||
```diff
|
||
- name: multiple host
|
||
uses: appleboy/ssh-action@v1.0.3
|
||
with:
|
||
host: "foo.com,bar.com"
|
||
+ sync: true
|
||
username: ${{ secrets.USERNAME }}
|
||
key: ${{ secrets.KEY }}
|
||
port: ${{ secrets.PORT }}
|
||
script: |
|
||
whoami
|
||
ls -al
|
||
```
|
||
|
||
#### Pass environment variable to shell script
|
||
|
||
```diff
|
||
- name: pass environment
|
||
uses: appleboy/ssh-action@v1.0.3
|
||
+ 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"
|
||
```
|
||
|
||
_Inside `env` object, you need to pass every environment variable as a string, passing `Integer` data type or any other may output unexpected results._
|
||
|
||
#### Stop script after first failure
|
||
|
||
> ex: missing `abc` folder
|
||
|
||
```diff
|
||
- name: stop script if command error
|
||
uses: appleboy/ssh-action@v1.0.3
|
||
with:
|
||
host: ${{ secrets.HOST }}
|
||
username: ${{ secrets.USERNAME }}
|
||
key: ${{ secrets.KEY }}
|
||
port: ${{ secrets.PORT }}
|
||
+ script_stop: true
|
||
script: |
|
||
mkdir abc/def
|
||
ls -al
|
||
```
|
||
|
||
output:
|
||
|
||
```sh
|
||
======CMD======
|
||
mkdir abc/def
|
||
ls -al
|
||
|
||
======END======
|
||
2019/11/21 01:16:21 Process exited with status 1
|
||
err: mkdir: cannot create directory ‘abc/def’: No such file or directory
|
||
##[error]Docker run failed with exit code 1
|
||
```
|
||
|
||
#### How to connect remote server using `ProxyCommand`?
|
||
|
||
```bash
|
||
+--------+ +----------+ +-----------+
|
||
| Laptop | <--> | Jumphost | <--> | FooServer |
|
||
+--------+ +----------+ +-----------+
|
||
```
|
||
|
||
in your `~/.ssh/config`, you will see the following.
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
#### How to convert to YAML format of GitHubActions
|
||
|
||
```diff
|
||
- name: ssh proxy command
|
||
uses: appleboy/ssh-action@v1.0.3
|
||
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
|
||
```
|
||
|
||
#### Protecting a Private Key
|
||
|
||
The purpose of the passphrase is usually to encrypt the private key.
|
||
This makes the key file by itself useless to an attacker.
|
||
It is not uncommon for files to leak from backups or decommissioned hardware, and hackers commonly exfiltrate files from compromised systems.
|
||
|
||
```diff
|
||
- name: ssh key passphrase
|
||
uses: appleboy/ssh-action@v1.0.3
|
||
with:
|
||
host: ${{ secrets.HOST }}
|
||
username: ${{ secrets.USERNAME }}
|
||
key: ${{ secrets.KEY }}
|
||
port: ${{ secrets.PORT }}
|
||
+ passphrase: ${{ secrets.PASSPHRASE }}
|
||
script: |
|
||
whoami
|
||
ls -al
|
||
```
|
||
|
||
#### Using host fingerprint verification
|
||
|
||
Setting up SSH host fingerprint verification can help to prevent Person-in-the-Middle attacks. Before setting this up, run the command below to get your SSH host fingerprint. Remember to replace `ed25519` with your appropriate key type (`rsa`, `dsa`, etc.) that your server is using and `example.com` with your host.
|
||
|
||
In modern OpenSSH releases, the _default_ key types to be fetched are `rsa` (since version 5.1), `ecdsa` (since version 6.0), and `ed25519` (since version 6.7).
|
||
|
||
```sh
|
||
ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' ' -f2
|
||
```
|
||
|
||
Now you can adjust you config:
|
||
|
||
```diff
|
||
- name: ssh key passphrase
|
||
uses: appleboy/ssh-action@v1.0.3
|
||
with:
|
||
host: ${{ secrets.HOST }}
|
||
username: ${{ secrets.USERNAME }}
|
||
key: ${{ secrets.KEY }}
|
||
port: ${{ secrets.PORT }}
|
||
+ fingerprint: ${{ secrets.FINGERPRINT }}
|
||
script: |
|
||
whoami
|
||
ls -al
|
||
```
|
||
|
||
## Contributing
|
||
|
||
We would love for you to contribute to `appleboy/ssh-action`, pull requests are welcome!
|
||
|
||
## License
|
||
|
||
The scripts and documentation in this project are released under the [MIT License](LICENSE)
|