What's new ⬇ Download Reportworq
⬇ Guide PDF

Set up Google Cloud Storage#

Google Cloud Storage is a dual-role integration in Reportworq. One Google service account can power two separate role-configurations:

Both roles authenticate with a Google service account and its JSON key, entered once as a shared credential. Access is granted with ordinary Google Cloud IAM roles on the buckets.

Secrets warning. The service account JSON contains a private key. Treat the whole file as a secret. Never paste it into a ticket, a screenshot, a chat message, source control, or any other unsecured location. Reportworq encrypts the key at rest once you enter it in the shared credential, and after that it is never shown again.

Before you begin#

1. Create a service account and a JSON key#

In the Google Cloud Console, in the project that owns your buckets:

  1. Go to IAM & Admin, Service Accounts, and select Create Service Account.
  2. Give it a descriptive name, for example reportworq-storage, and finish creating it.
  3. Open the service account, then its Keys tab. Select Add Key, Create new key, choose JSON, and create the key. The file downloads once.
  4. Note the service account's email address (it ends in .iam.gserviceaccount.com). You grant it access to buckets in the next step.

The key must be a real service-account key, with "type": "service_account" at the top level of the JSON. Other Google credential types, such as an authorized_user credential or an external_account (workload identity) credential, are not accepted for Cloud Storage.

The key's project_id matters: Reportworq lists buckets in that project. A key with no project_id can still read and write a bucket you name, but it cannot browse the project's buckets (see Browsing buckets).

2. Grant the service account access to the buckets#

Grant the service account's email address the roles it needs, on each bucket (or on the project, if you want it to reach every bucket in it). In the Cloud Console, open the bucket, go to Permissions, select Grant access, and add the service account.

Role of the connection Permission Reportworq checks Example predefined role
Report provider (read) storage.objects.list and storage.objects.get on the bucket Storage Object Viewer
Distributor (write) storage.objects.create on the bucket Storage Object Creator

A bucket that both supplies reports and receives output needs both sets. Any role that includes the permissions also works. Grant the narrowest role that covers what the credential must do.

Delivery only needs storage.objects.create. A write-only key, one that can create objects but not list them, is a valid distributor credential.

3. Add the shared credential#

  1. In Reportworq, go to Settings, Integrations, and in the Shared Credentials swimlane add a Google service account credential.
  2. Give it a Display name.
  3. Either paste the complete JSON into the Service Account Key (JSON) box, or select Upload .json and pick the downloaded key file.
  4. Save.

Reportworq reads the service account's email address out of the key and shows it with a Copy button, so you can confirm it matches the account you granted in step 2. The private key itself is never shown again; the row reads "Key loaded - the private key is stored encrypted and is not shown," with a Replace key button if you rotate it.

This is the same Google service account shared credential type that the Google Drive roles use. If you already have one, you can reuse it for Cloud Storage, provided its service account has been granted the bucket roles above. A separate service account for storage keeps the two sets of access apart and is the tidier choice.

4. Configure the connection#

The report provider and the distributor are separate integrations. Neither is created when you set up the other, and each references the shared credential by name. Set up one or both.

In Settings, Integrations, add a Google Cloud Storage integration in the Report Providers family, the Distributors family, or both. Like every integration, the editor opens with the common chrome, an Enable Integration checkbox, a Display name, and an Availability workspaces dropdown. See The integrations hub for the add, test, enable, and save mechanics. The connection settings are:

Field Required What to enter
Credential Yes The Google service account shared credential from step 3.
Location Yes A bucket name, optionally followed by a folder: reports-bucket or reports-bucket/2026.

What Location means#

Location is a single text box that Reportworq splits into the bucket and an optional folder inside it. Its meaning depends on the role:

A pasted gs:// in front of the bucket is dropped, and backslashes are read as /.

Select Test Connection, then save, and enable the integration so authors can see it.

Who can read what#

Because Location is not a read boundary, the credential is the boundary. Anyone who can write a file into a bucket the service account can read can get that file rendered by Reportworq, exactly as with any other report provider (see They are a security boundary). Grant the service account read access only to the buckets whose contents you are willing to have reports built from.

Pick a report from a bucket#

On the Reports step, an author selects Add a Report, picks the Cloud Storage provider, and works in the Select a Report dialog. The dialog is bucket-rooted: the top level is the list of buckets the credential can see, not just the Location.

Browsing buckets and the permission it needs#

Access checks and locked buckets#

Reportworq checks each listed bucket in the background to see whether the credential can read it, so the page appears right away and the answers arrive afterward:

A bucket whose check could not complete (a network problem, say, which says nothing about permission) is asked again after about 15 seconds.

A report picked from a bucket is saved with its bucket and full path, and shows in the Reports grid as Connection/bucket/folders/file. When the job runs, Reportworq always reads the current version of the object at that path.

Dynamic Path#

A report's source can be dynamic, with a path that embeds parameter values and resolves differently on each run, as described in Dynamic, parameter-driven source paths. For Cloud Storage, a Dynamic Path is the path inside the picked report's own bucket:

reports/%param:Region%.xlsx

If the picked report is in the bucket finance-reports, this reads finance-reports/reports/<Region>.xlsx. The parameter name is case-sensitive.

To read from a different bucket, start the path with gs:// and the bucket name:

gs://shared-templates/%param:Region%/pack.xlsx

Rules and conveniences:

If a Dynamic Path points at a file that does not exist, the run fails with a message such as "The Dynamic Path resolved to '...', but no file exists there in bucket 'b'." naming the bucket and the path it tried. If the path names another bucket that the credential cannot read, the message says the bucket does not exist or this connection cannot read it, and reminds you that to read from the report's own bucket you leave out the gs://bucket/ and start with the folders.

Deliver to a bucket#

Add Google Cloud Storage as a destination on a job's Distribution step. The step has one field, Path, in the form bucket or bucket/folders.

Path Where the files go
Blank The connection's Location (its bucket and folder).
finance-reports/2026/Q3 That bucket and folder. Any value other than blank is absolute: the connection's folder is not added in front of it.
{Region}-reports/{Quarter} Variables are resolved first, and the result is then split into bucket and folders, so a variable can supply the bucket or the whole path.

Each output is written as folder/<output file name>. Folders in Cloud Storage are part of the object name, so there is nothing to create first.

A Path that contains a variable and resolves to nothing for a run fails with a message that the path "resolved to nothing for this run", rather than quietly writing to the connection's default. A step with no bucket anywhere fails with a "no bucket" message.

The destination's folder picker lists the buckets the credential can see, like Select a Report does, but checks write access: a bucket the credential cannot write to is held back behind Show N other buckets in the same way.

Troubleshooting#

Symptom Likely cause and fix
The credential will not save, with a message about the key type The JSON is not a service-account key ("type" is something other than service_account). Download a new JSON key from the service account's Keys tab.
Select a Report shows only one bucket, with a notice The credential cannot list the project's buckets, or the key has no project_id. Grant storage.buckets.list on the project, or work from the Location bucket and a Dynamic Path.
A bucket is under Show N other buckets, or locked Open its reason panel. The usual cause is a missing storage.objects.list and storage.objects.get (read) or storage.objects.create (write) for the service account on that bucket.
A saved report says it does not name a bucket and file It was saved without them. Pick the report again in Select a Report.
Delivery fails with "no bucket" The step's Path is blank and the connection's Location has no bucket, or the Path is a bare folder. Start the Path with the bucket name.

Feedback on this page

Comments, questions, requests, or something missing or unclear? Email us - the page you are on is filled in for you.

Email feedback on this page

Or write to support@reportworq.com directly.