Skip to content

Commit 4d84f05

Browse files
appleboyappleboy
committed
docs: revamp and unify multi-language readme documentation
- Remove the Table of Contents section to simplify documentation. - Add and reorganize introduction sections for a clearer project overview. - Rename and clarify section titles for improved structure and navigation. - Consolidate and expand explanatory text around SSH key setup, OpenSSH compatibility, security, and troubleshooting. - Provide richer descriptions for core concepts and advanced SSH usage scenarios. - Apply the same documentation improvements and structural changes across English, Simplified Chinese, and Traditional Chinese readme files for consistency. Signed-off-by: appleboy <[email protected]>
1 parent c7fbbc9 commit 4d84f05

File tree

3 files changed

+93
-141
lines changed

3 files changed

+93
-141
lines changed

‎README.md

Lines changed: 31 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -2,44 +2,22 @@
22

33
English | [繁體中文](./README.zh-tw.md) | [简体中文](./README.zh-cn.md)
44

5-
## Table of Contents
6-
7-
- [🚀 SSH for GitHub Actions](#-ssh-for-github-actions)
8-
- [Table of Contents](#table-of-contents)
9-
- [📥 Input Parameters](#-input-parameters)
10-
- [🚦 Usage Example](#-usage-example)
11-
- [🔑 Setting Up SSH Keys](#-setting-up-ssh-keys)
12-
- [Generate RSA key](#generate-rsa-key)
13-
- [Generate ED25519 key](#generate-ed25519-key)
14-
- [🛡️ OpenSSH Compatibility](#️-openssh-compatibility)
15-
- [🧑‍💻 More Usage Examples](#-more-usage-examples)
16-
- [Using password authentication](#using-password-authentication)
17-
- [Using private key authentication](#using-private-key-authentication)
18-
- [Multiple commands](#multiple-commands)
19-
- [Run commands from a file](#run-commands-from-a-file)
20-
- [Multiple hosts](#multiple-hosts)
21-
- [Multiple hosts with different ports](#multiple-hosts-with-different-ports)
22-
- [Synchronous execution on multiple hosts](#synchronous-execution-on-multiple-hosts)
23-
- [Pass environment variables to shell script](#pass-environment-variables-to-shell-script)
24-
- [🌐 Using ProxyCommand (Jump Host)](#-using-proxycommand-jump-host)
25-
- [🔒 Protecting Your Private Key](#-protecting-your-private-key)
26-
- [🖐️ Host Fingerprint Verification](#️-host-fingerprint-verification)
27-
- [❓ Q\&A](#-qa)
28-
- [Command not found (npm or other command)](#command-not-found-npm-or-other-command)
29-
- [🤝 Contributing](#-contributing)
30-
- [📝 License](#-license)
31-
32-
A [GitHub Action](https://github.com/features/actions) for executing remote SSH commands easily and securely.
5+
---
6+
7+
## 📖 Introduction
8+
9+
**SSH for GitHub Actions** is a powerful [GitHub Action](https://github.com/features/actions) for executing remote SSH commands easily and securely in your CI/CD workflows.
10+
Built with [Golang](https://go.dev) and [drone-ssh](https://github.com/appleboy/drone-ssh), it supports a wide range of SSH scenarios, including multi-host, proxy, and advanced authentication.
3311

3412
![ssh workflow](./images/ssh-workflow.png)
3513

3614
[![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)
3715

38-
This project is built with [Golang](https://go.dev) and [drone-ssh](https://github.com/appleboy/drone-ssh).
39-
4016
---
4117

42-
## 📥 Input Parameters
18+
## 🧩 Core Concepts & Input Parameters
19+
20+
This action provides flexible SSH command execution with a rich set of configuration options.
4321

4422
For full details, see [action.yml](./action.yml).
4523

@@ -85,9 +63,9 @@ For full details, see [action.yml](./action.yml).
8563
8664
---
8765

88-
## 🚦 Usage Example
66+
## ⚡ Quick Start
8967

90-
Run remote SSH commands in your workflow:
68+
Run remote SSH commands in your workflow with minimal configuration:
9169

9270
```yaml
9371
name: Remote SSH Command
@@ -121,17 +99,19 @@ linuxserver.io
12199

122100
---
123101

124-
## 🔑 Setting Up SSH Keys
102+
## 🔑 SSH Key Setup & OpenSSH Compatibility
103+
104+
### Setting Up SSH Keys
125105

126106
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:
127107

128-
### Generate RSA key
108+
#### Generate RSA key
129109

130110
```bash
131111
ssh-keygen -t rsa -b 4096 -C "[email protected]"
132112
```
133113

134-
### Generate ED25519 key
114+
#### Generate ED25519 key
135115

136116
```bash
137117
ssh-keygen -t ed25519 -a 200 -C "[email protected]"
@@ -175,9 +155,7 @@ See more: [SSH login without a password](http://www.linuxproblem.org/art_9.html)
175155
> - Set `.ssh` permissions to 700
176156
> - Set `.ssh/authorized_keys2` permissions to 640
177157
178-
---
179-
180-
## 🛡️ OpenSSH Compatibility
158+
### OpenSSH Compatibility
181159

182160
If you see this error:
183161

@@ -199,7 +177,9 @@ ssh-keygen -t ed25519 -a 200 -C "[email protected]"
199177

200178
---
201179

202-
## 🧑‍💻 More Usage Examples
180+
## 🛠️ Usage Scenarios & Advanced Examples
181+
182+
This section covers common and advanced usage patterns, including multi-host, proxy, and environment variable passing.
203183

204184
### Using password authentication
205185

@@ -331,7 +311,9 @@ Default `port` is `22`.
331311

332312
---
333313

334-
## 🌐 Using ProxyCommand (Jump Host)
314+
## 🌐 Proxy & Jump Host Usage
315+
316+
You can connect to remote hosts via a proxy (jump host) for advanced network topologies.
335317

336318
```bash
337319
+--------+ +----------+ +-----------+
@@ -376,7 +358,9 @@ Host FooServer
376358

377359
---
378360

379-
## 🔒 Protecting Your Private Key
361+
## 🛡️ Security Best Practices
362+
363+
### Protecting Your Private Key
380364

381365
A passphrase encrypts your private key, making it useless to attackers if leaked. Always store your private key securely.
382366

@@ -394,9 +378,7 @@ A passphrase encrypts your private key, making it useless to attackers if leaked
394378
ls -al
395379
```
396380

397-
---
398-
399-
## 🖐️ Host Fingerprint Verification
381+
### Host Fingerprint Verification
400382

401383
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):
402384

@@ -422,9 +404,11 @@ Update your config:
422404

423405
---
424406

425-
## ❓ Q&A
407+
## 🚨 Error Handling & Troubleshooting
408+
409+
### Q&A
426410

427-
### Command not found (npm or other command)
411+
#### Command not found (npm or other command)
428412

429413
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.
430414

‎README.zh-cn.md

Lines changed: 31 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -2,44 +2,22 @@
22

33
[English](./README.md) | [繁體中文](./README.zh-tw.md) | 简体中文
44

5-
## 目录
6-
7-
- [🚀 用于 GitHub Actions 的 SSH](#-用于-github-actions-的-ssh)
8-
- [目录](#目录)
9-
- [📥 输入参数](#-输入参数)
10-
- [🚦 使用示例](#-使用示例)
11-
- [🔑 配置 SSH 密钥](#-配置-ssh-密钥)
12-
- [生成 RSA 密钥](#生成-rsa-密钥)
13-
- [生成 ED25519 密钥](#生成-ed25519-密钥)
14-
- [🛡️ OpenSSH 兼容性](#️-openssh-兼容性)
15-
- [🧑‍💻 更多用法示例](#-更多用法示例)
16-
- [使用密码认证](#使用密码认证)
17-
- [使用私钥认证](#使用私钥认证)
18-
- [多条命令](#多条命令)
19-
- [从文件执行命令](#从文件执行命令)
20-
- [多主机](#多主机)
21-
- [多主机不同端口](#多主机不同端口)
22-
- [多主机同步执行](#多主机同步执行)
23-
- [传递环境变量到 shell 脚本](#传递环境变量到-shell-脚本)
24-
- [🌐 使用 ProxyCommand（跳板机）](#-使用-proxycommand跳板机)
25-
- [🔒 保护你的私钥](#-保护你的私钥)
26-
- [🖐️ 主机指纹验证](#️-主机指纹验证)
27-
- [❓ 常见问题](#-常见问题)
28-
- [命令未找到（npm 或其他命令）](#命令未找到npm-或其他命令)
29-
- [🤝 贡献](#-贡献)
30-
- [📝 许可证](#-许可证)
31-
32-
一个让你轻松安全地执行远程 SSH 命令的 [GitHub Action](https://github.com/features/actions)。
5+
---
6+
7+
## 📖 简介
8+
9+
**SSH for GitHub Actions** 是一个强大的 [GitHub Action](https://github.com/features/actions)，可让你在 CI/CD 工作流中轻松且安全地执行远程 SSH 命令。
10+
本项目基于 [Golang](https://go.dev) 和 [drone-ssh](https://github.com/appleboy/drone-ssh) 构建，支持多主机、代理、高级认证等多种 SSH 场景。
3311

3412
![ssh workflow](./images/ssh-workflow.png)
3513

3614
[![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)
3715

38-
本项目基于 [Golang](https://go.dev) 和 [drone-ssh](https://github.com/appleboy/drone-ssh) 构建。
39-
4016
---
4117

42-
## 📥 输入参数
18+
## 🧩 核心概念与输入参数
19+
20+
本 Action 提供灵活的 SSH 命令执行能力，并具备丰富的配置选项。
4321

4422
详细参数请参阅 [action.yml](./action.yml)。
4523

@@ -85,9 +63,9 @@
8563
8664
---
8765

88-
## 🚦 使用示例
66+
## ⚡ 快速开始
8967

90-
在工作流中执行远程 SSH 命令：
68+
只需简单配置，即可在工作流中执行远程 SSH 命令：
9169

9270
```yaml
9371
name: Remote SSH Command
@@ -121,17 +99,19 @@ linuxserver.io
12199

122100
---
123101

124-
## 🔑 配置 SSH 密钥
102+
## 🔑 SSH 密钥配置与 OpenSSH 兼容性
103+
104+
### 配置 SSH 密钥
125105

126106
建议在本地机器（而非远程服务器）上创建 SSH 密钥。请使用 GitHub Secrets 中指定的用户名登录并生成密钥对：
127107

128-
### 生成 RSA 密钥
108+
#### 生成 RSA 密钥
129109

130110
```bash
131111
ssh-keygen -t rsa -b 4096 -C "[email protected]"
132112
```
133113

134-
### 生成 ED25519 密钥
114+
#### 生成 ED25519 密钥
135115

136116
```bash
137117
ssh-keygen -t ed25519 -a 200 -C "[email protected]"
@@ -175,9 +155,7 @@ xclip < ~/.ssh/id_ed25519
175155
> - 设置 `.ssh` 权限为 700
176156
> - 设置 `.ssh/authorized_keys2` 权限为 640
177157
178-
---
179-
180-
## 🛡️ OpenSSH 兼容性
158+
### OpenSSH 兼容性
181159

182160
如果出现如下错误：
183161

@@ -199,7 +177,9 @@ ssh-keygen -t ed25519 -a 200 -C "[email protected]"
199177

200178
---
201179

202-
## 🧑‍💻 更多用法示例
180+
## 🛠️ 用法场景与进阶示例
181+
182+
本节涵盖常见与进阶用法，包括多主机、代理、环境变量传递等。
203183

204184
### 使用密码认证
205185

@@ -331,7 +311,9 @@ ssh-keygen -t ed25519 -a 200 -C "[email protected]"
331311

332312
---
333313

334-
## 🌐 使用 ProxyCommand（跳板机）
314+
## 🌐 代理与跳板机用法
315+
316+
你可以通过代理（跳板机）连接到远程主机，适用于进阶网络拓扑。
335317

336318
```bash
337319
+--------+ +----------+ +-----------+
@@ -376,7 +358,9 @@ Host FooServer
376358

377359
---
378360

379-
## 🔒 保护你的私钥
361+
## 🛡️ 安全最佳实践
362+
363+
### 保护你的私钥
380364

381365
密码短语会加密你的私钥，即使泄露也无法被攻击者直接利用。请务必妥善保管私钥。
382366

@@ -394,9 +378,7 @@ Host FooServer
394378
ls -al
395379
```
396380

397-
---
398-
399-
## 🖐️ 主机指纹验证
381+
### 主机指纹验证
400382

401383
验证 SSH 主机指纹有助于防止中间人攻击。获取主机指纹（将 `ed25519` 替换为你的密钥类型，`example.com` 替换为你的主机）：
402384

@@ -422,9 +404,11 @@ ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' '
422404

423405
---
424406

425-
## ❓ 常见问题
407+
## 🚨 错误处理与疑难解答
408+
409+
### 常见问题
426410

427-
### 命令未找到（npm 或其他命令）
411+
#### 命令未找到（npm 或其他命令）
428412

429413
如果遇到 "command not found" 错误，请参考 [此评论](https://github.com/appleboy/ssh-action/issues/31#issuecomment-1006565847) 了解交互式与非交互式 shell 的区别。
430414

0 commit comments

Comments
 (0)