rsync-deployments GitHub Action

These commands manage the $HOME/.ssh/known_hosts file to ensure correct permissions and entry management.

Initialize known_hosts

hosts-init creates the $HOME/.ssh/known_hosts file with default permissions of 600.

Add a host key

hosts-add [key] adds a new entry to the known_hosts file and ensures the file permissions remain correct.

• Argument: The new key string to add.

Clear known_hosts

hosts-clear truncates the known_hosts file, effectively removing all known host entries.

hosts-init
hosts-add "ssh-rsa AAAAB3Nza..."
hosts-clear

If you are using older versions of rsync-deployments, it is recommended to upgrade to the latest version (v9) for better performance and security.

• Version 3.0 (EOL): Uses alpine:latest directly. Upgrade to 4.0+ to use the optimized drinternet/rsync:1.0.1 image.
• Version 2.0 (EOL): Uses ubuntu:latest. Upgrade to 3.0+ for faster deployments.
• Version 1.0 (EOL): Has reached end-of-life state.

If your remote OpenSSH server is version 8.8 or newer and still uses legacy RSA hostkeys, you must explicitly enable support by setting legacy_allow_rsa_hostkeys: "true" in your workflow configuration.

- name: rsync deployments
  uses: burnett01/rsync-deployments@v9
  with:
    switches: -avzr --delete
    legacy_allow_rsa_hostkeys: "true"
    path: src/
    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 }}

To use this action, you must provide an SSH private key via the remote_key input.

1. Generate a key pair: Use Ed25519 or RSA 4096-bit.
2. Server Setup: Add the public key (.pub) to the server's ~/.ssh/authorized_keys file. Ensure permissions are correct:

   chmod 700 ~/.ssh
   chmod 600 ~/.ssh/authorized_keys

3. GitHub Setup: Add the private key (the file without the .pub extension) to your GitHub Repository/Organization Secrets as a new secret (e.g., REMOTE_PRIVATE_KEY).
4. Reference in Workflow: Use ${{ secrets.REMOTE_PRIVATE_KEY }} in your workflow file.

# 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 ""

If the action fails with rsync: command not found, you must install rsync on your remote server using its package manager:

Ubuntu/Debian:

sudo apt-get update && sudo apt-get install rsync

CentOS/RHEL/Rocky/AlmaLinux:

sudo yum install rsync
# OR
sudo dnf install rsync

Alpine Linux:

sudo apk add rsync

If you see Permission denied (publickey,password), check the following:

1. SSH Key Configuration:
   • Ensure the public key is in the server's ~/.ssh/authorized_keys.
   • Ensure the private key is correctly stored in GitHub Secrets and referenced as remote_key.
   • Verify server-side permissions: chmod 700 ~/.ssh and chmod 600 ~/.ssh/authorized_keys.
2. Remote Path Permissions: Ensure the remote_user has write access to the remote_path on the target server.
3. Firewalls: If the server restricts IP ranges, you may need to whitelist GitHub Actions IP ranges or use a self-hosted runner.

By default, rsync copies all files and dotfiles at the specified path. To exclude specific directories or files (like .git or node_modules), use the --exclude flag within the switches input.

switches: -avzr --delete --exclude='.git/'
# Or multiple exclusions:
switches: -avzr --delete --exclude='.git/' --exclude='node_modules/' --exclude='.env'