actions/ssh-action
1
0
Fork 0
mirror of https://github.com/appleboy/ssh-action.git synced 2025-06-20 16:42:10 +10:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: rewrite and unify documentation across all supported languages

Browse source 
- Rewrite and reorganize documentation for clarity and readability, including reworded introductions and consistent headings.
- Improve input parameter tables: clarify descriptions, unify formatting, and better explain parameter purposes across all three languages.
- Expand and update step-by-step SSH key setup guides, streamline copy instructions, and add practical notes and tips.
- Enhance usage examples with clearer titles, better labels, and updated YAML examples for different authentication methods and scenarios.
- Add new sections and tips on OpenSSH compatibility and troubleshooting "command not found" issues, with improved cross-platform guidance.
- Refine explanations for host fingerprint verification, proxy setup, and command environment management.
- Update and polish contributing and license sections for greater encouragement and style consistency.
- Apply the above documentation improvements to both Simplified and Traditional Chinese versions for parity.

Signed-off-by: appleboy <appleboy.tw@gmail.com>
This commit is contained in:
appleboy 2025-04-27 09:47:26 +08:00
parent 0e19dd962d
commit b80f638dc4
No known key found for this signature in database
3 changed files with 384 additions and 351 deletions
Download patch file Download diff file Expand all files Collapse all files

265
README.md
View file

@ -2,71 +2,75 @@
English | [繁體中文](./README.zh-tw.md) | [简体中文](./README.zh-cn.md)
A [GitHub Action](https://github.com/features/actions) for executing remote SSH commands.
A [GitHub Action](https://github.com/features/actions) for executing remote SSH commands easily and securely.
![ssh workflow](./images/ssh-workflow.png)
[![testing main branch](https://github.com/appleboy/ssh-action/actions/workflows/main.yml/badge.svg)](https://github.com/appleboy/ssh-action/actions/workflows/main.yml)
This project is built with [Golang](https://go.dev) and [drone-ssh](https://github.com/appleboy/drone-ssh). 🚀
This project is built with [Golang](https://go.dev) and [drone-ssh](https://github.com/appleboy/drone-ssh).
## Input variables
---
Refer to [action.yml](./action.yml) for more detailed information.
## 📥 Input Parameters
| 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 are specified | false |
| use_insecure_cipher | Include more ciphers with use_insecure_cipher | false |
| cipher | Allowed cipher algorithms. If unspecified, sensible defaults are used | |
| 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_protocol | SSH proxy protocol version (tcp, tcp4, tcp6) | tcp |
| 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_path | Execute commands from a file | |
| envs | Pass environment variables to the 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 |
| curl_insecure | Allow curl to connect to SSL sites without certificates | false |
| version | drone-ssh binary version. If not specified, the latest version will be used. | |
For full details, see [action.yml](./action.yml).
**Note:** Users can add `set -e` in their shell script to achieve similar functionality to the removed `script_stop` option.
| Parameter | Description | Default |
| ------------------------- | --------------------------------------------------------------------------------- | ------- |
| host | SSH host address | |
| port | SSH port number | 22 |
| passphrase | Passphrase for the SSH private key | |
| username | SSH username | |
| password | SSH password | |
| protocol | SSH protocol version (`tcp`, `tcp4`, `tcp6`) | tcp |
| sync | Run synchronously if multiple hosts are specified | false |
| use_insecure_cipher | Allow additional (less secure) ciphers | false |
| cipher | Allowed cipher algorithms. Uses sensible defaults if unspecified | |
| timeout | Timeout for SSH connection to host | 30s |
| command_timeout | Timeout for SSH command execution | 10m |
| key | Content of SSH private key (e.g., raw content of `~/.ssh/id_rsa`) | |
| key_path | Path to SSH private key | |
| fingerprint | SHA256 fingerprint of the host public key | |
| proxy_host | SSH proxy host | |
| proxy_port | SSH proxy port | 22 |
| proxy_protocol | SSH proxy protocol version (`tcp`, `tcp4`, `tcp6`) | tcp |
| proxy_username | SSH proxy username | |
| proxy_password | SSH proxy password | |
| proxy_passphrase | SSH proxy key passphrase | |
| proxy_timeout | Timeout for SSH connection to proxy host | 30s |
| proxy_key | Content of SSH proxy private key | |
| proxy_key_path | Path to 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 | Allow additional (less secure) ciphers for the proxy | false |
| script | Commands to execute remotely | |
| script_path | Path to a file containing commands to execute | |
| envs | Environment variables to pass to the shell script | |
| envs_format | Flexible configuration for environment variable transfer | |
| debug | Enable debug mode | false |
| allenvs | Pass all environment variables with `GITHUB_` and `INPUT_` prefixes to the script | false |
| request_pty | Request a pseudo-terminal from the server | false |
| curl_insecure | Allow curl to connect to SSL sites without certificates | false |
| version | drone-ssh binary version. If not specified, the latest version will be used. | |
## Usage
> **Note:** To mimic the removed `script_stop` option, add `set -e` at the top of your shell script.
Executing remote SSH commands.
---
## 🚦 Usage Example
Run remote SSH commands in your workflow:
```yaml
name: remote ssh command
name: Remote SSH Command
on: [push]
jobs:
build:
name: Build
runs-on: ubuntu-latest
steps:
- name: executing remote ssh commands using password
- name: Execute remote SSH commands using password
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.HOST }}
@ -76,7 +80,7 @@ jobs:
script: whoami
```
output:
**Output:**
```sh
======CMD======
@ -88,50 +92,35 @@ linuxserver.io
===============================================
```
### Setting up a SSH Key
---
Follow the steps below to create and use SSH Keys.
It is best practice to create SSH Keys on your local machine, not on a remote machine.
Log in with the username specified in GitHub Secrets and generate an RSA Key-Pair:
## 🔑 Setting Up SSH Keys
### Generate rsa key
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:
### Generate RSA key
```bash
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
```
### Generate ed25519 key
### Generate ED25519 key
```bash
ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
```
Add the newly generated key to the Authorized keys. Read more about authorized keys [here](https://www.ssh.com/ssh/authorized_keys/).
### Add rsa key into Authorized keys
Add the new public key to the authorized keys on your server. [Learn more about authorized keys.](https://www.ssh.com/ssh/authorized_keys/)
```bash
cat .ssh/id_rsa.pub | ssh b@B 'cat >> .ssh/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'
```
### Add ed25519 key into Authorized keys
```bash
cat .ssh/id_ed25519.pub | ssh b@B 'cat >> .ssh/authorized_keys'
```
Copy the Private Key content and paste it into GitHub Secrets.
### Copy rsa Private key
Before copying the private key, install the `clip` command as shown below:
```bash
# Ubuntu
sudo apt-get install xclip
```
Copy the private key:
Copy the private key content and paste it into GitHub Secrets.
```bash
# macOS
@ -140,9 +129,9 @@ pbcopy < ~/.ssh/id_rsa
xclip < ~/.ssh/id_rsa
```
Starting from and including the comment section `-----BEGIN OPENSSH PRIVATE KEY-----` and ending at and including the comment section `-----END OPENSSH PRIVATE KEY-----`, copy the private key and paste it into GitHub Secrets.
> **Tip:** Copy from `-----BEGIN OPENSSH PRIVATE KEY-----` to `-----END OPENSSH PRIVATE KEY-----` (inclusive).
### Copy ed25519 Private key
For ED25519:
```bash
# macOS
@ -151,40 +140,44 @@ pbcopy < ~/.ssh/id_ed25519
xclip < ~/.ssh/id_ed25519
```
See detailed information about [SSH login without a password](http://www.linuxproblem.org/art_9.html).
See more: [SSH login without a password](http://www.linuxproblem.org/art_9.html).
**Note**: Depending on your version of SSH, you might also need to make the following changes:
> **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
- 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
## 🛡️ OpenSSH Compatibility
If you are currently using OpenSSH and are getting the following error:
If you see this error:
```bash
ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey]
```
Ensure that your chosen key algorithm 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 (either `/etc/ssh/sshd_config` or a drop-in file under `/etc/ssh/sshd_config.d/`):
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/`):
```bash
CASignatureAlgorithms +ssh-rsa
```
Alternatively, `ed25519` keys are accepted by default in OpenSSH. You can use this instead of rsa if needed:
Alternatively, use ED25519 keys (supported by default):
```bash
ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
```
### Example
---
#### Executing remote ssh commands using password
## 🧑‍💻 More Usage Examples
### Using password authentication
```yaml
- name: executing remote ssh commands using password
- name: Execute remote SSH commands using password
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.HOST }}
@ -194,10 +187,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
script: whoami
```
#### Using private key
### Using private key authentication
```yaml
- name: executing remote ssh commands using ssh key
- name: Execute remote SSH commands using SSH key
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.HOST }}
@ -207,10 +200,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
script: whoami
```
#### Multiple Commands
### Multiple commands
```yaml
- name: multiple command
- name: Multiple commands
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.HOST }}
@ -224,10 +217,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
![result](./images/output-result.png)
#### Commands from a file
### Run commands from a file
```yaml
- name: file commands
- name: File commands
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.HOST }}
@ -237,10 +230,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
script_path: scripts/script.sh
```
#### Multiple Hosts
### Multiple hosts
```diff
- name: multiple host
- name: Multiple hosts
uses: appleboy/ssh-action@v1
with:
- host: "foo.com"
@ -253,12 +246,12 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
ls -al
```
The default value of `port` is `22`.
Default `port` is `22`.
#### Multiple hosts with different port
### Multiple hosts with different ports
```diff
- name: multiple host
- name: Multiple hosts
uses: appleboy/ssh-action@v1
with:
- host: "foo.com"
@ -270,10 +263,10 @@ The default value of `port` is `22`.
ls -al
```
#### Synchronous execution on multiple hosts
### Synchronous execution on multiple hosts
```diff
- name: multiple host
- name: Multiple hosts
uses: appleboy/ssh-action@v1
with:
host: "foo.com,bar.com"
@ -286,10 +279,10 @@ The default value of `port` is `22`.
ls -al
```
#### Pass environment variable to shell script
### Pass environment variables to shell script
```diff
- name: pass environment
- name: Pass environment
uses: appleboy/ssh-action@v1
+ env:
+ FOO: "BAR"
@ -307,9 +300,11 @@ The default value of `port` is `22`.
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._
> _All environment variables in the `env` object must be strings. Using integers or other types may cause unexpected results._
#### How to connect remote server using `ProxyCommand`?
---
## 🌐 Using ProxyCommand (Jump Host)
```bash
+--------+ +----------+ +-----------+
@ -317,7 +312,7 @@ _Inside `env` object, you need to pass every environment variable as a string, p
+--------+ +----------+ +-----------+
```
in your `~/.ssh/config`, you will see the following.
Example `~/.ssh/config`:
```bash
Host Jumphost
@ -333,10 +328,10 @@ Host FooServer
ProxyCommand ssh -q -W %h:%p Jumphost
```
#### How to convert to YAML format of GitHubActions
**GitHub Actions YAML:**
```diff
- name: ssh proxy command
- name: SSH proxy command
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.HOST }}
@ -352,14 +347,14 @@ Host FooServer
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.
## 🔒 Protecting Your Private Key
A passphrase encrypts your private key, making it useless to attackers if leaked. Always store your private key securely.
```diff
- name: ssh key passphrase
- name: SSH key passphrase
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.HOST }}
@ -372,20 +367,20 @@ It is not uncommon for files to leak from backups or decommissioned hardware, an
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.
## 🖐️ Host Fingerprint Verification
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).
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):
```sh
ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' ' -f2
```
Now you can adjust you config:
Update your config:
```diff
- name: ssh key passphrase
- name: SSH key passphrase
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.HOST }}
@ -398,33 +393,31 @@ Now you can adjust you config:
ls -al
```
## Q&A
---
## ❓ Q&A
### Command not found (npm or other command)
See the [issue comment](https://github.com/appleboy/ssh-action/issues/31#issuecomment-1006565847) about interactive vs non interactive shell. Thanks @kocyigityunus for the solution.
If you encounter "command not found" errors, see [this issue comment](https://github.com/appleboy/ssh-action/issues/31#issuecomment-1006565847) about interactive vs non-interactive shells.
If you are running a command in a non-interactive shell, like ssh-action, on many Linux distros,
`/etc/bash.bashrc` file has a specific command that returns only, so some of the files didn't run and some specific commands doesn't add to path,
On many Linux distros, `/etc/bash.bashrc` contains:
```sh
# /etc/bash.bashrc
# System-wide .bashrc file for interactive bash(1) shells.
# To enable the settings / commands in this file for login shells as well,
# this file has to be sourced in /etc/profile.
# If not running interactively, don't do anything
[ -z "$PS1" ] && return`
[ -z "$PS1" ] && return
```
comment out the line that returns early, and everything should work fine. Alternatively, you can use the real paths of the commands you want to use.
Comment out this line or use absolute paths for your commands.
## Contributing
---
We would love for you to contribute to `appleboy/ssh-action`, pull requests are welcome!
## 🤝 Contributing
## License
Contributions are welcome! Please submit a pull request to help improve `appleboy/ssh-action`.
The scripts and documentation in this project are released under the [MIT License](LICENSE)
---
## 📝 License
This project is licensed under the [MIT License](LICENSE).