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 <appleboy.tw@gmail.com>
2025-11-28 23:27:13 -05:00 · 2025-11-28 23:07:52 +08:00
parent 652a0bee3c
commit f6208e096d
3 changed files with 117 additions and 12 deletions
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@ English | [繁體中文](./README.zh-tw.md) | [简体中文](./README.zh-cn.md)
    - [🔌 Connection Settings](#-connection-settings)
    - [🛠️ SSH Command Settings](#️-ssh-command-settings)
    - [🌐 Proxy Settings](#-proxy-settings)
+  - [📤 Output Variables](#-output-variables)
  - [⚡ Quick Start](#-quick-start)
  - [🔑 SSH Key Setup \& OpenSSH Compatibility](#-ssh-key-setup--openssh-compatibility)
    - [Setting Up SSH Keys](#setting-up-ssh-keys)
@@ -26,6 +27,7 @@ English | [繁體中文](./README.zh-tw.md) | [简体中文](./README.zh-cn.md)
    - [Multiple hosts with different ports](#multiple-hosts-with-different-ports)
    - [Synchronous execution on multiple hosts](#synchronous-execution-on-multiple-hosts)
    - [Pass environment variables to shell script](#pass-environment-variables-to-shell-script)
+    - [Capturing command output](#capturing-command-output)
  - [🌐 Proxy \& Jump Host Usage](#-proxy--jump-host-usage)
  - [🛡️ Security Best Practices](#️-security-best-practices)
    - [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
 | debug           | Enable debug mode                                                                 | false   |
 | request_pty     | Request a pseudo-terminal from the server                                         | false   |
 | curl_insecure   | Allow curl to connect to SSL sites without certificates                           | false   |
+| capture_stdout  | Capture standard output from commands as action output                            | false   |
 | version         | drone-ssh binary version. If not specified, the latest version will be used.      |         |

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

 ---

+## 📤 Output Variables
+
+This action provides the following outputs that you can use in subsequent steps:
+
+| Output | Description                                                       |
+| ------ | ----------------------------------------------------------------- |
+| stdout | Standard output of the executed commands (requires `capture_stdout: true`) |
+
+---
+
 ## ⚡ Quick Start

 Run remote SSH commands in your workflow with minimal configuration:
@@ -136,7 +149,7 @@ jobs:
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.HOST }}
-          username: linuxserver.io
+          username: ${{ secrets.USERNAME }}
          password: ${{ secrets.PASSWORD }}
          port: ${{ secrets.PORT }}
          script: whoami
@@ -148,7 +161,7 @@ jobs:
 ======CMD======
 whoami
 ======END======
-linuxserver.io
+out: your_username
 ===============================================
 ✅ Successfully executed commands to all hosts.
 ===============================================
@@ -222,7 +235,7 @@ ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publ

 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
+```text
 CASignatureAlgorithms +ssh-rsa
 ```

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

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

+### Capturing command output
+
+You can capture the standard output of remote commands and use it in subsequent steps:
+
+```yaml
+- name: Execute and capture output
+  id: ssh
+  uses: appleboy/ssh-action@v1
+  with:
+    host: ${{ secrets.HOST }}
+    username: ${{ secrets.USERNAME }}
+    key: ${{ secrets.KEY }}
+    port: ${{ secrets.PORT }}
+    capture_stdout: true
+    script: |
+      echo "Hello World"
+      hostname
+
+- name: Use captured output
+  run: echo "SSH output was ${{ steps.ssh.outputs.stdout }}"
+```
+
 ---

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

 Example `~/.ssh/config`:

-```bash
+```text
 Host Jumphost
  HostName Jumphost
  User ubuntu
--- a/README.zh-cn.md
+++ b/README.zh-cn.md
@@ -11,6 +11,7 @@
    - [🔌 连接设置](#-连接设置)
    - [🛠️ 指令设置](#️-指令设置)
    - [🌐 代理设置](#-代理设置)
+  - [📤 输出变量](#-输出变量)
  - [⚡ 快速开始](#-快速开始)
  - [🔑 SSH 密钥配置与 OpenSSH 兼容性](#-ssh-密钥配置与-openssh-兼容性)
    - [配置 SSH 密钥](#配置-ssh-密钥)
@@ -26,6 +27,7 @@
    - [多主机不同端口](#多主机不同端口)
    - [多主机同步执行](#多主机同步执行)
    - [传递环境变量到 shell 脚本](#传递环境变量到-shell-脚本)
+    - [捕获命令输出](#捕获命令输出)
  - [🌐 代理与跳板机用法](#-代理与跳板机用法)
  - [🛡️ 安全最佳实践](#️-安全最佳实践)
    - [保护你的私钥](#保护你的私钥)
@@ -93,6 +95,7 @@
 | debug           | 启用调试模式                                          | false  |
 | request_pty     | 向服务器请求伪终端                                    | false  |
 | curl_insecure   | 允许 curl 连接无证书的 SSL 站点                       | false  |
+| capture_stdout  | 捕获命令的标准输出作为 Action 输出                    | false  |
 | version         | drone-ssh 二进制版本，未指定时使用最新版本            |        |

 ---
@@ -120,6 +123,16 @@

 ---

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

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

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

-```bash
+```text
 CASignatureAlgorithms +ssh-rsa
 ```

@@ -366,6 +379,28 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"

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

+### 捕获命令输出
+
+你可以捕获远程命令的标准输出，并在后续步骤中使用：
+
+```yaml
+- name: 执行并捕获输出
+  id: ssh
+  uses: appleboy/ssh-action@v1
+  with:
+    host: ${{ secrets.HOST }}
+    username: ${{ secrets.USERNAME }}
+    key: ${{ secrets.KEY }}
+    port: ${{ secrets.PORT }}
+    capture_stdout: true
+    script: |
+      echo "Hello World"
+      hostname
+
+- name: 使用捕获的输出
+  run: echo "SSH 输出为 ${{ steps.ssh.outputs.stdout }}"
+```
+
 ---

 ## 🌐 代理与跳板机用法
@@ -380,7 +415,7 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"

 示例 `~/.ssh/config`：

-```bash
+```text
 Host Jumphost
  HostName Jumphost
  User ubuntu
--- a/README.zh-tw.md
+++ b/README.zh-tw.md
@@ -11,6 +11,7 @@
    - [🔌 連線設定](#-連線設定)
    - [🛠️ 指令設定](#️-指令設定)
    - [🌐 代理設定](#-代理設定)
+  - [📤 輸出變數](#-輸出變數)
  - [⚡ 快速開始](#-快速開始)
  - [🔑 SSH 金鑰設定與 OpenSSH 相容性](#-ssh-金鑰設定與-openssh-相容性)
    - [設定 SSH 金鑰](#設定-ssh-金鑰)
@@ -26,6 +27,7 @@
    - [多主機不同埠號](#多主機不同埠號)
    - [多主機同步執行](#多主機同步執行)
    - [傳遞環境變數到 shell 腳本](#傳遞環境變數到-shell-腳本)
+    - [擷取指令輸出](#擷取指令輸出)
  - [🌐 代理與跳板機用法](#-代理與跳板機用法)
  - [🛡️ 安全最佳實踐](#️-安全最佳實踐)
    - [保護你的私鑰](#保護你的私鑰)
@@ -93,6 +95,7 @@
 | debug           | 啟用除錯模式                                          | false  |
 | request_pty     | 向伺服器請求偽終端                                    | false  |
 | curl_insecure   | 允許 curl 連線無憑證的 SSL 網站                       | false  |
+| capture_stdout  | 擷取指令的標準輸出作為 Action 輸出                    | false  |
 | version         | drone-ssh 執行檔版本，未指定時使用最新版本            |        |

 ---
@@ -120,6 +123,16 @@

 ---

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

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

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

-```bash
+```text
 CASignatureAlgorithms +ssh-rsa
 ```

@@ -366,6 +379,28 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"

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

+### 擷取指令輸出
+
+你可以擷取遠端指令的標準輸出，並在後續步驟中使用：
+
+```yaml
+- name: 執行並擷取輸出
+  id: ssh
+  uses: appleboy/ssh-action@v1
+  with:
+    host: ${{ secrets.HOST }}
+    username: ${{ secrets.USERNAME }}
+    key: ${{ secrets.KEY }}
+    port: ${{ secrets.PORT }}
+    capture_stdout: true
+    script: |
+      echo "Hello World"
+      hostname
+
+- name: 使用擷取的輸出
+  run: echo "SSH 輸出為 ${{ steps.ssh.outputs.stdout }}"
+```
+
 ---

 ## 🌐 代理與跳板機用法
@@ -380,7 +415,7 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"

 範例 `~/.ssh/config`：

-```bash
+```text
 Host Jumphost
  HostName Jumphost
  User ubuntu