Deploying to Google Cloud Run¶

This guide covers deploying the bd-clickup webhook server to Google Cloud Run for production use.

Prerequisites¶

Google Cloud Account with billing enabled
gcloud CLI installed and authenticated
Docker installed locally
ClickUp API Token from https://app.clickup.com/settings/apps

Quick Deploy¶

# Set your ClickUp API token
export CLICKUP_API_TOKEN=pk_your_token_here

# Deploy (uses current gcloud project)
./scripts/deploy.sh

# Or specify project and region
./scripts/deploy.sh my-gcp-project europe-west1

Manual Deployment Steps¶

1. Configure GCP Project¶

# Set your project
gcloud config set project YOUR_PROJECT_ID

# Enable required APIs
gcloud services enable \
    cloudbuild.googleapis.com \
    run.googleapis.com \
    containerregistry.googleapis.com

2. Build and Push Docker Image¶

# Build locally
docker build -t gcr.io/YOUR_PROJECT_ID/bd-clickup-webhook:latest .

# Push to Container Registry
docker push gcr.io/YOUR_PROJECT_ID/bd-clickup-webhook:latest

3. Deploy to Cloud Run¶

gcloud run deploy bd-clickup-webhook \
    --image gcr.io/YOUR_PROJECT_ID/bd-clickup-webhook:latest \
    --region europe-west1 \
    --platform managed \
    --allow-unauthenticated \
    --memory 512Mi \
    --cpu 1 \
    --min-instances 0 \
    --max-instances 2 \
    --timeout 300 \
    --set-env-vars "CLICKUP_API_TOKEN=pk_your_token"

4. Get Service URL¶

gcloud run services describe bd-clickup-webhook \
    --region europe-west1 \
    --format 'value(status.url)'

5. Register Webhook with ClickUp¶

python -m beads_clickup.cli webhook-register https://bd-clickup-webhook-xxxxx.run.app/webhook/clickup

Using Secret Manager (Recommended)¶

Instead of passing the API token as an environment variable, use Secret Manager:

# Create secret
echo -n "pk_your_clickup_token" | gcloud secrets create clickup-api-token \
    --replication-policy="automatic" \
    --data-file=-

# Grant Cloud Run access
gcloud secrets add-iam-policy-binding clickup-api-token \
    --member="serviceAccount:YOUR_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"

# Deploy with secret reference
gcloud run deploy bd-clickup-webhook \
    --image gcr.io/YOUR_PROJECT_ID/bd-clickup-webhook:latest \
    --region europe-west1 \
    --platform managed \
    --allow-unauthenticated \
    --set-secrets "CLICKUP_API_TOKEN=clickup-api-token:latest"

Automated Deployments with Cloud Build¶

The included cloudbuild.yaml enables automatic deployments:

Setup Cloud Build Trigger¶

Go to Cloud Build Triggers
Create a new trigger:
Event: Push to branch
Branch: ^main$
Configuration: Cloud Build configuration file
Location: /cloudbuild.yaml
Add substitution variables:
_REGION: europe-west1
_CLICKUP_API_TOKEN: (from Secret Manager)

Now every push to main will automatically deploy!

Configuration¶

Environment Variables¶

Variable	Required	Description
`CLICKUP_API_TOKEN`	Yes	ClickUp API token
`PORT`	No	Server port (default: 8080, set by Cloud Run)
`WEBHOOK_SECRET`	No	Secret for webhook signature verification

Resource Recommendations¶

Workload	Memory	CPU	Instances
Light (< 10 webhooks/min)	256Mi	1	0-1
Medium (< 100 webhooks/min)	512Mi	1	0-2
Heavy (> 100 webhooks/min)	1Gi	2	1-4

Monitoring¶

View Logs¶

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=bd-clickup-webhook" \
    --limit 50 \
    --format "table(timestamp,textPayload)"

Check Service Health¶

curl https://bd-clickup-webhook-xxxxx.run.app/health

Troubleshooting¶

Webhook not receiving events¶

Check webhook is registered: python -m beads_clickup.cli webhook-list
Check Cloud Run logs for errors
Verify the service URL is correct and publicly accessible

Authentication errors¶

Verify CLICKUP_API_TOKEN is set correctly
Check token hasn't expired
Ensure token has access to the workspace

Cold start delays¶

Cloud Run scales to zero when idle. First request after idle period may be slow (~2-5s). To avoid: set --min-instances 1 (increases cost).

Cost Estimation¶

Cloud Run pricing (approximate, varies by region): - CPU: $0.00002400/vCPU-second - Memory: $0.00000250/GiB-second - Requests: $0.40/million

With min-instances=0 and light usage: - ~$0-5/month for occasional webhooks - ~$10-20/month for continuous use

Security Considerations¶

Use Secret Manager for API tokens
Enable webhook signature verification if supported
Restrict IAM permissions to minimum required
Monitor for unusual activity in Cloud Logging