Google Cloud Run Provider

Deploy preview environments to Google Cloud Run — the default provider for Previewops.

How it works

Build: submits a build to Cloud Build, which clones the repo and builds the Docker image, pushing it to Artifact Registry.
Deploy: creates or updates a Cloud Run v2 service. The service scales to zero when idle.
Delete: deletes the Cloud Run service and its Artifact Registry image.
List: lists all Cloud Run services in the project filtered by the previewops=true resource label.

Credentials required

Plan	What to do
Pro, Enterprise, Custom	Nothing — Previewops manages GCP on your behalf
Free, Premium BYOC	Follow the steps below to connect your own GCP project

Setup (Free and Premium BYOC plans)

You need a GCP project with billing enabled and the following APIs enabled:

Cloud Run API
Cloud Build API
Artifact Registry API

Step 1 — Create an Artifact Registry repository

gcloud artifacts repositories create previewops \
  --repository-format=docker \
  --location=us-central1 \
  --project=YOUR_PROJECT_ID

Step 2 — Create a service account and grant roles

gcloud iam service-accounts create previewops-byoc \
  --project=YOUR_PROJECT_ID

for role in roles/cloudbuild.builds.editor roles/artifactregistry.writer roles/run.admin roles/iam.serviceAccountUser; do
  gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member="serviceAccount:previewops-byoc@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
    --role="$role"
done

Step 3 — Download the key and base64-encode it

gcloud iam service-accounts keys create sa-key.json \
  --iam-account=previewops-byoc@YOUR_PROJECT_ID.iam.gserviceaccount.com

base64 -i sa-key.json   # copy the output — this is your GCP_SA_KEY value

Step 4 — Add credentials in the dashboard

Log in to the Previewops dashboard.
Click Credentials in the left sidebar.
Select cloud-run from the provider dropdown.
Add the following keys:

Key	Required	Description
`GCP_PROJECT_ID`	Yes	Your GCP project ID
`GCP_SA_KEY`	Yes	Base64-encoded service account JSON key (from Step 3)
`GCP_ARTIFACT_REGISTRY_REPO`	Yes	Full registry path, e.g. `us-central1-docker.pkg.dev/my-project/previewops`
`GCP_REGION`	No	Region override (default: `us-central1`)

Step 5 — Configure the repo

Cloud Run is the default provider — no .previewops.yaml is required to get started. When you add one, a complete example showing all available options:

# .previewops.yaml
provider: cloud-run               # optional — cloud-run is the default

# Common options — all optional
concurrency: 3                    # max simultaneous active previews per repo
ttlHours: 24                      # auto-delete after N hours (default: 24)
port: 3000                        # optional — auto-detected from your Dockerfile EXPOSE; falls back to 8080
memory: 512Mi                     # container memory (default: 512Mi)
cpu: 1                            # container vCPU (default: 1)
dockerfile: Dockerfile            # Dockerfile path relative to repo root (default: Dockerfile)
buildContext: .                   # Docker build context (default: .)
env:
  NODE_ENV: preview               # inject env vars into the preview container

Cloud Run has no providerConfig YAML options. The GCP project, service account key, registry path, and region are all stored as dashboard credentials (see Step 4 above).

Step 6 — Verify

Comment /validate-previewops on any open PR. The bot confirms that Cloud Build and Cloud Run APIs are reachable with the credentials you provided.

Notes

Preview services are named prev-{owner}-{repo}-pr{number} and deployed in us-central1 by default.
Cloud Run scales to zero — no idle cost between requests.
Preview URLs use HTTPS automatically via Cloud Run's managed TLS.

Troubleshooting

Error	Fix
`Permission denied on Cloud Build`	Service account missing `roles/cloudbuild.builds.editor`
`PERMISSION_DENIED: Cloud Run API not enabled`	Run `gcloud services enable run.googleapis.com` in your project
Image not found in Cloud Run	Build failed — check Cloud Build logs in the GCP console
`GCP_SA_KEY is not valid base64-encoded JSON`	Re-encode: `base64 -i sa-key.json` and store the output as `GCP_SA_KEY`
`GCP_SA_KEY JSON must contain client_email and private_key`	Wrong key format — use the full JSON downloaded from IAM → Service Accounts
`GCP_PROJECT_ID is required when GCP_SA_KEY is set`	Add `GCP_PROJECT_ID` to your dashboard credentials
Build quota exceeded	120 min/day free Cloud Build tier hit — builds will queue automatically
`❌ Failed` with no detail in the PR comment	The container started but its process exited immediately. Open Cloud Run logs in the GCP console for the actual error. A common cause is a startup command that crashes (e.g. a database migration that fails). Example: `prisma migrate deploy` returns `P3005` when the target database was not created via Prisma migrations — see databases.md for safe database setup with the Preview DB add-on.
Preview fails with `container failed to start and listen on PORT=X`	The port in your Dockerfile `EXPOSE` statement does not match the `port:` value in `.previewops.yaml`. Update one to match the other. The default port is `8080`.