From 6ef11e4b9565b18f32bdacb019b55ad7e77b1491 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Sep 2025 11:25:45 +0000 Subject: [PATCH] Add comprehensive troubleshooting guide for SSH permission denied issues Co-authored-by: Burnett01 <1208707+Burnett01@users.noreply.github.com> --- README.md | 100 +++++++++++++++++++++++++++++++++++++++++-- test/entrypoint.bats | 21 +++++++++ 2 files changed, 117 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7ff52b3..36b9bd8 100644 --- a/README.md +++ b/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 -manually enable legacy support for this by using ``legacy_allow_rsa_hostkeys: "true"``. +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. + +**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: diff --git a/test/entrypoint.bats b/test/entrypoint.bats index 80dfba9..9b9eae6 100644 --- a/test/entrypoint.bats +++ b/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"* ]] +}