gcloud storage cp: Usage, Recursion & Common CI Errors
Copy files to and from Google Cloud Storage - the modern gsutil replacement.
gcloud storage cp copies objects between local paths and Cloud Storage buckets. It is the faster, recommended successor to gsutil cp and the standard way to move artifacts in GCP pipelines.
What it does
gcloud storage cp <src> <dst> copies a file to or from a gs:// bucket; with --recursive it copies a whole directory tree. It parallelizes large transfers automatically. Either side may be local or a gs:// URI, and - streams via stdin/stdout.
Common usage
# Upload a file
gcloud storage cp build.zip gs://my-bucket/releases/build.zip
# Download
gcloud storage cp gs://my-bucket/config.json ./config.json
# Recursive upload of a directory
gcloud storage cp ./dist gs://my-bucket/site --recursiveCommon error in CI: 403 storage.objects.create / bucket not found
Uploads fail with "403 ... does not have storage.objects.create access to the Google Cloud Storage object" when the identity lacks the role, or "404 ... bucket does not exist" on a typo or wrong project. Fix: grant roles/storage.objectAdmin (or objectCreator for upload-only) on the bucket to the CI service account, and confirm the gs:// bucket name and project. If you are migrating from gsutil, the syntax is nearly identical - gcloud storage cp is preferred and generally faster.
Key options
| Option | Purpose |
|---|---|
| --recursive | Copy a directory tree |
| --content-type | Set object content type |
| --cache-control | Set Cache-Control metadata |
| - | Stream via stdin/stdout |
| gcloud storage rsync | Sync directories (like s3 sync) |