gsutil cp: Copy Objects to Google Cloud Storage
gsutil cp copies files between the local filesystem and Google Cloud Storage, and with the top-level -m flag runs the copies in parallel.
gsutil is the classic GCS transfer tool. cp handles single files and, with -r, whole trees; the -m flag before cp turns on multithreaded, multiprocess transfers that matter for many objects.
What it does
gsutil cp copies objects between local paths and gs:// URLs. -r recurses into directories. The -m flag (placed before cp, as gsutil -m cp) parallelizes the operation across threads and processes, dramatically speeding up many-file transfers.
Common usage
gsutil cp ./build.tar.gz gs://my-bucket/artifacts/
gsutil -m cp -r ./dist gs://my-bucket/site
# gzip-on-the-fly for text assets, then upload
gsutil -m cp -Z -r ./public gs://my-bucket/wwwOptions
| Flag | What it does |
|---|---|
| -m | Top-level flag: run the operation in parallel |
| -r | Recurse into directories |
| -Z | Gzip-compress objects on upload (sets Content-Encoding) |
| -n | No-clobber: skip objects that already exist |
| -I | Read the list of source URLs from stdin |
In CI
Put -m before cp (gsutil -m cp) for speed on directory uploads. Authenticate with Workload Identity Federation (OIDC) rather than a service-account key file so no long-lived key sits on the runner. Note gcloud storage cp is the newer equivalent; gsutil remains widely used.
Common errors in CI
"AccessDeniedException: 403" means the identity lacks storage.objects.create on the bucket; grant roles/storage.objectAdmin on the prefix. "BucketNotFoundException: 404 ... bucket does not exist" is a wrong bucket. "ServiceException: 401 Anonymous caller" means no credentials resolved; check GOOGLE_APPLICATION_CREDENTIALS or the Workload Identity setup. "your credentials are invalid" often means an expired token.