From 4861d65a3cc490e357344053b9cd8e4a9d29764c Mon Sep 17 00:00:00 2001 From: Karolis2011 Date: Thu, 20 Nov 2025 01:19:48 +0200 Subject: [PATCH] fix: add debug option for SSH remote shell wrapper to assist with troubleshooting --- .github/workflows/example.yml | 4 ++++ README.md | 34 ++++++++++++++++++++++++++++++++++ action.yml | 32 ++++++++++++++++++++++++++------ 3 files changed, 64 insertions(+), 6 deletions(-) diff --git a/.github/workflows/example.yml b/.github/workflows/example.yml index 338a119..7bf54aa 100644 --- a/.github/workflows/example.yml +++ b/.github/workflows/example.yml @@ -19,6 +19,10 @@ jobs: ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }} ssh-host: ${{ secrets.SSH_HOST }} ssh-user: ${{ secrets.SSH_USER }} + # Try turning on the shell wrapper debug if the job succeeds but + # produces no visible output. This will print the temp script and + # its contents to the step log. + debug-shell-wrapper: 'true' - name: Check system info shell: ssh-remote {0} diff --git a/README.md b/README.md index 3e731b6..9f3d47d 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,9 @@ jobs: ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }} ssh-host: ${{ secrets.SSH_HOST }} ssh-user: ${{ secrets.SSH_USER }} + # Optional: enable debug mode to print the temp script and its + # contents on the runner for troubleshooting "no output" cases. + debug-shell-wrapper: 'true' - name: Run remote commands with custom shell shell: ssh-remote {0} @@ -137,6 +140,7 @@ jobs: | `strict-host-key-checking` | Enable strict host key checking (`yes`/`no`/`accept-new`) | No | `accept-new` | | `use-shell-wrapper` | Create shell wrapper for remote execution (enables `shell: ssh-remote {0}`) | No | `true` | | `remote-shell` | Shell to use on remote server (`bash`, `sh`, `zsh`, etc.) | No | `bash` | +| `debug-shell-wrapper` | Print script path and contents before executing remote commands (for debugging only) | No | `false` | ## Outputs @@ -170,6 +174,8 @@ Use `shell: ssh-remote {0}` in any step to execute the entire script on the remo - Works like a local shell - No need to wrap commands in SSH +⚠️ Note: Enabling `debug-shell-wrapper: 'true'` will print the contents of the temporary script and the exit code to the job logs. This can help diagnose "no output" runs, but may leak secrets or other sensitive data — only enable on trusted runs. + ### 2. SSH Host Alias (Direct) @@ -220,6 +226,34 @@ Add the output to a GitHub secret named `SSH_KNOWN_HOSTS`. ## Troubleshooting +### Debugging no output from custom shell + +If a step using `shell: ssh-remote {0}` shows no output but reports success: + +- Enable `debug-shell-wrapper: 'true'` in the `Setup SSH` step. This will tell the wrapper to print the temp script path and the first 200 lines of the script it executes. Example: + +```yaml +- name: Setup SSH + uses: your-username/setup-ssh-client@v1 + with: + ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }} + ssh-host: ${{ secrets.SSH_HOST }} + ssh-user: ${{ secrets.SSH_USER }} + debug-shell-wrapper: 'true' +``` + +- Re-run the job — the logs from subsequent steps will include the script path and contents; confirm the commands you expect are present. +- If the script looks correct, try a direct SSH command from a `run:` step to verify remote side: + +```yaml +- name: Direct SSH smoke test + run: ssh github-action-host "echo hello; whoami; pwd" +``` + +- If the direct test shows output but the wrapper step still shows nothing, examine whether your remote shell sets PATH or environment differently for non-interactive shells — you may need to force a login shell or source shell rc files with `shell: ssh-remote {0}` and `run: | source ~/.bashrc; your commands` or set `remote-shell: 'bash -l'`. + +Note: Don't forget to disable `debug-shell-wrapper` when done; it prints the script contents into logs which may reveal secrets. + ### Connection Timeout If the connection test fails with a timeout: diff --git a/action.yml b/action.yml index 7ff83c3..721ce22 100644 --- a/action.yml +++ b/action.yml @@ -35,6 +35,10 @@ inputs: description: 'Shell to use on remote server (bash, sh, zsh, etc.)' required: false default: 'bash' + debug-shell-wrapper: + description: 'Enable debug logging in the SSH remote wrapper (prints script path and contents)' + required: false + default: 'false' outputs: ssh-config-path: @@ -212,10 +216,21 @@ runs: # Use BatchMode to prevent interactive prompts # ConnectTimeout to fail fast if connection issues echo "Executing script on remote server '${{ inputs.ssh-host }}' via SSH..." + # Print some debug information if requested. See 'debug-shell-wrapper' input. + if [ "${SSH_REMOTE_DEBUG-}" = "true" ]; then + echo "[ssh-remote wrapper] Script file: $SCRIPT_FILE" + echo "[ssh-remote wrapper] Script contents:" >&2 + sed -n '1,200p' "$SCRIPT_FILE" + echo "[ssh-remote wrapper] ---------- end script ----------" + fi ssh -o BatchMode=yes \ -o ConnectTimeout=10 \ github-action-host \ "${{ inputs.remote-shell }} -s" < "$SCRIPT_FILE" + SSH_EXIT_CODE=$? + if [ "${SSH_REMOTE_DEBUG-}" = "true" ]; then + echo "[ssh-remote wrapper] SSH exit code: $SSH_EXIT_CODE" + fi WRAPPER_EOF chmod +x "$WRAPPER_PATH" @@ -223,12 +238,12 @@ runs: # We also create symlink without the .sh extension to provide a # short executable name inside the wrapper dir (e.g. $WRAPPER_DIR/ssh-remote) ln -s "$WRAPPER_PATH" "$WRAPPER_DIR/ssh-remote" - if [ "${{ inputs.use-shell-wrapper }}" = "true" ]; then - echo "" - echo "To use the remote shell in subsequent steps, add:" - echo " shell: ssh-remote {0}" - echo "" - echo "The 'ssh-remote' shell is now available for use." + if [ "${{ inputs.debug-shell-wrapper }}" = "true" ]; then + # Persist debug flag to the job environment; the wrapper can pick + # this up later when the job runs. This allows debugging without + # changing the wrapper script at runtime. + echo "SSH_REMOTE_DEBUG=true" >> $GITHUB_ENV + echo "⚠️ SSH remote shell wrapper debug is enabled (SSH_REMOTE_DEBUG=true)" fi echo "shell-wrapper-dir=$WRAPPER_DIR" >> $GITHUB_OUTPUT echo "shell-wrapper-path=$WRAPPER_PATH" >> $GITHUB_OUTPUT @@ -243,3 +258,8 @@ runs: echo "Adding custom shell 'ssh-remote' to PATH" echo "PATH=$SHELL_WRAPPER_DIR:$PATH" >> $GITHUB_ENV echo "✅ Custom shell 'ssh-remote' registered for this job" + echo "" + echo "To use the remote shell in subsequent steps, add:" + echo " shell: ssh-remote {0}" + echo "" + echo "The 'ssh-remote' shell is now available for use."