Add comprehensive SSH troubleshooting section with documentation links and improved secret naming to README (#83)

* chore: Add comprehensive SSH troubleshooting section to README

* chore: Enhance README with rsync documentation link, SSH key guide

* chore: further enrich readme with more troubleshooting + change secrets name from DEPLOY_* to REMOTE_*

* chore: Added a new section for versions and updated heading formatting.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Burnett01 <1208707+Burnett01@users.noreply.github.com>
Co-authored-by: sovetski

README.md

@@ -35,9 +35,9 @@ Rsync version: [3.4.1-r0](https://download.samba.org/pub/rsync/NEWS#3.4.1)
 
 - `remote_user`* - The remote user
 
-- `remote_key`* - The remote ssh key
+- `remote_key`* - The remote ssh private key
 
-- `remote_key_pass` - The remote ssh key passphrase (if any)
+- `remote_key_pass` - The remote ssh private key passphrase (if any)
 
 ``* = Required``
 
@@ -47,7 +47,7 @@ This action needs secret variables for the ssh private key of your key pair. The
 
 > Always use secrets when dealing with sensitive inputs!
 
-For simplicity, we are using `DEPLOY_*` as the secret variables throughout the examples.
+For simplicity, we are using `REMOTE_*` as the secret variables throughout the examples.
 
 ## Current Version: 7.1.0
 
@@ -75,7 +75,7 @@ jobs:
         remote_path: /var/www/html/
         remote_host: example.com
         remote_user: debian
-        remote_key: ${{ secrets.DEPLOY_KEY }}
+        remote_key: ${{ secrets.REMOTE_PRIVATE_KEY }}
 ```
 
 Advanced:
@@ -95,7 +95,7 @@ jobs:
         remote_host: example.com
         remote_port: 5555
         remote_user: debian
-        remote_key: ${{ secrets.DEPLOY_KEY }}
+        remote_key: ${{ secrets.REMOTE_PRIVATE_KEY }}
 ```
 
 For better **security**, I suggest you create additional secrets for remote_host, remote_port, remote_user and remote_path inputs.
@@ -111,11 +111,11 @@ jobs:
       with:
         switches: -avzr --delete
         path: src/
-        remote_path: ${{ secrets.DEPLOY_PATH }}
+        remote_path: ${{ secrets.REMOTE_PATH }}
-        remote_host: ${{ secrets.DEPLOY_HOST }}
+        remote_host: ${{ secrets.REMOTE_HOST }}
-        remote_port: ${{ secrets.DEPLOY_PORT }}
+        remote_port: ${{ secrets.REMOTE_PORT }}
-        remote_user: ${{ secrets.DEPLOY_USER }}
+        remote_user: ${{ secrets.REMOTE_USER }}
-        remote_key: ${{ secrets.DEPLOY_KEY }}
+        remote_key: ${{ secrets.REMOTE_PRIVATE_KEY }}
 ```
 
 If your private key is passphrase protected you should use:
@@ -131,12 +131,12 @@ jobs:
       with:
         switches: -avzr --delete
         path: src/
-        remote_path: ${{ secrets.DEPLOY_PATH }}
+        remote_path: ${{ secrets.REMOTE_PATH }}
-        remote_host: ${{ secrets.DEPLOY_HOST }}
+        remote_host: ${{ secrets.REMOTE_HOST }}
-        remote_port: ${{ secrets.DEPLOY_PORT }}
+        remote_port: ${{ secrets.REMOTE_PORT }}
-        remote_user: ${{ secrets.DEPLOY_USER }}
+        remote_user: ${{ secrets.REMOTE_USER }}
-        remote_key: ${{ secrets.DEPLOY_KEY }}
+        remote_key: ${{ secrets.REMOTE_PRIVATE_KEY }}
-        remote_key_pass: ${{ secrets.DEPLOY_KEY_PASS }}
+        remote_key_pass: ${{ secrets.REMOTE_PRIVATE_KEY_PASS }}
 ```
 
 ---
@@ -158,17 +158,90 @@ jobs:
         switches: -avzr --delete
         legacy_allow_rsa_hostkeys: "true"
         path: src/
-        remote_path: ${{ secrets.DEPLOY_PATH }}
+        remote_path: ${{ secrets.REMOTE_PATH }}
-        remote_host: ${{ secrets.DEPLOY_HOST }}
+        remote_host: ${{ secrets.REMOTE_HOST }}
-        remote_port: ${{ secrets.DEPLOY_PORT }}
+        remote_port: ${{ secrets.REMOTE_PORT }}
-        remote_user: ${{ secrets.DEPLOY_USER }}
+        remote_user: ${{ secrets.REMOTE_USER }}
-        remote_key: ${{ secrets.DEPLOY_KEY }}
+        remote_key: ${{ secrets.REMOTE_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.
 
+**Note:** Only use this if necessary. It's recommended to upgrade your remote OpenSSH server instead.
+
+--
+
+## Advanced Rsync switches/flags/options
+
+For advanced rsync configuration options and switches, refer to the [rsync manual](https://linux.die.net/man/1/rsync).
+
 ---
 
+## Troubleshooting
+
+### SSH Permission Denied Errors
+
+If you encounter "Permission denied (publickey,password)" errors, here are the most common solutions:
+
+#### 1. SSH Key Setup
+
+Ensure your SSH key pair is correctly generated and configured:
+
+```bash
+# Generate a new SSH key pair (recommended: Ed25519 or RSA 4096-bit)
+ssh-keygen -t ed25519 -C "deploy@yourproject" -f ~/.ssh/deploy_yourproject -N ""
+# OR for RSA:
+ssh-keygen -t rsa -b 4096 -C "deploy@yourproject" -f ~/.ssh/deploy_yourproject -N ""
+```
+
+**Important Steps:**
+- Add the **public key** (`.pub` file) to your server's `~/.ssh/authorized_keys`
+- Add the **private key** (without `.pub` extension) to GitHub Secrets as `REMOTE_PRIVATE_KEY`
+- Ensure correct file permissions on your server:
+  ```bash
+  chmod 700 ~/.ssh
+  chmod 600 ~/.ssh/authorized_keys
+  ```
+
+For detailed information on creating and managing SSH keys, see [GitHub's SSH Key Guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
+
+#### 2. ``remote_path`` permissions
+
+Make sure the ``remote_user`` has write access to ``remote_path``.
+
+See: https://github.com/Burnett01/rsync-deployments/issues/81#issuecomment-3308152891
+
+#### 3. Firewall / GitHub Actions IP Restrictions
+
+If your remote server has firewall restrictions:
+
+- **Option A:** Whitelist [GitHub Actions IP ranges](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#ip-addresses) (Azure-based)
+- **Option B:** Use self-hosted runners on your server (recommended for strict firewall environments)
+
+### Excluding files/folders (eg .git) 
+
+By default, rsync copies dot files and folder if present at ``path:``. To exclude them, you can use the ``--exclude`` switch:
+
+```yml
+switches: -avzr --delete --exclude='.git/'
+```
+
+Other common exclusions:
+```yml
+switches: -avzr --delete --exclude='.git/' --exclude='node_modules/' --exclude='.env'
+```
+
+More advanced examples:
+
+- https://github.com/Burnett01/rsync-deployments/issues/5#issuecomment-667589874
+- https://github.com/Burnett01/rsync-deployments/issues/16
+- https://github.com/Burnett01/rsync-deployments/issues/71
+- https://github.com/Burnett01/rsync-deployments/issues/52
+
+---
+
+## Versions
+
 ## Version 7.0.2
 
 Check here: