Skip to main content

GCP Setup

Use this page as the top-level setup checklist. The detailed instructions are split into the three setup phases that happen in the app:

  1. Google OAuth setup connects Playrunner to your Google account.
  2. Project and Region setup saves the existing Google Cloud project and Cloud Run region Playrunner should use.
  3. Terraform setup creates the Google Cloud infrastructure inside that existing project.

OAuth, Project and Region, and Terraform are separate on purpose. OAuth saves credentials, Project and Region saves the existing GCP project ID and Cloud Run region in Playrunner's local database, and Terraform reads those saved values through the setup script and writes infra/gcp/terraform.tfvars.

First-Time Setup Order​

  1. Start Playrunner locally:
./start-local.sh
  1. Open Integrations and choose Connect to GCP.
  2. Complete Google OAuth setup.
  3. Complete Project and Region setup. Create the project in GCP first if it does not already exist, then save the project ID and Cloud Run region in the dialog.
  4. From the repo root, generate infra/gcp/terraform.tfvars:
./infra/gcp/scripts/setup-terraform.sh
  1. Review the generated file, then run Terraform directly:
terraform -chdir=infra/gcp init
terraform -chdir=infra/gcp plan
terraform -chdir=infra/gcp apply
  1. After Terraform succeeds, publish the runtime images:
./infra/gcp/scripts/push-runners.sh --target all --yes
  1. In the editor, select the GCP runner and run a workflow.

What Each Step Owns​

StepOwnerWhat it creates or saves
OAuthConnect to GCP dialogGoogle OAuth tokens in the local CloudCredential row
Project & RegionConnect to GCP dialogExisting Google Cloud project ID, Cloud Run region, scheduler service account email, and standard Playrunner runner defaults
Terraforminfra/gcpRequired APIs, Artifact Registry repositories, API Cloud Run service, shared Pub/Sub topic, and Cloud Scheduler service account
Image publishpush-runners.shAPI, Orchestrator, and Playwright runner images, plus Cloud Run service redeploys using the standard generated image paths

The Connect to GCP dialog does not ask for image URI templates. Playrunner generates the standard Artifact Registry paths from the saved region:

<region>-docker.pkg.dev/{projectId}/orchestrator/playrunner-orchestrator:latest
<region>-docker.pkg.dev/{projectId}/playwright-runner/playrunner-playwright-runner-{runtime}:{version}

Scheduler Service Account​

The full Cloud Scheduler service account email is not something the user should type into the dialog. The generated terraform.tfvars contains this ID:

scheduler_service_account_id = "playrunner-scheduler"

Terraform combines that ID with project_id to create the service account and prints the full email as the scheduler_service_account_email output. For a project named my-gcp-project, the output is:

playrunner-scheduler@my-gcp-project.iam.gserviceaccount.com

Local Scheduler Callbacks​

Most GCP workflow debugging does not need a public tunnel because the API pulls runner events from Pub/Sub over outbound HTTPS.

You only need a tunnel when Google Cloud Scheduler must call a local Playrunner API for enabled schedules. In that case, start a tunnel to the local API port:

cloudflared tunnel --url http://127.0.0.1:3011

Use the API port printed by ./start-local.sh or the PORT value in apps/api/.env if your local API is not on 3011. Put Cloudflare's printed https://...trycloudflare.com URL in apps/api/.env:

PLAYRUNNER_PUBLIC_API_URL=https://your-tunnel.trycloudflare.com

Restart the local API after changing apps/api/.env, then save the workflow with the schedule enabled.

More Detail​