Skip to content

Commit f6208e0

Browse files
appleboyappleboy
committed
docs: document and demonstrate capturing and using command output
- Add documentation outlining usage of output variables, specifically the captured command standard output - Introduce the `capture_stdout` parameter to command options tables - Update Quick Start examples to use a secret for the username, and clarify output handling - Provide example workflows showing how to capture and use command output in subsequent steps - Change code block language from bash to text for SSH configuration snippets Signed-off-by: appleboy <[email protected]>
1 parent 652a0be commit f6208e0

File tree

3 files changed

+117
-12
lines changed

3 files changed

+117
-12
lines changed

‎README.md‎

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ English | [繁體中文](./README.zh-tw.md) | [简体中文](./README.zh-cn.md)
1111
- [🔌 Connection Settings](#-connection-settings)
1212
- [🛠️ SSH Command Settings](#️-ssh-command-settings)
1313
- [🌐 Proxy Settings](#-proxy-settings)
14+
- [📤 Output Variables](#-output-variables)
1415
- [⚡ Quick Start](#-quick-start)
1516
- [🔑 SSH Key Setup \& OpenSSH Compatibility](#-ssh-key-setup--openssh-compatibility)
1617
- [Setting Up SSH Keys](#setting-up-ssh-keys)
@@ -26,6 +27,7 @@ English | [繁體中文](./README.zh-tw.md) | [简体中文](./README.zh-cn.md)
2627
- [Multiple hosts with different ports](#multiple-hosts-with-different-ports)
2728
- [Synchronous execution on multiple hosts](#synchronous-execution-on-multiple-hosts)
2829
- [Pass environment variables to shell script](#pass-environment-variables-to-shell-script)
30+
- [Capturing command output](#capturing-command-output)
2931
- [🌐 Proxy \& Jump Host Usage](#-proxy--jump-host-usage)
3032
- [🛡️ Security Best Practices](#️-security-best-practices)
3133
- [Protecting Your Private Key](#protecting-your-private-key)
@@ -93,6 +95,7 @@ These parameters control the commands executed on the remote host and related be
9395
| debug | Enable debug mode | false |
9496
| request_pty | Request a pseudo-terminal from the server | false |
9597
| curl_insecure | Allow curl to connect to SSL sites without certificates | false |
98+
| capture_stdout | Capture standard output from commands as action output | false |
9699
| version | drone-ssh binary version. If not specified, the latest version will be used. | |
97100

98101
---
@@ -120,6 +123,16 @@ These parameters control the use of a proxy (jump host) for connecting to your t
120123
121124
---
122125

126+
## 📤 Output Variables
127+
128+
This action provides the following outputs that you can use in subsequent steps:
129+
130+
| Output | Description |
131+
| ------ | ----------------------------------------------------------------- |
132+
| stdout | Standard output of the executed commands (requires `capture_stdout: true`) |
133+
134+
---
135+
123136
## ⚡ Quick Start
124137

125138
Run remote SSH commands in your workflow with minimal configuration:
@@ -136,7 +149,7 @@ jobs:
136149
uses: appleboy/ssh-action@v1
137150
with:
138151
host: ${{ secrets.HOST }}
139-
username: linuxserver.io
152+
username: ${{ secrets.USERNAME }}
140153
password: ${{ secrets.PASSWORD }}
141154
port: ${{ secrets.PORT }}
142155
script: whoami
@@ -148,7 +161,7 @@ jobs:
148161
======CMD======
149162
whoami
150163
======END======
151-
linuxserver.io
164+
out: your_username
152165
===============================================
153166
✅ Successfully executed commands to all hosts.
154167
===============================================
@@ -222,7 +235,7 @@ ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publ
222235

223236
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/`):
224237

225-
```bash
238+
```text
226239
CASignatureAlgorithms +ssh-rsa
227240
```
228241

@@ -366,6 +379,28 @@ Default `port` is `22`.
366379

367380
> _All environment variables in the `env` object must be strings. Using integers or other types may cause unexpected results._
368381

382+
### Capturing command output
383+
384+
You can capture the standard output of remote commands and use it in subsequent steps:
385+
386+
```yaml
387+
- name: Execute and capture output
388+
id: ssh
389+
uses: appleboy/ssh-action@v1
390+
with:
391+
host: ${{ secrets.HOST }}
392+
username: ${{ secrets.USERNAME }}
393+
key: ${{ secrets.KEY }}
394+
port: ${{ secrets.PORT }}
395+
capture_stdout: true
396+
script: |
397+
echo "Hello World"
398+
hostname
399+
400+
- name: Use captured output
401+
run: echo "SSH output was ${{ steps.ssh.outputs.stdout }}"
402+
```
403+
369404
---
370405

371406
## 🌐 Proxy & Jump Host Usage
@@ -380,7 +415,7 @@ You can connect to remote hosts via a proxy (jump host) for advanced network top
380415

381416
Example `~/.ssh/config`:
382417

383-
```bash
418+
```text
384419
Host Jumphost
385420
HostName Jumphost
386421
User ubuntu

‎README.zh-cn.md‎

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
- [🔌 连接设置](#-连接设置)
1212
- [🛠️ 指令设置](#️-指令设置)
1313
- [🌐 代理设置](#-代理设置)
14+
- [📤 输出变量](#-输出变量)
1415
- [⚡ 快速开始](#-快速开始)
1516
- [🔑 SSH 密钥配置与 OpenSSH 兼容性](#-ssh-密钥配置与-openssh-兼容性)
1617
- [配置 SSH 密钥](#配置-ssh-密钥)
@@ -26,6 +27,7 @@
2627
- [多主机不同端口](#多主机不同端口)
2728
- [多主机同步执行](#多主机同步执行)
2829
- [传递环境变量到 shell 脚本](#传递环境变量到-shell-脚本)
30+
- [捕获命令输出](#捕获命令输出)
2931
- [🌐 代理与跳板机用法](#-代理与跳板机用法)
3032
- [🛡️ 安全最佳实践](#️-安全最佳实践)
3133
- [保护你的私钥](#保护你的私钥)
@@ -93,6 +95,7 @@
9395
| debug | 启用调试模式 | false |
9496
| request_pty | 向服务器请求伪终端 | false |
9597
| curl_insecure | 允许 curl 连接无证书的 SSL 站点 | false |
98+
| capture_stdout | 捕获命令的标准输出作为 Action 输出 | false |
9699
| version | drone-ssh 二进制版本，未指定时使用最新版本 | |
97100

98101
---
@@ -120,6 +123,16 @@
120123
121124
---
122125

126+
## 📤 输出变量
127+
128+
本 Action 提供以下输出，可在后续步骤中使用：
129+
130+
| 输出 | 描述 |
131+
| ------ | ----------------------------------------------------- |
132+
| stdout | 执行命令的标准输出（需设置 `capture_stdout: true`） |
133+
134+
---
135+
123136
## ⚡ 快速开始
124137

125138
只需简单配置，即可在工作流中执行远程 SSH 命令：
@@ -136,7 +149,7 @@ jobs:
136149
uses: appleboy/ssh-action@v1
137150
with:
138151
host: ${{ secrets.HOST }}
139-
username: linuxserver.io
152+
username: ${{ secrets.USERNAME }}
140153
password: ${{ secrets.PASSWORD }}
141154
port: ${{ secrets.PORT }}
142155
script: whoami
@@ -148,7 +161,7 @@ jobs:
148161
======CMD======
149162
whoami
150163
======END======
151-
linuxserver.io
164+
out: your_username
152165
===============================================
153166
✅ Successfully executed commands to all hosts.
154167
===============================================
@@ -222,7 +235,7 @@ ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publ
222235

223236
在 Ubuntu 20.04+，你可能需要显式允许 `ssh-rsa` 算法。请在 OpenSSH 配置文件（`/etc/ssh/sshd_config` 或 `/etc/ssh/sshd_config.d/` 下的 drop-in 文件）中添加：
224237

225-
```bash
238+
```text
226239
CASignatureAlgorithms +ssh-rsa
227240
```
228241

@@ -366,6 +379,28 @@ ssh-keygen -t ed25519 -a 200 -C "[email protected]"
366379

367380
> _`env` 对象中的所有环境变量必须为字符串。传递整数或其他类型可能导致意外结果。_
368381

382+
### 捕获命令输出
383+
384+
你可以捕获远程命令的标准输出，并在后续步骤中使用：
385+
386+
```yaml
387+
- name: 执行并捕获输出
388+
id: ssh
389+
uses: appleboy/ssh-action@v1
390+
with:
391+
host: ${{ secrets.HOST }}
392+
username: ${{ secrets.USERNAME }}
393+
key: ${{ secrets.KEY }}
394+
port: ${{ secrets.PORT }}
395+
capture_stdout: true
396+
script: |
397+
echo "Hello World"
398+
hostname
399+
400+
- name: 使用捕获的输出
401+
run: echo "SSH 输出为 ${{ steps.ssh.outputs.stdout }}"
402+
```
403+
369404
---
370405

371406
## 🌐 代理与跳板机用法
@@ -380,7 +415,7 @@ ssh-keygen -t ed25519 -a 200 -C "[email protected]"
380415

381416
示例 `~/.ssh/config`：
382417

383-
```bash
418+
```text
384419
Host Jumphost
385420
HostName Jumphost
386421
User ubuntu

‎README.zh-tw.md‎

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
- [🔌 連線設定](#-連線設定)
1212
- [🛠️ 指令設定](#️-指令設定)
1313
- [🌐 代理設定](#-代理設定)
14+
- [📤 輸出變數](#-輸出變數)
1415
- [⚡ 快速開始](#-快速開始)
1516
- [🔑 SSH 金鑰設定與 OpenSSH 相容性](#-ssh-金鑰設定與-openssh-相容性)
1617
- [設定 SSH 金鑰](#設定-ssh-金鑰)
@@ -26,6 +27,7 @@
2627
- [多主機不同埠號](#多主機不同埠號)
2728
- [多主機同步執行](#多主機同步執行)
2829
- [傳遞環境變數到 shell 腳本](#傳遞環境變數到-shell-腳本)
30+
- [擷取指令輸出](#擷取指令輸出)
2931
- [🌐 代理與跳板機用法](#-代理與跳板機用法)
3032
- [🛡️ 安全最佳實踐](#️-安全最佳實踐)
3133
- [保護你的私鑰](#保護你的私鑰)
@@ -93,6 +95,7 @@
9395
| debug | 啟用除錯模式 | false |
9496
| request_pty | 向伺服器請求偽終端 | false |
9597
| curl_insecure | 允許 curl 連線無憑證的 SSL 網站 | false |
98+
| capture_stdout | 擷取指令的標準輸出作為 Action 輸出 | false |
9699
| version | drone-ssh 執行檔版本，未指定時使用最新版本 | |
97100

98101
---
@@ -120,6 +123,16 @@
120123
121124
---
122125

126+
## 📤 輸出變數
127+
128+
本 Action 提供以下輸出，可在後續步驟中使用：
129+
130+
| 輸出 | 說明 |
131+
| ------ | ----------------------------------------------------- |
132+
| stdout | 執行指令的標準輸出（需設定 `capture_stdout: true`） |
133+
134+
---
135+
123136
## ⚡ 快速開始
124137

125138
只需簡單設定，即可在工作流程中執行遠端 SSH 指令：
@@ -136,7 +149,7 @@ jobs:
136149
uses: appleboy/ssh-action@v1
137150
with:
138151
host: ${{ secrets.HOST }}
139-
username: linuxserver.io
152+
username: ${{ secrets.USERNAME }}
140153
password: ${{ secrets.PASSWORD }}
141154
port: ${{ secrets.PORT }}
142155
script: whoami
@@ -148,7 +161,7 @@ jobs:
148161
======CMD======
149162
whoami
150163
======END======
151-
linuxserver.io
164+
out: your_username
152165
===============================================
153166
✅ Successfully executed commands to all hosts.
154167
===============================================
@@ -222,7 +235,7 @@ ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publ
222235

223236
在 Ubuntu 20.04+，你可能需明確允許 `ssh-rsa` 演算法。請於 OpenSSH 設定檔（`/etc/ssh/sshd_config` 或 `/etc/ssh/sshd_config.d/` 下的 drop-in 檔案）加入：
224237

225-
```bash
238+
```text
226239
CASignatureAlgorithms +ssh-rsa
227240
```
228241

@@ -366,6 +379,28 @@ ssh-keygen -t ed25519 -a 200 -C "[email protected]"
366379

367380
> _`env` 物件中的所有環境變數必須為字串。傳遞整數或其他型別可能導致非預期結果。_
368381

382+
### 擷取指令輸出
383+
384+
你可以擷取遠端指令的標準輸出，並在後續步驟中使用：
385+
386+
```yaml
387+
- name: 執行並擷取輸出
388+
id: ssh
389+
uses: appleboy/ssh-action@v1
390+
with:
391+
host: ${{ secrets.HOST }}
392+
username: ${{ secrets.USERNAME }}
393+
key: ${{ secrets.KEY }}
394+
port: ${{ secrets.PORT }}
395+
capture_stdout: true
396+
script: |
397+
echo "Hello World"
398+
hostname
399+
400+
- name: 使用擷取的輸出
401+
run: echo "SSH 輸出為 ${{ steps.ssh.outputs.stdout }}"
402+
```
403+
369404
---
370405

371406
## 🌐 代理與跳板機用法
@@ -380,7 +415,7 @@ ssh-keygen -t ed25519 -a 200 -C "[email protected]"
380415

381416
範例 `~/.ssh/config`：
382417

383-
```bash
418+
```text
384419
Host Jumphost
385420
HostName Jumphost
386421
User ubuntu

0 commit comments

Comments
 (0)