How to configure Reg-suit with Google Cloud Storage

To publish reg-suit visual regression snapshots and reports to Google Cloud Storage, install reg-publish-gcs-plugin, configure its required bucketName in the project’s regconfig.json, and make Google Application Default Credentials (ADC) available to the process running reg-suit. Then run reg-suit run. The publisher uses ADC to access the bucket; setting a report URI does not replace authentication.

This guide covers the plugin setup, local and CI credentials, configuration options, verification, common failures, and operational tradeoffs. The plugin and reg-suit configuration details are documented in the GCS publisher README and the reg-suit README.

1. Install the GCS publisher

From the root of the project where reg-suit runs, install the publisher as a development dependency:

npm i reg-publish-gcs-plugin -D

If reg-suit itself is not installed in the project yet, follow the project’s current installation instructions in its README. Keeping the publisher in the project dependency set makes its availability explicit in local development and CI.

2. Configure reg-suit

The GCS plugin README documents interactive setup with:

npx reg-suit prepare -p publish-gcs

Review the generated configuration and ensure the installed plugin’s settings are under the package name in the plugins object. A representative configuration is:

{
  "core": {
    "workingDir": ".reg",
    "actualDir": "images",
    "thresholdRate": 0.05
  },
  "plugins": {
    "reg-publish-gcs-plugin": {
      "bucketName": "$REG_SUIT_GCS_BUCKET",
      "pathPrefix": "visual-regression"
    }
  }
}

The core values shown are illustrative project settings; retain or adjust the values appropriate to your reg-suit workflow. The GCS-specific configuration is the publisher entry. Reg-suit documents environment substitution for plugin settings, which lets each environment provide its bucket without hard-coding it.

Plugin options

Option	Required	Purpose
`bucketName`	Yes	Name of the GCS bucket that stores published data.
`customUri`	No	Overrides the report URI prefix. The documented default is `https://storage.googleapis.com/${bucketName}`. It can help when report HTML is served through an HTTP proxy.
`pathPrefix`	No	Adds a prefix to published object paths, for example to group reg-suit files beneath a directory-like prefix.

For example, with a bucket named visual-test-results and a prefix team-a, the plugin publishes under that prefix. Confirm the precise report object path from the installed plugin version and generated output; the README’s path examples are illustrative. A custom URI changes the link prefix used for reports. It does not create the bucket, grant access, or configure credentials.

3. Provide Google credentials

The publisher authenticates using ADC. Credentials must be available to the same identity and process that runs reg-suit run. Google’s Cloud Storage authentication guide describes ADC discovery and environment-specific approaches. Select the option that matches where the command runs:

Environment	Typical ADC approach	Key consideration
Local development	Create user ADC with the gcloud CLI, as described by Google; supported client libraries can also use service-account impersonation.	A successful `gcloud` CLI login does not by itself prove ADC is available to the reg-suit process. Verify the identity and credentials in that execution environment.
Workload on Google Cloud	Use the workload’s attached service account.	Grant that identity the bucket access needed by the workflow.
External CI runner	Use workload identity federation where supported and appropriate; the plugin README also recommends a service account for CI.	Prefer a credential mechanism that fits organizational policy. Avoid distributing long-lived service-account keys when federation is available.

The plugin documentation does not prescribe a universal IAM role or bucket policy. Determine the object operations needed for your workflow, then grant the executing identity the narrowest permissions that support them. Bucket existence and project IAM are separate from reg-suit’s JSON configuration.

Local development checklist

Create or select the GCS bucket and note its exact name.
Set REG_SUIT_GCS_BUCKET in the shell or environment where reg-suit will run.
Set up Google ADC for your user or an approved impersonated identity.
Confirm that identity has the required access to the target bucket.
Run reg-suit from the project root so it reads the intended regconfig.json.

CI checklist

Set the bucket variable in the CI job or deployment environment.
Configure ADC for the CI workload using the organization-approved credential method.
Ensure the credentials are available to the exact job step or container that invokes reg-suit.
Grant the workload identity only the bucket operations the publishing and fetching workflow requires.
Do not print credential material into job logs. Check the provider’s secret handling and identity configuration separately from reg-suit.

4. Run the workflow

Once the configuration and credentials are ready, run:

npx reg-suit run

Reg-suit performs the visual test workflow, including comparison and publishing, along with any configured notifications. Publisher plugins can fetch expected snapshots and publish current images and reports; the GCS plugin uses the configured bucket as its storage backend. Use the project’s established build and snapshot-generation steps before this command when your workflow requires them.

Environment variable example

Set the environment variable in the same shell or CI step that invokes reg-suit. For a local POSIX shell:

export REG_SUIT_GCS_BUCKET="your-gcs-bucket"
npx reg-suit run

In CI, add REG_SUIT_GCS_BUCKET through that provider’s environment-variable configuration. This example avoids assuming a particular CI product’s syntax. If the variable is unset or the substitution is not recognized by the installed reg-suit version, use the configuration mechanism documented for that version and check the resolved plugin settings without exposing secrets.

5. Verify the setup

Check that the project root contains the intended regconfig.json and that the GCS publisher appears beneath plugins.
Confirm the bucket name resolves to the expected value in the execution environment.
Verify ADC as the identity used by the reg-suit process, not only through a separate CLI login.
Run the command and inspect its result for authentication, permission, or storage errors.
Inspect the target bucket for newly published objects and confirm the report URI works for the intended readers or proxy.

Common errors and fixes

Symptom	Likely cause	What to check
Missing or invalid bucket configuration	`bucketName` is absent, misspelled, or its environment placeholder did not resolve.	Check the plugin key and setting in `regconfig.json`, then confirm the bucket environment variable exists in the command’s process.
Credentials not found	ADC is not available to the runtime, even if a user has authenticated the gcloud CLI.	Follow Google’s ADC guidance for that environment and verify credentials from the same job, container, or shell that runs reg-suit.
Permission denied or access denied	The ADC identity lacks one or more required bucket operations, or the wrong identity is active.	Identify the principal actually used and review its project and bucket access. Grant only the needed operations under your organization’s policy.
Objects publish, but report links fail	The default URI may not match the way reports are served, or a proxy expects another public-facing prefix.	Check the generated report URI and proxy routing. Configure `customUri` only when the report-serving path requires an override.
Report appears under an unexpected path	`pathPrefix` or the plugin version’s path behavior differs from the assumed example.	Inspect actual object names in the bucket and consult the README matching the installed plugin version.
Works locally but fails in CI	Local user ADC is not present in CI, or the job step/container does not receive the intended workload identity.	Set up ADC for the CI environment explicitly, verify the active identity there, and check bucket permissions.
CLI login succeeds but reg-suit still cannot access GCS	gcloud CLI credentials and ADC are distinct in some situations.	Use Google’s ADC setup process and test from the same runtime that executes the publisher.

Performance, reliability, and cost considerations

Performance: the guide and plugin documentation do not provide benchmark figures. Runtime depends on the overall visual test workflow, the amount of snapshot data, network conditions, and storage operations. Keep snapshot output scoped to what the visual test needs.
Reliability: publishing depends on both reg-suit execution and the availability of valid ADC and bucket permissions. External CI should use a workload identity configuration that remains available to the job and is managed through its identity provider. Confirm report links independently if a proxy or custom URI is involved.
Cost: no cost estimate can be derived from the plugin configuration alone. Consider your GCS storage, request, retention, and data transfer charges under your Google Cloud terms. A path prefix organizes objects; it does not set retention or lifecycle rules.
Versioning: avoid relying on a remembered package version. Check the current npm package and repository before pinning or upgrading, then validate generated paths and authentication behavior in your project.

Or skip the browser setup

Reg-suit stores visual test snapshots and reports; ScreenshotNeo is a separate website screenshot API and MCP server for developers. If you need website captures for a visual check or another workflow, a single GET request returns an image or PDF. The API accepts common screenshot API parameter names, which can make switching easier. See the ScreenshotNeo site and API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners are accepted and removed before capture; 60+ known consent platforms, newsletter popups, and chat widgets can be removed, with each step configurable.
Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers identify the page verdict and billing status.
An MCP server gives AI agents tools for screenshots, page information, and PDF capture.
The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Does `customUri` make a private bucket public?

No. It changes the report URI prefix used by the plugin. Bucket access and report visibility still depend on your Google Cloud configuration and serving path.

Can I put the bucket name directly in the configuration?

Yes. The documented required setting is bucketName. An environment variable is useful when environments use different buckets or when configuration values should not be committed.

Is reg-suit’s GCS publisher a replacement for screenshot capture?

No. It publishes reg-suit visual regression artifacts to GCS. The browser and snapshot generation remain part of the visual testing workflow.

Where should I investigate if the plugin’s output path differs from an example?

Inspect the objects actually written to the bucket and check the README for the plugin version installed in your project. The example prefix and report paths should not be treated as a universal path guarantee.