rsync --chown and --usermap for Ownership
rsync --chown=USER:GROUP sets the owner and group of transferred files, when you have the privileges to do so.
A deploy often connects as a deploy user but the files must end up owned by www-data. --chown handles that, with the catch that changing owner needs root on the remote.
What it does
--chown=USER:GROUP is a convenience for --owner --group plus --usermap and --groupmap, forcing every transferred file to the given owner and group. Setting the owner requires super-user privileges on the receiving side; setting only the group is allowed if you belong to that group.
Common usage
# Land files owned by www-data (needs remote root)
rsync -av --chown=www-data:www-data dist/ user@host:/var/www/app/
# Only set the group (works without root if you are in it)
rsync -av --chown=:deploy dist/ user@host:/srv/app/Ownership options
| Flag | What it does |
|---|---|
| --chown=U:G | Force owner U and group G on the destination |
| --chown=:G | Set group only (no owner change) |
| -o / --owner | Preserve source owner (super-user only) |
| -g / --group | Preserve source group |
| --usermap=FROM:TO | Remap owner names/ids during transfer |
In CI
Because owner changes need root, pair --chown with --rsync-path="sudo rsync" so the remote rsync runs under sudo. Configure a passwordless sudoers entry scoped to rsync for the deploy user; otherwise sudo will prompt and the job hangs or fails.
Common errors in CI
rsync: chown "..." failed: Operation not permitted (1) means the deploy user is not root and cannot change owner. Either use --rsync-path="sudo rsync", drop to a group-only --chown=:group, or fix ownership server-side after the transfer.