aws s3 sync: Sync a Directory to S3 in CI

Recursively copy only files that changed, optionally deleting removed ones.

aws s3 sync recursively copies a directory to (or from) S3, transferring only files whose size or timestamp changed. With --delete it removes destination files that no longer exist locally, making it the standard command for deploying static sites and SPAs from CI.

Common flags

--delete - remove destination objects not present in the source
--exclude / --include - filter files (later patterns override earlier ones)
--dryrun - show what would change without transferring
--cache-control / --metadata-directive - set headers on synced objects
--size-only - compare by size only, ignoring timestamps

Example in CI

Deploy a static site and purge stale objects.

shell

aws s3 sync ./dist s3://${SITE_BUCKET} --delete --exclude "*.map"

Common errors in CI

Unable to locate credentials - assume the OIDC deploy role first
An error occurred (AccessDenied) - missing s3:DeleteObject when using --delete
A client error (404) occurred - source path or bucket does not exist

Key takeaways

aws s3 sync transfers only changed files, ideal for repeated CI deploys.
--delete keeps the bucket an exact mirror; it needs s3:DeleteObject.
Use --dryrun in CI to preview a destructive sync before running it.