Google Cloud Storage
Google Cloud Storage (GCS) is Google’s object storage. WP Media Cloud uploads your Media Library to a GCS bucket through Google’s S3-compatible XML API. It signs in with an HMAC key that belongs to a service account. Files are served from https://storage.googleapis.com/your-bucket, or from a CDN you put in front of the bucket.
This guide takes about 15 minutes. It sets up a service account that can only change files in one bucket.
How GCS access works#
The plugin uses one HMAC key. What that key can do depends on the roles you give its service account.
| 1. Bucket access | 2. Bucket list | |
|---|---|---|
| Required? | Yes | No, optional |
| Role | Storage Object Admin, on your one bucket | Storage Bucket Viewer, on the project |
| What it lets the plugin do | Upload, serve, restore and delete files in that bucket | Fill a bucket list when you select Load in the setup wizard |
| What it cannot do | Touch other buckets, or change the bucket’s settings | Read, change or delete any file |
Do you need the second role? No. In the setup wizard you type the bucket name. The Load button only fills an optional list to pick from. Listing buckets needs a project-level permission that Storage Object Admin does not include.
Before you start#
- A Google Cloud project with billing enabled.
- Permission to manage the project. You need to create buckets, service accounts and HMAC keys, and change bucket permissions. The Storage Admin role covers the bucket steps.
- No organization policy blocking public buckets or HMAC keys. If your company manages Google Cloud for you, see Troubleshooting first.
Step 1: Create a bucket#
- In the Google Cloud console, go to Cloud Storage and open Buckets.
- Select Create.
- Under Get started, enter a globally unique name, for example
example-media. You cannot rename a bucket later. - Under Choose where to store your data, pick a location type and location. A region near most of your visitors is a good default.
- Under Choose how to store your data, keep the Standard storage class.
- Under Choose how to control access to objects, clear Prevent public access. Leave the access control model on Uniform.
- Select Create.
If Prevent public access is locked, an organization policy enforces it. Ask your Google Cloud admin before you continue, because visitors will not be able to load your images.
Step 2: Make the bucket public#
Visitors load images straight from the bucket, or through a CDN that reads it. Both need public read access.
- Open your bucket and select the Permissions tab.
- If the Public access card says public access is prevented, select Allow public access, then Confirm.
- Select Grant access.
- In New principals, enter
allUsers. - In Select a role, choose Storage Object Viewer.
- Select Save, then Allow public access.
This lets anyone read files in this bucket. It does not let anyone list, upload or delete them.
Step 3: Create a service account#
- In the console, go to IAM & Admin and open Service Accounts.
- Select Create service account.
- Enter a name you will recognise, such as
wp-media-cloud-example. - Select Done. Skip the optional step that grants roles on the whole project.
- Copy the service account’s email address. It ends in
.iam.gserviceaccount.com.
Use one service account per site. That keeps each site’s access separate.
Step 4: Give the service account access#
Part 1: Bucket access (required)#
- Go back to your bucket and open the Permissions tab.
- Select Grant access.
- In New principals, paste the service account email from Step 3.
- In Select a role, choose Storage Object Admin.
- Select Save.
Granting the role here, on the bucket, limits the service account to this one bucket.
Part 2: Bucket list (optional)#
Skip this part unless you want the wizard’s Load button to list your buckets.
- In the console, go to IAM & Admin and open IAM.
- Select Grant access.
- In New principals, paste the service account email.
- In Select a role, choose Storage Bucket Viewer.
- Select Save.
This role can see bucket names in the project. It cannot read or change any file.
Step 5: Create an HMAC key#
- In the console, go to Cloud Storage and open Settings.
- Select the Interoperability tab.
- Next to Create a key for a service account, select the add icon.
- Choose the service account from Step 3.
- Select Create key.
- Copy the Access key and the Secret into a password manager.
Copy the secret now. Google shows it only once. If you lose it, create a new key and delete the old one.
Step 6: Connect WP Media Cloud#

In WordPress, open Media Cloud in the admin menu. The setup wizard opens on first use. Choose Google Cloud and select Continue.
| Field | What to enter |
|---|---|
| HMAC Access Key | The access key from Step 5. It starts with GOOG. |
| HMAC Secret | The secret from Step 5 |
| Bucket name | Type your bucket name from Step 1, for example example-media. With the optional role from part 2, you can select Load and pick it instead. |
| Location | Starts on auto. Leave it, or enter your bucket’s location code, such as us-east1. |
| CDN Configuration | Direct bucket URL serves files from storage.googleapis.com with no CDN. Choose another option if you have a CDN in front of the bucket. |
Custom CDN takes the URL of any CDN, such as Cloud CDN or Fastly. The other options are Bunny.net CDN, KeyCDN, EWWW Easy IO and CDN77. For the last four, paste that service’s API key and pick your zone. The plugin then fills in the CDN URL and shows bandwidth on the Dashboard.
Select Continue, then Save & Go to Dashboard.
Check that it works#
The Google Cloud form has no Test connection button. To check your setup:
- Upload an image in Media, then Add New Media File.
- Open Media in list view. The image should show In cloud under its name.
- Open the image’s URL in a private browser window. It should load from your bucket or CDN.
If you see Offload failed, hover over it to read the error, then see Troubleshooting.
Changing your bucket or keys later#

Go to Settings and select run the setup wizard. Your offloaded files, records and other settings are kept.
The Google Cloud form opens with your saved bucket, location, CDN choice and CDN URL filled in. Saved keys show as Saved. Paste only the keys you are changing.
Alternative: Connect with wp-config.php#

Instead of the wizard, you can define your settings in wp-config.php, above the line /* That's all, stop editing! */. Values set here override anything saved in the admin, which suits sites managed in version control.
Multisite: constants in wp-config.php apply to every subsite, so they point every subsite at the same bucket. That works when each subsite keeps its files in its own folder: also add define( 'WPMC_PATH_PREFIX', 'sites/%site_id%' );. Or set up each subsite in its own dashboard. See Custom path prefix.
// Required
define( 'WPMC_PROVIDER', 'gcs' );
define( 'WPMC_GCS_ACCESS_KEY', 'GOOG...' );
define( 'WPMC_GCS_SECRET_KEY', 'your-hmac-secret' );
define( 'WPMC_GCS_BUCKET', 'example-media' );
// Optional
define( 'WPMC_GCS_LOCATION', 'auto' ); // or your bucket location, e.g. us-east1
define( 'WPMC_GCS_CDN_TYPE', 'custom' ); // none | custom | bunny | keycdn | ewww | cdn77
define( 'WPMC_GCS_CDN_URL', 'https://media.example.com' );
define( 'WPMC_GCS_ACL', 'private' ); // keep private for uniform buckets The first four lines are required. Without WPMC_GCS_CDN_URL, files are served from https://storage.googleapis.com/your-bucket.
For other CDNs, the generator also prints optional constants such as WPMC_GCS_BUNNY_API_KEY, WPMC_GCS_PULL_ZONE_HOSTNAME, WPMC_GCS_KEYCDN_ZONE_URL, WPMC_GCS_EWWW_API_KEY and WPMC_GCS_CDN77_URL. WP Media Cloud reads every one of them. The Health page and the Dashboard read the constants too.
After setup#
- New uploads go to your bucket automatically and are served from your CDN URL, or from
storage.googleapis.com. - Existing media is not moved until you start a bulk offload. On the Dashboard, find the Bulk Offload card and select Offload All Media. On large libraries or multisite,
wp wpmc offload(orwp wpmc offload --network) is faster. - Changing your CDN or its URL later: in Settings, open the Google Cloud Storage CDN card. Choose your CDN option and enter the URL. Select Save Settings. Then, under Apply to Existing Media, select Update all media URLs so existing files use the new address.
- Object permissions: keep Object ACL on private in Settings, under Object Permissions. Uniform buckets reject
public-read. Public access comes from theallUsersrole in Step 2. - Caching: WP Media Cloud stores every file with a one-year
Cache-Controlheader. Replaced files get a new file name, so this is safe. - Dashboard stats: Storage Used shows N/A. Google only reports storage size to OAuth credentials, not HMAC keys. The Offloaded count is always tracked. CDN Bandwidth appears when your CDN is Bunny.net, KeyCDN, EWWW Easy IO or CDN77 and its API key is saved.
- WooCommerce secure downloads are available with Bunny.net and Cloudflare R2 only. For Google Cloud Storage, the WooCommerce card says so, and downloadable files use their normal CDN URL. Those links are public, so do not put paid files in this bucket.
Troubleshooting#
| What you see | What it means | How to fix it |
|---|---|---|
| Load shows an error | The service account cannot list buckets, or the keys are wrong. The wizard shows the error below the field. | Type the bucket name instead. Check both keys. To use the list, grant Storage Bucket Viewer on the project (Step 4, part 2). |
| Media Library shows Not configured | The access key, secret or bucket name is missing. | Run the setup wizard again, or check your wp-config.php constants. |
Offload failed with HTTP 403 SignatureDoesNotMatch | The secret does not match the access key. | Paste both again with no spaces. If unsure, create a new HMAC key. |
Offload failed with HTTP 403 AccessDenied | The service account cannot write to this bucket, or the HMAC key is inactive. | Grant Storage Object Admin on the bucket (Step 4, part 1). In Interoperability, check that the key is Active. |
Offload failed with HTTP 404 NoSuchBucket | The bucket name is wrong. | Names are case-sensitive. Copy the name exactly from Buckets. |
Offload failed with HTTP 400 after changing Object ACL | Uniform buckets reject object ACLs. | Set Object ACL back to private. |
Images are broken, and the file URL shows AccessDenied in the browser | The bucket is not public. | Complete Step 2. Check that public access prevention is off on the bucket. |
| Allow public access is missing or locked | An organization policy enforces public access prevention. A bucket cannot override it. | Ask your Google Cloud admin to lift it for this project. |
| You cannot create an HMAC key | An organization policy blocks HMAC or service account keys. | Ask your admin about constraints/storage.restrictAuthTypes and constraints/iam.disableServiceAccountKeyCreation. |
New uploads use storage.googleapis.com instead of your CDN | The CDN choice is Direct Bucket, or the CDN URL is empty. | In the Google Cloud Storage CDN card, choose your CDN, enter its URL and select Save Settings. Or set WPMC_GCS_CDN_URL in wp-config.php. |
| Update all media URLs is greyed out | No CDN URL is entered in the Google Cloud Storage CDN card. | Choose your CDN option and enter its URL first. |
| New uploads stay on your server | Offload on upload is switched off. Before 1.1.7.1, finishing the setup wizard could switch it off. | In Settings, turn on Offload on upload and Rewrite URLs, then select Save Settings. |
| Storage Used shows N/A on the Dashboard | Expected. Storage size needs OAuth, which the plugin does not use for GCS. | Nothing to fix. Check storage usage in the Google Cloud console instead. |
| Run All Checks on the Health page passes, but uploads fail | For GCS, the health check only confirms that keys and a bucket are saved. It does not upload a test file. | Upload a test image and read the error on Offload failed. |
Frequently asked questions#
Is Storage Object Admin on one bucket really enough? Yes. It covers everything WP Media Cloud does with your files: uploading, serving, restoring and deleting. Storage Bucket Viewer is optional. It only fills the Load list in the wizard.
Why HMAC keys and not a JSON key file? WP Media Cloud talks to GCS through its S3-compatible XML API. That API signs requests with HMAC keys.
Do I need Google Cloud CDN? No. Files can be served straight from storage.googleapis.com. A CDN makes repeat visits faster and can give you your own domain.
Can I use one bucket for several sites? Yes, when each site has its own path prefix. WP Media Cloud stores files by upload date and file name, such as 2026/10/photo.jpg, so two sites without a prefix can overwrite each other’s files. On a multisite network, set Path prefix to sites/%site_id%. For separate sites, give each one a prefix of its own, such as shop and blog. A staging site should still use its own bucket. See Custom path prefix.
What does the Location field do? WP Media Cloud uses it when it signs requests. The wizard suggests auto for multi-region buckets, or a region code such as us-east1 or europe-west1.