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:
- A report provider that reads source workbooks and PowerPoint templates from a Cloud Storage bucket. See Source report providers for how a provider is consumed on the Reports step.
- A distributor that writes a distribution job's generated files into a bucket. See Destinations for the destination catalog.
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#
- You are a Reportworq administrator with permission to configure integrations.
- You have access to the Google Cloud Console for the project that owns the buckets, and permission there to create a service account and grant IAM roles.
- You know which bucket Reportworq will deliver into (for the distributor), and which bucket or buckets hold the source reports (for the report provider).
1. Create a service account and a JSON key#
In the Google Cloud Console, in the project that owns your buckets:
- Go to IAM & Admin, Service Accounts, and select Create Service Account.
- Give it a descriptive name, for example
reportworq-storage, and finish creating it. - Open the service account, then its Keys tab. Select Add Key, Create new key, choose JSON, and create the key. The file downloads once.
- 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#
- In Reportworq, go to Settings, Integrations, and in the Shared Credentials swimlane add a Google service account credential.
- Give it a Display name.
- Either paste the complete JSON into the Service Account Key (JSON) box, or select Upload .json and pick the downloaded key file.
- 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:
- On a report provider, Location is only where browsing starts. It is the bucket pinned first in the Select a Report dialog. It is not a limit on what can be read: any bucket the credential can read can supply a report.
- On a distributor, Location is the default destination. A distribution step that leaves its own Path blank delivers here.
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#
- Buckets are listed 50 at a time. Use the search box (it matches the start of a bucket name) and Load more to page through a long list. Only the bucket list is paged; the folders inside a bucket are not.
- The connection's own bucket (its Location) is pinned first.
- Listing the project's buckets needs a permission that reading files does not:
storage.buckets.liston the project. The Storage Object Viewer role does not include it. Grant it (through a custom role, or a broader role that carries it) only if you want authors to browse the full list. - If the credential cannot list buckets, the dialog still works: it shows the connection's own bucket, with a notice. Authors can read other buckets by typing a Dynamic Path that names them (below). Delivering to a bucket also works without the bucket-list permission, because delivery only needs
storage.objects.createon the bucket.
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 still being checked shows Checking access. You can still open or pick it.
- Buckets the credential can read are shown first.
- Buckets it cannot read, or cannot confirm it can read, are hidden behind Show N other buckets. Select it to see them, and Show only the ones you can use to hide them again.
- A locked bucket shows why: a plain one-sentence reason for any user, and, for administrators, the identity used, the missing permission, and the provider's message, with a paste-ready text version to send to whoever manages the bucket. A locked bucket cannot be opened or picked.
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:
- A path with no
gs://never leaves the picked bucket. A typo cannot send a job into some other bucket by accident. - A pasted bucket or connection name in front is forgiven. The File Path line in the Reports grid reads
Connection/bucket/folders/file, and people paste that. If the path as typed does not exist, Reportworq also tries it without a leading connection name and then without a leading bucket name. The path as typed is always tried first, so a real folder that happens to share the bucket's name still works. .and..folders are refused. The path stays inside the bucket.- A preview shows where it will read. In Report Properties, the Dynamic Path box carries the hint "The path inside this report's bucket, for example reports/%param:Region%.xlsx. To read from another bucket, start with gs://bucket-name/." Beneath it, a Reads ... line shows the bucket and path that will be read, with
<Region>standing in for each parameter. A path using.or..shows "This path is not allowed: it uses . or .. folders." - A very large folder. If a bucket folder holds more files than the dialog lists, it says some files may not be shown and that a Dynamic Path can still read them.
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. |
Related pages#
- Source report providers for the provider list and Dynamic Path basics.
- Destinations for the destination catalog.
- The integrations hub for add, test, enable, and delete mechanics.
- Set up Google Drive, which uses the same Google service account credential type.
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 pageOr write to support@reportworq.com directly.