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.
Navigate to Installations → select your organisation → Credentials.
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 provider field is required in .previewops.yaml:

# .previewops.yaml
concurrency: 3
ttlHours: 24
memory: 512Mi
cpu: 1
port: 8080

To set it explicitly:

provider: cloud-run

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