From f1607ccbba1ebd7612dc57414708912e2e1fcfff Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 19 Sep 2025 15:40:13 +0200 Subject: [PATCH] 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 | 115 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 94 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 7ff52b3..8ee1562 100644 --- a/README.md +++ b/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_host: ${{ secrets.DEPLOY_HOST }} - remote_port: ${{ secrets.DEPLOY_PORT }} - remote_user: ${{ secrets.DEPLOY_USER }} - remote_key: ${{ secrets.DEPLOY_KEY }} + remote_path: ${{ secrets.REMOTE_PATH }} + remote_host: ${{ secrets.REMOTE_HOST }} + remote_port: ${{ secrets.REMOTE_PORT }} + remote_user: ${{ secrets.REMOTE_USER }} + 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_host: ${{ secrets.DEPLOY_HOST }} - remote_port: ${{ secrets.DEPLOY_PORT }} - remote_user: ${{ secrets.DEPLOY_USER }} - remote_key: ${{ secrets.DEPLOY_KEY }} - remote_key_pass: ${{ secrets.DEPLOY_KEY_PASS }} + remote_path: ${{ secrets.REMOTE_PATH }} + remote_host: ${{ secrets.REMOTE_HOST }} + remote_port: ${{ secrets.REMOTE_PORT }} + remote_user: ${{ secrets.REMOTE_USER }} + remote_key: ${{ secrets.REMOTE_PRIVATE_KEY }} + 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_host: ${{ secrets.DEPLOY_HOST }} - remote_port: ${{ secrets.DEPLOY_PORT }} - remote_user: ${{ secrets.DEPLOY_USER }} - remote_key: ${{ secrets.DEPLOY_KEY }} + remote_path: ${{ secrets.REMOTE_PATH }} + remote_host: ${{ secrets.REMOTE_HOST }} + remote_port: ${{ secrets.REMOTE_PORT }} + remote_user: ${{ secrets.REMOTE_USER }} + 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: