Add comprehensive troubleshooting guide for SSH permission denied issues

Co-authored-by: Burnett01 <1208707+Burnett01@users.noreply.github.com>

README.md

@@ -49,6 +49,19 @@ This action needs secret variables for the ssh private key of your key pair. The
 
 For simplicity, we are using `DEPLOY_*` as the secret variables throughout the examples.
 
+### Recommended SSH Key Generation
+
+**For new deployments, use Ed25519 keys (recommended):**
+```bash
+ssh-keygen -t ed25519 -C "deploy@yourproject" -f ~/.ssh/deploy_yourproject -N ""
+```
+
+**If you must use RSA keys:**
+```bash
+ssh-keygen -t rsa -b 4096 -C "deploy@yourproject" -f ~/.ssh/deploy_yourproject -N ""
+```
+*Note: RSA keys require `legacy_allow_rsa_hostkeys: "true"` with modern OpenSSH servers (8.8+)*
+
 ## Current Version: 7.1.0
 
 ## Example usage
@@ -143,8 +156,9 @@ jobs:
 
 #### Legacy RSA Hostkeys support for OpenSSH Servers >= 8.8+
 
-If your remote OpenSSH Server still uses RSA hostkeys, then you have to
+If you're using RSA SSH keys (generated with `ssh-keygen -t rsa`) and your remote server runs OpenSSH 8.8+, you need to enable legacy RSA hostkey support. This is required because OpenSSH 8.8+ deprecated RSA hostkeys by default for security reasons.
-manually enable legacy support for this by using ``legacy_allow_rsa_hostkeys: "true"``.
+
+**When you need this:** RSA keys + OpenSSH 8.8+ server = add `legacy_allow_rsa_hostkeys: "true"`
 
 ```yml
 jobs:
@@ -156,19 +170,97 @@ jobs:
       uses: burnett01/rsync-deployments@7.1.0
       with:
         switches: -avzr --delete
-        legacy_allow_rsa_hostkeys: "true"
+        legacy_allow_rsa_hostkeys: "true"  # Required for RSA keys with OpenSSH 8.8+
         path: src/
         remote_path: ${{ secrets.DEPLOY_PATH }}
         remote_host: ${{ secrets.DEPLOY_HOST }}
         remote_port: ${{ secrets.DEPLOY_PORT }}
         remote_user: ${{ secrets.DEPLOY_USER }}
-        remote_key: ${{ secrets.DEPLOY_KEY }}
+        remote_key: ${{ secrets.DEPLOY_KEY }}  # Your RSA private key
 ```
 
 See [#49](https://github.com/Burnett01/rsync-deployments/issues/49) and [#24](https://github.com/Burnett01/rsync-deployments/issues/24) for more information.
 
 ---
 
+## Troubleshooting Common Issues
+
+### "Permission denied" SSH Errors
+
+If you encounter errors like:
+```
+Identity added: (stdin) (deploy@***)
+Warning: Permanently added '***' (ED25519) to the list of known hosts.
+Permission denied, please try again.
+Permission denied, please try again.
+***@***: Permission denied (publickey,password).
+rsync: connection unexpectedly closed (0 bytes received so far) [sender]
+rsync error: unexplained error (code 255) at io.c(228) [sender=3.2.3]
+```
+
+**Most common cause:** You're using RSA keys with an OpenSSH 8.8+ server that has deprecated RSA hostkeys by default.
+
+**Solution:** Add `legacy_allow_rsa_hostkeys: "true"` to your workflow:
+
+```yml
+- name: Deploy files to server
+  uses: burnett01/rsync-deployments@7.1.0
+  with:
+    switches: -avz --delete
+    legacy_allow_rsa_hostkeys: "true"  # Add this line
+    path: ./
+    remote_path: ${{ secrets.DEPLOY_PATH }}
+    remote_host: ${{ secrets.DEPLOY_HOST }}
+    remote_user: ${{ secrets.DEPLOY_USER }}
+    remote_key: ${{ secrets.DEPLOY_KEY }}
+```
+
+**Alternative solution:** Generate Ed25519 keys instead of RSA:
+```bash
+ssh-keygen -t ed25519 -C "deploy@yourproject" -f ~/.ssh/deploy_yourproject -N ""
+```
+
+### When do I need `legacy_allow_rsa_hostkeys: "true"`?
+
+You need this setting when **both** conditions are true:
+1. You're using RSA SSH keys (generated with `-t rsa`)
+2. Your destination server runs OpenSSH 8.8+ (most modern servers)
+
+You can check your server's OpenSSH version:
+```bash
+ssh user@yourserver 'ssh -V'
+```
+
+### Frequently Asked Questions
+
+**Q: Do I need to exclude ".git" folder from deployment?**
+A: No, rsync by default follows your `.path` setting. If you set `path: ./`, it syncs the entire directory. If you want to exclude `.git`, use:
+```yml
+switches: -avz --delete --exclude='.git'
+```
+
+**Q: Do I need to allowlist GitHub Actions IP addresses in my firewall?**
+A: Yes, if you have a restrictive firewall. GitHub publishes their IP ranges at:
+- API endpoint: https://api.github.com/meta (look for `actions` IPs)
+- Or allowlist the entire GitHub IP ranges for `actions` and `hooks`
+
+However, these IP ranges change frequently. Consider:
+1. Using a jump host/bastion with a static IP
+2. Setting up a VPN connection
+3. Using GitHub's self-hosted runners in your network
+
+**Q: My key has a passphrase, how do I handle it?**
+A: Use the `remote_key_pass` input:
+```yml
+remote_key: ${{ secrets.DEPLOY_KEY }}
+remote_key_pass: ${{ secrets.DEPLOY_KEY_PASSPHRASE }}
+```
+
+**Q: Should I use RSA or Ed25519 keys?**
+A: Ed25519 is recommended for new deployments as it's more secure and doesn't require legacy compatibility flags. However, RSA keys work fine with the `legacy_allow_rsa_hostkeys: "true"` setting.
+
+---
+
 ## Version 7.0.2
 
 Check here: 

test/entrypoint.bats

@@ -63,3 +63,24 @@ teardown() {
     run ./entrypoint.sh
     [[ "${output}" != *"HostKeyAlgorithms=+ssh-rsa"* ]]
 }
+
+@test "legacy RSA switches include both HostKeyAlgorithms and PubkeyAcceptedKeyTypes" {
+    export INPUT_LEGACY_ALLOW_RSA_HOSTKEYS="true"
+    export INPUT_REMOTE_PATH="remote/"
+    export INPUT_REMOTE_KEY="dummy"
+    export INPUT_REMOTE_KEY_PASS="dummy"
+    export GITHUB_ACTION="dummy"
+    export INPUT_SWITCHES="-avz"
+    export INPUT_REMOTE_PORT="22"
+    export INPUT_RSH=""
+    export INPUT_PATH=""
+    export INPUT_REMOTE_USER="user"
+    export INPUT_REMOTE_HOST="host"
+    export GITHUB_WORKSPACE="/tmp"
+    export DSN="user@host"
+    export LOCAL_PATH="/tmp/"
+
+    run ./entrypoint.sh
+    [[ "${output}" == *"HostKeyAlgorithms=+ssh-rsa"* ]]
+    [[ "${output}" == *"PubkeyAcceptedKeyTypes=+ssh-rsa"* ]]
+}