Cloud Run Preview - Quick Start Guide¶

What is it?¶

When you create a PR with backend changes, a preview deployment is automatically created on Google Cloud Run. This gives you a live URL to test your backend changes before merging.

How to use it¶

1. Create a PR¶

Create a PR targeting the develop branch with changes to: - apps/perci-platform-backend/functions/** - apps/perci-platform-backend/Dockerfile

2. Wait for deployment¶

The GitHub Actions workflow will automatically: 1. Build your TypeScript code 2. Create a Docker image 3. Deploy to Cloud Run 4. Comment on your PR with the preview URL

This typically takes 5-10 minutes.

3. Test your changes¶

Once deployed, you'll get a comment with your preview URL:

🚀 Backend Preview Deployed

Service URL: https://backend-preview-pr-123-abc123.europe-west2.run.app

Available Endpoints:
- API: https://backend-preview-pr-123-abc123.europe-west2.run.app/api/v1
- Member BFF: https://backend-preview-pr-123-abc123.europe-west2.run.app/bff/v1
- Clinical BFF: https://backend-preview-pr-123-abc123.europe-west2.run.app/bff_clinical/v1
- Clinical Media: https://backend-preview-pr-123-abc123.europe-west2.run.app/bff_clinical_media/v1
- Health Check: https://backend-preview-pr-123-abc123.europe-west2.run.app/_health

4. Make additional changes¶

Push new commits to your PR branch. The preview will automatically update with your changes.

5. Cleanup¶

When you close or merge the PR, the preview is automatically deleted.

Testing with frontend apps¶

You can point your frontend apps to use the preview backend by updating the API URLs:

Member App¶

// In your flutter app config
final apiBaseUrl = 'https://backend-preview-pr-123-abc123.europe-west2.run.app/bff/v1';

Clinical App¶

// In your flutter app config
final apiBaseUrl = 'https://backend-preview-pr-123-abc123.europe-west2.run.app/bff_clinical/v1';

Important Notes¶

Environment¶

Preview uses staging environment configuration
Connects to staging database and services
Uses staging credentials and secrets
Does NOT affect production

Data¶

Only use test data with previews
Changes affect the staging environment
Be careful with destructive operations

Performance¶

Preview services scale to zero when not in use
First request after idle may be slower (cold start)
Subsequent requests are fast

Monitoring¶

Check Cloud Run logs for debugging:

gcloud run services logs read backend-preview-pr-{PR_NUMBER} \
  --region europe-west2 \
  --project perci-platform-staging

Cost¶

Previews are optimized for cost
Scale to zero = no cost when idle
Automatically cleaned up when PR closes

Troubleshooting¶

Preview not deploying?¶

Check the GitHub Actions tab for workflow runs
Look for errors in the "Backend - Deploy Cloud Run Preview" workflow
Common issues:
TypeScript compilation errors
Missing secrets in Secret Manager
Insufficient GCP permissions

503 Service Unavailable?¶

Service might be starting (cold start) - wait 30 seconds and retry
Check Cloud Run logs for errors
Verify environment variables are set correctly

Changes not showing up?¶

Ensure your commit triggered the workflow (check Actions tab)
Verify the workflow completed successfully
Hard refresh your browser (clear cache)
Check that your code changes were actually in the affected paths

Local Testing¶

Before creating a PR, you can test the Cloud Run adapter locally:

# Navigate to functions directory
cd apps/perci-platform-backend/functions

# Build TypeScript
npm run build

# Set environment variables
cp .env.sample .env
# Edit .env with your configuration

# Run the Cloud Run adapter
node lib/cloudrun.js

The service will be available at http://localhost:8080.

Need Help?¶

If you encounter issues: 1. Check the full documentation 2. Ask in the #platform-engineering Slack channel 3. Tag @platform-team in your PR for assistance