gcloud storage rsync: Sync Files to a Bucket
gcloud storage rsync synchronizes a local directory with a Cloud Storage prefix, copying only what changed.
Deploying a built static site or caching artifacts to GCS is efficient with rsync, since it transfers only differences instead of re-uploading everything.
What it does
gcloud storage rsync makes a destination match a source by copying new or changed objects. With --recursive it descends directories; with --delete-unmatched-destination-objects it removes destination objects absent from the source, making it a true mirror.
Common usage
# publish a built site, mirroring deletes
gcloud storage rsync ./dist gs://my-site \
--recursive --delete-unmatched-destination-objects
# pull a cache down, additively
gcloud storage rsync gs://my-cache ./cache --recursiveFlags
| Flag | What it does |
|---|---|
| --recursive / -r | Sync directories recursively |
| --delete-unmatched-destination-objects | Delete dest objects missing from source (mirror) |
| --exclude <regex> | Skip paths matching the pattern |
| --dry-run | Show what would change without doing it |
| --checksums-only | Compare by checksum instead of size and mtime |
In CI
Use --delete-unmatched-destination-objects only when you truly want a mirror, since it deletes destination files; test with --dry-run first. Authenticate keylessly with Workload Identity Federation; the identity needs roles/storage.objectAdmin to write and delete.
Common errors in CI
"The destination bucket ... does not exist" or "NotFoundException: 404" means a wrong bucket name or missing gs:// prefix. "AccessDeniedException: 403" means the identity lacks object write or delete permission. Surprising deletions almost always come from --delete-unmatched-destination-objects pointed at the wrong source.