---

name: gcp-cloud-run-deploy description: Deploy Docker containers to GCP Cloud Run with full CI/CD pipeline. Use when setting up GCP Cloud Run deployment, configuring GitHub Actions for GCP, setting up Artifact Registry, or automating container deployments to Google Cloud.

GCP Cloud Run Deployment Guide

End-to-end setup for deploying the zkmin protocol Docker container to GCP Cloud Run with GitHub Actions CI/CD.

Prerequisites

• Google Cloud account with billing enabled
• GitHub repository with Dockerfile
• gcloud CLI installed locally (brew install google-cloud-sdk)

Phase 1: GCP Project Setup

1.1 Authenticate and Select Project

Copy# Login to GCP
gcloud auth login

# List available projects
gcloud projects list

# Create new project (if needed)
gcloud projects create PROJECT_ID --name="Project Name"

# Set active project
gcloud config set project PROJECT_ID

# Enable billing (required for Cloud Run)
# Visit: https://console.cloud.google.com/billing/linkedaccount?project=PROJECT_ID

1.2 Enable Required APIs

Copygcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  iam.googleapis.com \
  iamcredentials.googleapis.com

1.3 Create Artifact Registry Repository

Copy# Create Docker repository in Artifact Registry
gcloud artifacts repositories create zkmin \
  --repository-format=docker \
  --location=us-central1 \
  --description="zkmin protocol container images"

# Verify creation
gcloud artifacts repositories list --location=us-central1

Phase 2: Service Account Setup

2.1 Create Deployment Service Account

Copy# Create service account for CI/CD
gcloud iam service-accounts create github-actions \
  --display-name="GitHub Actions Deployment"

# Get the full service account email
SA_EMAIL="github-actions@PROJECT_ID.iam.gserviceaccount.com"

2.2 Grant Required Permissions

CopyPROJECT_ID=$(gcloud config get-value project)
SA_EMAIL="github-actions@${PROJECT_ID}.iam.gserviceaccount.com"

# Artifact Registry Writer (push images)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/artifactregistry.writer"

# Cloud Run Developer (deploy services)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/run.developer"

# Service Account User (to act as the service account)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/iam.serviceAccountUser"

Phase 3: Workload Identity Federation (Recommended)

More secure than service account keys - uses OIDC tokens from GitHub.

3.1 Create Workload Identity Pool

CopyPROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

# Create identity pool
gcloud iam workload-identity-pools create "github-pool" \
  --location="global" \
  --display-name="GitHub Actions Pool"

# Create OIDC provider
gcloud iam workload-identity-pools providers create-oidc "github-provider" \
  --location="global" \
  --workload-identity-pool="github-pool" \
  --display-name="GitHub Provider" \
  --attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner" \
  --issuer-uri="https://token.actions.githubusercontent.com"

3.2 Allow GitHub to Impersonate Service Account

CopyPROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
SA_EMAIL="github-actions@${PROJECT_ID}.iam.gserviceaccount.com"
GITHUB_ORG="YOUR_GITHUB_USERNAME_OR_ORG"  # Replace with your GitHub org/username
REPO_NAME="zkmin"  # Replace with your repo name

# Allow the GitHub repo to impersonate the service account
gcloud iam service-accounts add-iam-policy-binding $SA_EMAIL \
  --project=$PROJECT_ID \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/github-pool/attribute.repository/${GITHUB_ORG}/${REPO_NAME}"

3.3 Get Workload Identity Provider Resource Name

Copy# Save this - needed for GitHub Actions workflow
echo "projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/github-pool/providers/github-provider"

Phase 4: GitHub Actions Secrets

Add these secrets to your GitHub repository:

Adding Secrets via gh CLI

Copy# Set secrets using GitHub CLI
gh secret set GCP_PROJECT_ID --body "your-project-id"
gh secret set GCP_REGION --body "us-central1"
gh secret set GCP_WORKLOAD_IDENTITY_PROVIDER --body "projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/github-pool/providers/github-provider"
gh secret set GCP_SERVICE_ACCOUNT --body "github-actions@your-project-id.iam.gserviceaccount.com"

Phase 5: GitHub Actions Workflow

Create .github/workflows/deploy-cloud-run.yml:

Copyname: Deploy to Cloud Run

on:
  push:
    branches: [main]
    paths:
      - 'protocol.zkmin/**'
      - '.github/workflows/deploy-cloud-run.yml'
  workflow_dispatch:

env:
  SERVICE_NAME: zkmin-protocol
  IMAGE_NAME: us-central1-docker.pkg.dev/${{ secrets.GCP_PROJECT_ID }}/zkmin/protocol

permissions:
  contents: read
  id-token: write  # Required for Workload Identity Federation

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: protocol.zkmin

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Google Auth
        id: auth
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
          service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}

      - name: Set up Cloud SDK
        uses: google-github-actions/setup-gcloud@v2
        with:
          project_id: ${{ secrets.GCP_PROJECT_ID }}

      - name: Configure Docker
        run: gcloud auth configure-docker us-central1-docker.pkg.dev --quiet

      - name: Build and Push Image
        run: |
          VERSION=$(git describe --tags --always --dirty 2>/dev/null || echo "dev")
          COMMIT=$(git rev-parse --short HEAD)
          BUILD_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
          
          docker build \
            --build-arg VERSION=$VERSION \
            --build-arg COMMIT=$COMMIT \
            --build-arg BUILD_TIME=$BUILD_TIME \
            -t ${{ env.IMAGE_NAME }}:${{ github.sha }} \
            -t ${{ env.IMAGE_NAME }}:latest \
            .
          
          docker push ${{ env.IMAGE_NAME }}:${{ github.sha }}
          docker push ${{ env.IMAGE_NAME }}:latest

      - name: Deploy to Cloud Run
        uses: google-github-actions/deploy-cloudrun@v2
        with:
          service: ${{ env.SERVICE_NAME }}
          region: ${{ secrets.GCP_REGION }}
          image: ${{ env.IMAGE_NAME }}:${{ github.sha }}
          flags: |
            --port=8081
            --cpu=1
            --memory=512Mi
            --min-instances=0
            --max-instances=10
            --allow-unauthenticated
            --set-env-vars=ENVIRONMENT=production

      - name: Show Service URL
        run: |
          echo "Service deployed successfully!"
          gcloud run services describe ${{ env.SERVICE_NAME }} \
            --region=${{ secrets.GCP_REGION }} \
            --format='value(status.url)'

Phase 6: First Manual Deployment (Verify Setup)

Test the setup before relying on CI/CD:

Copycd protocol.zkmin

# Build and tag image locally
docker build -t us-central1-docker.pkg.dev/PROJECT_ID/zkmin/protocol:manual .

# Configure Docker for Artifact Registry
gcloud auth configure-docker us-central1-docker.pkg.dev

# Push to Artifact Registry
docker push us-central1-docker.pkg.dev/PROJECT_ID/zkmin/protocol:manual

# Deploy to Cloud Run
gcloud run deploy zkmin-protocol \
  --image us-central1-docker.pkg.dev/PROJECT_ID/zkmin/protocol:manual \
  --region us-central1 \
  --port 8081 \
  --cpu 1 \
  --memory 512Mi \
  --min-instances 0 \
  --max-instances 10 \
  --allow-unauthenticated

# Get service URL
gcloud run services describe zkmin-protocol --region us-central1 --format='value(status.url)'

Cloud Run Configuration Options

Environment Variables

Copy# Set environment variables
gcloud run services update zkmin-protocol \
  --region us-central1 \
  --set-env-vars="LOG_LEVEL=info,CHAIN_ID=mainnet"

Secrets (from Secret Manager)

Copy# Create a secret
echo -n "my-secret-value" | gcloud secrets create MY_SECRET --data-file=-

# Grant access to Cloud Run service account
gcloud secrets add-iam-policy-binding MY_SECRET \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

# Mount as environment variable
gcloud run services update zkmin-protocol \
  --region us-central1 \
  --set-secrets="MY_SECRET=MY_SECRET:latest"

Custom Domain

Copy# Map custom domain
gcloud run domain-mappings create \
  --service zkmin-protocol \
  --domain your-domain.com \
  --region us-central1

Troubleshooting

Common Issues

Build fails - permission denied

Copy# Ensure Artifact Registry access
gcloud artifacts repositories get-iam-policy zkmin --location=us-central1

Deploy fails - service account missing permissions

Copy# List current bindings
gcloud projects get-iam-policy PROJECT_ID --flatten="bindings[].members" \
  --filter="bindings.members:github-actions@" \
  --format="table(bindings.role)"

Workload Identity not working

Copy# Verify pool exists
gcloud iam workload-identity-pools describe github-pool --location=global

# Verify provider
gcloud iam workload-identity-pools providers describe github-provider \
  --location=global --workload-identity-pool=github-pool

Viewing Logs

Copy# Stream logs
gcloud run services logs read zkmin-protocol --region us-central1 --tail=50

# View in console
# https://console.cloud.google.com/run/detail/us-central1/zkmin-protocol/logs

Alternative: Service Account Key (Less Secure)

If Workload Identity doesn't work for your setup:

Copy# Create key (store securely!)
gcloud iam service-accounts keys create key.json \
  --iam-account=github-actions@PROJECT_ID.iam.gserviceaccount.com

# Base64 encode for GitHub secret
base64 -i key.json | tr -d '\n'

# Add as GCP_SA_KEY secret, then update workflow:
# Replace google-github-actions/auth step with:
# credentials_json: ${{ secrets.GCP_SA_KEY }}

Optional: GCP MCP Server

For interactive GCP management from Cursor, install the GCP MCP server:

See mcp-setup.md for GCP MCP server configuration.

Quick Reference