fix: add debug option for SSH remote shell wrapper to assist with troubleshooting

.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}

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:

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
+        if [ "${{ inputs.debug-shell-wrapper }}" = "true" ]; then
-          echo ""
+          # Persist debug flag to the job environment; the wrapper can pick
-          echo "To use the remote shell in subsequent steps, add:"
+          # this up later when the job runs. This allows debugging without
-          echo "  shell: ssh-remote {0}"
+          # changing the wrapper script at runtime.
-          echo ""
+          echo "SSH_REMOTE_DEBUG=true" >> $GITHUB_ENV
-          echo "The 'ssh-remote' shell is now available for use."
+          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."