Updated README to clarify options. Added section on pinning trusted host keys.
rsync deployments
This cross-platform GitHub Action deploys files in path (relative to GITHUB_WORKSPACE) to a remote folder via rsync over ssh.
Use this action in a CD workflow which leaves deployable code in GITHUB_WORKSPACE, such actions/checkout.
The base-image of this action is very small and based on Alpine 3.24.4 (no cache) which results in fast deployments.
Alpine version: 3.24.4 Rsync version: 3.5.2-r1
Current Version: v9 (9.0.4)
Release channels:
| Version | Purpose | Immutable |
|---|---|---|
@v9 (recommended, LTS) |
latest MAJOR (pointer to 9.MINOR.PATCH) | no |
@9.0.4 |
latest MAJOR+MINOR+PATCH | yes |
@v8 (ESU) |
previous MAJOR (pointer to 8.MINOR.PATCH) | no |
@8.0.5 |
previous MAJOR+MINOR+PATCH | yes |
You can also use @latest which always points to the latest MAJOR (currently v9).
Check SECURITY.md for support cycles.
How it works
name: DEPLOY
on:
push:
branches:
- master
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: rsync deployments
uses: burnett01/rsync-deployments@v9
with:
switches: -avzr --delete
path: src/
remote_path: ${{ secrets.REMOTE_PATH }} # ex: /var/www/html/
remote_host: ${{ secrets.REMOTE_HOST }} # ex: example.com
remote_port: ${{ secrets.REMOTE_PORT }} # ex: 22
remote_user: ${{ secrets.REMOTE_USER }} # ex: ubuntu
remote_key: ${{ secrets.REMOTE_PRIVATE_KEY }}
Inputs
-
debug* - Whether to enable debug output. ("true" / "false") - Default: "false" -
switches* - The first is for any initial/required rsync flags, eg:-avzr --delete -
rsh- Custom remote shell SSH parameters via Rsync. -
strict_hostkeys_checking- Enables support for strict hostkeys (fingerprint) checking. ("true" / "false") - Default: "false" - DEPRECATED (use 'known_hosts')! -
known_hosts- Trusted host keys of the remote server, one per line (pinning). Enables strict hostkeys checking. Takes precedence overstrict_hostkeys_checking- Default: "" - See guide -
legacy_allow_rsa_hostkeys- Enables support for legacy RSA host keys on OpenSSH 8.8+. ("true" / "false") - Default: "false" -
path- The source path. Defaults to GITHUB_WORKSPACE and is relative to it -
remote_path* - The deployment target path -
remote_host* - The remote host -
remote_port- The remote port. Defaults to 22 -
remote_user* - The remote user -
remote_key* - The remote ssh private key -
remote_key_pass- The remote ssh private key passphrase (if any)
* = Required
Required secret(s)
This action needs secret variables for the ssh private key of your key pair. The public key part should be added to the authorized_keys file on the server that receives the deployment. The secret variable should be set in the Github secrets section of your org/repo and then referenced as the remote_key input.
Always use secrets when dealing with sensitive inputs!
For simplicity, we are using REMOTE_* as the secret variables throughout the examples.
Example usage
For better security always use secrets for remote_host, remote_port, remote_user and remote_path inputs.
Simple:
name: DEPLOY
on:
push:
branches:
- master
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: rsync deployments
uses: burnett01/rsync-deployments@v9
with:
switches: -avzr --delete
path: src/
remote_path: ${{ secrets.REMOTE_PATH }} # ex: /var/www/html/
remote_host: ${{ secrets.REMOTE_HOST }} # ex: example.com
remote_port: ${{ secrets.REMOTE_PORT }} # ex: 22
remote_user: ${{ secrets.REMOTE_USER }} # ex: ubuntu
remote_key: ${{ secrets.REMOTE_PRIVATE_KEY }}
Advanced (with filters etc) use switches:
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: rsync deployments
uses: burnett01/rsync-deployments@v9
with:
switches: -avzr --delete --exclude="" --include="" --filter=""
[...redacted...]
If your private key is passphrase protected you should use:
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: rsync deployments
uses: burnett01/rsync-deployments@v9
with:
[...redacted...]
remote_key: ${{ secrets.REMOTE_PRIVATE_KEY }}
remote_key_pass: ${{ secrets.REMOTE_PRIVATE_KEY_PASS }}
Pinning trusted host keys (known_hosts)
By default the action accepts any host key the server presents. With strict_hostkeys_checking: "true" (deprecated)
the key is fetched via ssh-keyscan right before the deployment, which only protects against
the key changing during the run, not against a server that is already spoofed at that moment.
To actually verify the server, pass its host key(s) via known_hosts. The action then enables strict checking and skips ssh-keyscan. If the server presents
a different key, the deployment fails.
Get the public host key on the server itself (not over the network):
cat /etc/ssh/ssh_host_ed25519_key.pub
# ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... user@server
Store the output in a secret (e.g. REMOTE_HOST_KEYS) and pass it to the action:
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: rsync deployments
uses: burnett01/rsync-deployments@v9
with:
[...redacted...]
known_hosts: ${{ secrets.REMOTE_HOST_KEYS }}
Accepted formats, one entry per line (blank lines and lines starting with # are ignored):
- Bare key, e.g.
ssh-ed25519 AAAAC3.... It is bound toremote_host(andremote_port, if not 22) automatically. - Full known_hosts line, e.g.
example.com ssh-ed25519 AAAAC3...or a hashed|1|...line. Used as is, so the host part must matchremote_host.
Multiple keys (e.g. ed25519 and ecdsa) can be listed on separate lines.
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".
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: rsync deployments
uses: burnett01/rsync-deployments@v9
with:
[...redacted...]
legacy_allow_rsa_hostkeys: "true"
See #49 and #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.
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:
# 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 (
.pubfile) to your server's~/.ssh/authorized_keys - Add the private key (without
.pubextension) to GitHub Secrets asREMOTE_PRIVATE_KEY - Ensure correct file permissions on your server:
chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys
For detailed information on creating and managing SSH keys, see GitHub's SSH Key Guide.
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 (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:
switches: -avzr --delete --exclude='.git/'
Other common exclusions:
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
Missing rsync on Remote Host
If the action fails with "rsync: command not found" or similar errors, rsync is not installed on your remote server. Install it using your system's package manager:
Ubuntu/Debian:
sudo apt-get update && sudo apt-get install rsync
CentOS/RHEL/Rocky/AlmaLinux:
sudo yum install rsync
# OR on newer versions:
sudo dnf install rsync
Alpine Linux:
sudo apk add rsync
Versions
Version 9.0.3
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/9.0.3 (alpine 3.24.3)
Version 9.0.2
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/9.0.2 (alpine 3.24.2)
Version 9.0.1
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/9.0.1 (alpine 3.24.1)
Version 9.0.0
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/9.0.0 (alpine 3.24.1)
Version 8.0.5
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/8.0.5 (alpine 3.23.4)
Version 8.0.4
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/8.0.4 (alpine 3.23.3)
Version 8.0.3
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/8.0.3 (alpine 3.23.2)
Version 8.0.2
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/8.0.2 (alpine 3.23.0)
Version 8.0.1 (EOL)
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/8.0.1 (alpine 3.23.0)
Version 8.0.0 (EOL due to regression -> fixed via 8.0.1 & 8.0.2)
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/8.0.0 (alpine 3.23.0)
Version 7.1.0 (EOL)
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/7.1.0 (alpine 3.22.1)
Version 7.0.2 (EOL)
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/7.0.2 (alpine 3.22.1)
Version 7.0.0 & 7.0.1 (EOL)
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/7.0.0 (alpine 3.19.1)
- https://github.com/Burnett01/rsync-deployments/tree/7.0.1 (alpine 3.22.1)
Version 6.0 (EOL)
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/6.0 (alpine 3.17.2)
Version 5.0, 5.1 & 5.2 & 5.x (EOL)
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/5.0 (alpine 3.11.x)
- https://github.com/Burnett01/rsync-deployments/tree/5.1 (alpine 3.14.1)
- https://github.com/Burnett01/rsync-deployments/tree/5.2 (alpine 3.15.0)
- https://github.com/Burnett01/rsync-deployments/tree/5.2.1 (alpine 3.16.1)
- https://github.com/Burnett01/rsync-deployments/tree/5.2.2 (alpine 3.17.2)
Version 4.0 & 4.1 (EOL)
Check here:
- https://github.com/Burnett01/rsync-deployments/tree/4.0
- https://github.com/Burnett01/rsync-deployments/tree/4.1
Version 4.0 & 4.1 use the drinternet/rsync:1.0.1 base-image.
Version 3.0 (EOL)
Check here: https://github.com/Burnett01/rsync-deployments/tree/3.0
Version 3.0 uses the alpine:latest base-image directly.
Consider upgrading to 4.0 that uses a docker-image drinternet/rsync:1.0.1 that is
based on alpine:latestand heavily optimized for rsync.
Version 2.0 (EOL)
Check here: https://github.com/Burnett01/rsync-deployments/tree/2.0
Version 2.0 uses a larger base-image (ubuntu:latest).
Consider upgrading to 3.0 for even faster deployments.
Version 1.0 (EOL)
Check here: https://github.com/Burnett01/rsync-deployments/tree/1.0
Please note that version 1.0 has reached end of life state.
Acknowledgements
- This project is a fork of Contention/rsync-deployments
- docker-rsync JoshPiper/rsync-docker
Media & Pingback
This action was featured in multiple blogs across the globe:
Disclaimer: The author & co-authors are not responsible for the content of the site-links below.