rsync-deployments

rsync deployments

CI - Validating, Linting, Testing Snyk Docker Vulnerability Scan CodeQL Dependabot Updates

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.23.2 (no cache) which results in fast deployments.

Alpine version: 3.23.2 Rsync version: 3.4.1-r1

Current Version: v8 (8.0.3)

Release channels:

Version Purpose Immutable
v8 (recommended) latest MAJOR (pointer to 8.MINOR.PATCH) no
8.0.3 latest MINOR+PATCH yes
7.1.0 previous MAJOR+MINOR (deprecation notice) yes
7.0.2 previous MAJOR+PATCH (deprecation notice) no

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@v6
    - name: rsync deployments
      uses: burnett01/rsync-deployments@v8
      with:
        switches: -avzr --delete
        path: src/
        remote_path: $ # ex: /var/www/html/
        remote_host: $ # ex: example.com
        remote_port: $ # ex: 22
        remote_user: $ # ex: ubuntu
        remote_key: $

Inputs

* = 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@v6
    - name: rsync deployments
      uses: burnett01/rsync-deployments@v8
      with:
        switches: -avzr --delete
        path: src/
        remote_path: $ # ex: /var/www/html/
        remote_host: $ # ex: example.com
        remote_port: $ # ex: 22
        remote_user: $ # ex: ubuntu
        remote_key: $

Advanced (with filters etc):

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - name: rsync deployments
      uses: burnett01/rsync-deployments@v8
      with:
        switches: -avzr --delete --exclude="" --include="" --filter=""
        path: src/
        remote_path: $ # ex: /var/www/html/
        remote_host: $ # ex: example.com
        remote_port: $ # ex: 22
        remote_user: $ # ex: ubuntu
        remote_key: $

If your private key is passphrase protected you should use:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - name: rsync deployments
      uses: burnett01/rsync-deployments@v8
      with:
        switches: -avzr --delete
        path: src/
        remote_path: $ # ex: /var/www/html/
        remote_host: $ # ex: example.com
        remote_port: $ # ex: 22
        remote_user: $ # ex: ubuntu
        remote_key: $
        remote_key_pass: $

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@v6
    - name: rsync deployments
      uses: burnett01/rsync-deployments@v8
      with:
        switches: -avzr --delete
        legacy_allow_rsa_hostkeys: "true"
        path: src/
        remote_path: $ # ex: /var/www/html/
        remote_host: $ # ex: example.com
        remote_port: $ # ex: 22
        remote_user: $ # ex: ubuntu
        remote_key: $

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:

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:

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:

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 8.0.0 (EOL due to regression -> fixed via 8.0.1 & 8.0.2)

Check here:

Version 7.1.0

Check here:

Version 7.0.2 (DEPRECATED)

Check here:

Version 7.0.0 & 7.0.1 (EOL)

Check here:

Version 6.0 (EOL)

Check here:

Version 5.0, 5.1 & 5.2 & 5.x (EOL)

Check here:

Version 4.0 & 4.1 (EOL)

Check here:

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

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.

This site is open source. Improve this page.