Forem: Rashika Karki

Building LearnForge: Multi-Agent AI Learning Platform on Cloud Run with Google ADK

Rashika Karki — Sat, 08 Nov 2025 21:55:23 +0000

Note: I wrote this article for the Google Cloud Run Hackathon 2025.

I built LearnForge, an AI-powered learning platform that does something no other platform does: it has a conversation with you, figures out what you actually want to learn (not what you think you want), researches the topic in real-time, and then creates a personalized learning journey that adapts to how you learn.

Built on Google Cloud Run and Agent Development Kit (ADK) with 12 specialized AI agents working together, it handles everything from vague "I want to learn AI" statements to structured, adaptive learning missions that remember where you left off—even if you come back weeks later.

The result? A learning experience that feels like having a personal tutor who never forgets, never gets tired, and actually knows what they're talking about.

The Problem: Why Online Learning is Hard (And How I Fixed It)

Let me paint you a picture. You're sitting at your computer, motivated, ready to learn something new. You type "learn Python" into a course platform. You get 47 courses. You pick one. Three hours later, you realize:

You're learning about data types when you wanted to build web APIs
The instructor assumes you know nothing, but you've coded in JavaScript for years
The examples are boring and don't relate to what you actually want to build
You're on lesson 12 of 200, and you have no idea if you're learning the right things

Sound familiar? This is the fundamental problem with online learning: one-size-fits-all doesn't fit anyone.

The Real Problem

Here's what's broken:

1. The Goal Mismatch

When someone says "I want to learn AI," they could mean:

Building chatbots for customer service
Fine-tuning language models for text summarization
Understanding neural network architectures
Creating computer vision systems for medical imaging

But traditional platforms give everyone the same "Introduction to AI" course. It's like asking "Where do you want to go?" and getting the same map regardless of whether you said "the grocery store" or "Mount Everest."

2. The Experience Gap

A beginner needs hand-holding. An intermediate learner needs to skip basics. An expert needs advanced concepts. But courses are static, they can't adapt.

3. The Context Loss

You start a course on Monday. Life happens. You come back on Friday. The platform has no idea:

What you were learning
How well you understood it
Where you left off
What you were confused about

4. The Content Problem

Most courses are pre-recorded, static content. But learning is dynamic. You might need:

A different explanation when you're confused
Real-world examples relevant to your goals
Video tutorials when you're a visual learner
Step-by-step guides when you prefer structured learning

The Solution: AI That Actually Understands

What if, instead of picking from a catalog, you could just... talk to an AI?

You: "I want to learn AI"

AI: "Great! I checked what's trending in AI learning. Most people start with either model training, data pipelines, or building AI-powered applications. Which direction do you want to focus on?"

You: "Building applications, I think"

AI: "Got it. Are you thinking of chatbots, image generators, or recommendation systems?"

You: "Chatbots"

AI: "Perfect! So you want to learn AI chatbot development, at an intermediate level, focusing on building real applications. Does that sound right?"

And then here's the magic the AI:

Researches the topic using Google Search
Creates a personalized learning mission with checkpoints
Guides you through it conversationally
Adapts content based on your responses
Remembers everything, even if you come back weeks later

This isn't a chatbot. This is a multi-agent AI system that coordinates 12 specialized agents to create a complete learning experience.

How It Works: The Magic Behind the Scenes

LearnForge uses Google's Agent Development Kit (ADK) to orchestrate 12 specialized AI agents. Think of it like a well-coordinated team where each agent has a specific job, but to the user, it feels like talking to one intelligent tutor.

Phase 1: Mission Creation (Meet Polaris)

When you first connect, you meet Polaris, the Pathfinder. Polaris doesn't just ask questions it researches your topic in real-time to ask intelligent, informed questions.

You: "I want to learn machine learning"

Polaris: [Searches Google for "machine learning learning paths 2025"]
         [Finds that most people focus on: model training, data prep, or deployment]

         "When people explore 'machine learning,' they often focus on 
         model training, data prep, or deployment. Which of these do 
         you want to master first?"

Behind the scenes, Polaris uses:

Pathfinder Agent: Conversational goal clarification with research
Search Agent: Google Search API for real-time topic research
Mission Curator Agent: Converts your goals into structured learning missions

The result? Instead of a generic "Machine Learning 101" course, you get a mission tailored to your specific goal: "Building Production ML Systems with Python and TensorFlow" or "Data Preparation for Machine Learning Models."

Phase 2: Learning Execution (Meet Lumina)

Once your mission is created, Lumina takes over. Lumina is your personal learning companion patient, adaptive, and genuinely helpful.

Lumina guides you through checkpoints (bite-sized learning goals) using a sophisticated multi-agent system:

Lumina Orchestrator (invisible coordinator)
    ├── Greeter: "Welcome! Let's start your journey..."
    ├── Flow Briefer: "Next up: Understanding Neural Networks. Ready?"
    ├── Sensei (your teacher)
    │   ├── Content Composer
    │   │   ├── Content Searcher: Finds educational articles via Google Search
    │   │   ├── Video Selector: Curates YouTube videos (4-20 min, educational)
    │   │   └── Content Formatter: Personalizes content for your learning style
    │   └── Evaluates your understanding
    ├── Help Desk: Answers off-topic questions
    └── Wrapper: Celebrates your completion

Here's what makes this special:

1. Content is Generated in Real-Time

When Sensei teaches you about "neural networks," it doesn't pull from a static database. Instead:

Content Searcher finds the latest, most relevant articles
Video Selector curates educational YouTube videos (filtered by duration, category, relevance)
Content Formatter adapts everything to your learning style (visual? examples? step-by-step?)

2. It Adapts to Your Understanding

Sensei: "Can you explain how backpropagation works?"

You: "It's like... adjusting weights based on errors?"

Sensei: "You're on track with the error part! Let me clarify the 
        weight adjustment mechanism..."
        [Delegates to Content Composer for a clearer explanation]
        [Presents it naturally, as if Sensei knew it all along]

3. It Remembers Everything

This is where it gets interesting. Most chatbots lose context when you close the browser. LearnForge uses Cloud SQL with DatabaseSessionService to persist everything:

Which checkpoint you're on
What content was presented
How you responded to questions
What you were confused about
Your learning preferences

Close your browser, come back next week, switch devices it all just works.

The Architecture: How 12 Agents Work Together Seamlessly

The technical magic is in the orchestration. LearnForge uses Google ADK's hierarchical agent system to coordinate specialized agents without the user ever knowing.

Silent Orchestration: The Invisible Hand

The orchestrators are completely invisible. Users never see messages like "Let me hand you over to the Sensei..." Instead, transitions are seamless:

# What the user sees:
Sensei: "Let's explore neural networks! Here's how they work..."

# What's actually happening:
Orchestrator → delegates to Sensei → Sensei delegates to Content Composer 
→ Content Composer chains: Searcher → Video Selector → Formatter
→ Content flows back → Sensei presents it naturally

The orchestrator's instruction is explicit:

root_agent = LlmAgent(
    instruction="""
    YOU MUST NEVER TALK TO THE USER DIRECTLY.
    YOU MUST NEVER ACKNOWLEDGE DELEGATIONS.
    The user should ONLY see responses from sub-agents.
    """
)

Content Authority Separation: Why Teaching Agents Don't Generate Content

Here's an insight that improved content quality dramatically: teaching agents shouldn't generate content they should delegate to specialized agents.

sensei_agent = LlmAgent(
    instruction="""
    YOU ARE FORBIDDEN FROM CREATING ANY TEACHING CONTENT.
    You must delegate ALL content creation to content_composer_agent.

    YOU CAN:
    - Ask questions
    - Evaluate answers
    - Provide feedback

    YOU CANNOT:
    - Explain concepts yourself
    - Provide examples yourself
    """
)

Why? Because:

Content Searcher has access to Google Search (real-time, research-backed)
Video Selector has access to YouTube API (curated, filtered)
Content Formatter knows your learning preferences

Sensei focuses on pedagogy. Content creation agents focus on quality. Separation of concerns, even for AI.

The DatabaseSessionService Breakthrough: Why This Changes Everything

Here's where LearnForge diverges from every other AI learning platform I've seen.

The Problem Nobody Talks About

Most AI chatbots use in-memory sessions. This works fine for:

5-minute conversations
Simple Q&A
Demos

But learning is different. Learning sessions can span:

Hours (deep dive sessions)
Days (coming back to continue)
Weeks (long-form courses)
Months (mastery journeys)

In-memory sessions fail catastrophically:

Server restart? Session lost.
Connection drop? Session lost.
Switch devices? Session lost.
Come back tomorrow? Session lost.

The Solution: Persistent State with Cloud SQL

LearnForge uses DatabaseSessionService with Cloud SQL (PostgreSQL) to persist everything:

from google.adk.sessions import DatabaseSessionService
from google.cloud.sql.connector import Connector

connector = Connector(refresh_strategy="LAZY")

session_service = DatabaseSessionService(
    db_url="postgresql+pg8000://",
    creator=lambda: connector.connect(
        instance_connection_name,
        "pg8000",
        user=db_user,
        password=db_password,
        db=db_name,
    ),
    pool_size=10,
    max_overflow=5,
    pool_timeout=60,
    pool_recycle=1800,
)

What gets persisted:

Current checkpoint index
Completed checkpoints
Content search results (so we don't re-search)
Video selections (so we remember what was shown)
User responses and comprehension checks
Learning preferences

The impact:

You can:

Close your browser mid-checkpoint and resume exactly where you left off
Switch from laptop to phone seamlessly
Come back weeks later and continue your mission
Share sessions with team members (collaborative learning)

This isn't just a feature it's what makes LearnForge production-ready for real learning, not just demos.

Cloud SQL Connector: Security Without the Headache

Traditional database access requires:

IP whitelisting (nightmare in serverless)
VPNs (complex setup)
Exposed connection strings (security risk)

Cloud SQL Connector uses IAM credentials. No network configuration. No exposed passwords. Just secure, managed connections.

def _create_cloud_sql_connection(self):
    return self._connector.connect(
        settings.INSTANCE_CONNECTION_NAME,
        "pg8000",
        user=settings.DB_USER,
        password=settings.DB_PASSWORD,
        db=settings.DB_NAME,
    )

Production-grade security, zero configuration.

Real-Time WebSocket: The Conversation That Never Lags

Both Polaris and Lumina use WebSocket connections for real-time, bidirectional communication. But here's what makes it special: session resume.

The Flow

@router.websocket("/ws")
async def mission_ally_websocket(websocket: WebSocket, mission_id: str):
    await websocket.accept()
    user_id = await authenticate(websocket)

    # Check for existing session
    existing_session = await session_service.get_session(
        app_name="mission-ally",
        user_id=user_id,
        session_id=session_id
    )

    if existing_session:
        # Resume from last checkpoint
        current_checkpoint = existing_session.state["current_checkpoint_index"]
        completed = existing_session.state["completed_checkpoints"]
        # Send historical messages, continue from where they left off
    else:
        # Start new mission
        session = await session_service.create_session(...)

If you disconnect and reconnect, the system:

Loads your session from Cloud SQL
Sends you historical messages (so you see the conversation)
Continues from your last checkpoint
Feels completely seamless

No "start over" button. No lost progress. Just... continue.

Content Composition: How AI Curates Your Learning Materials

When Sensei needs to teach you about "neural networks," it doesn't pull from a static database. Instead, it orchestrates a three-stage pipeline:

Stage 1: Content Searcher

Uses Google Search API to find the latest, most relevant educational content:

content_searcher = LlmAgent(
    name="lumina_content_searcher",
    tools=[google_search_tool],
    instruction="Search for educational content about the concept..."
)

Real-time search means you get current information, not outdated course materials.

Stage 2: Video Selector

Uses YouTube Data API v3 to curate educational videos:

def search_youtube_videos(
    query: str,
    max_results: int = 3,
    duration_filter: str = "medium",  # 4-20 minutes (optimal for learning)
    video_category_id: str = "27"  # Education category
) -> list[dict]:
    # Filters by: duration, category, relevance
    # Returns: title, channel, description, duration, thumbnail

Why this matters: Not all YouTube videos are educational. Not all educational videos are the right length. The selector finds videos that are:

Actually educational (category 27)
The right duration (4-20 min is the sweet spot)
Relevant to the concept
From reputable channels

Stage 3: Content Formatter

Personalizes everything based on your learning profile:

content_formatter = LlmAgent(
    instruction=f"""
    Format content for:
    - Learning style: {user_profile['learning_style']}  # ["examples", "step-by-step"]
    - Level: {user_profile['level']}  # "Beginner" | "Intermediate" | "Advanced"
    - Preferences: {user_preferences}
    """
)

If you're a visual learner who prefers examples, you get examples. If you prefer step-by-step guides, you get structured explanations. The content adapts to you.

SequentialAgent: Chaining It All Together

ADK's SequentialAgent makes this elegant:

content_composer = SequentialAgent(
    name="lumina_content_composer_agent",
    sub_agents=[
        content_searcher,    # Stage 1: Search
        video_selector,   # Stage 2: Curate videos
        content_formatter # Stage 3: Personalize
    ]
)

Each stage passes its output to the next. Clean, simple, powerful.

Technical Deep Dives: The Decisions That Matter

1. Why Cloud SQL Connector Over Traditional Connections

The problem: In Cloud Run (serverless), you can't whitelist IPs. Traditional database connections require network configuration.

The solution: Cloud SQL Connector uses IAM credentials. Zero network configuration. Secure by default.

@property
def use_cloud_sql_connector(self) -> bool:
    return self.is_cloud_run and all([
        self.INSTANCE_CONNECTION_NAME,
        self.DB_USER,
        self.DB_PASSWORD,
        self.DB_NAME
    ])

Impact: Production-ready security without the infrastructure headache.

2. Secret Manager: Zero Hardcoded Credentials

All sensitive configuration comes from Secret Manager:

def _read_secret(env_var: str, default: str = "") -> str:
    value = os.getenv(env_var, default)
    # Cloud Run mounts secrets as files
    if value and os.path.exists(value):
        with open(value) as f:
            return f.read().strip()
    return value

Impact: Credential rotation? Just update the secret. No code changes. No redeploys.

3. Multi-Stage Docker Build: Faster Cold Starts

Optimized container images reduce cold start time:

# Builder stage: Install dependencies
FROM python:3.11-slim as builder
RUN pip install poetry
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-root --only main

# Runtime stage: Copy only what's needed
FROM python:3.11-slim
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY . .

Impact: 60% smaller images, faster cold starts, lower costs.

4. State-Driven Checkpoint Progression

Checkpoints advance through state, not hardcoded logic:

increment_checkpoint_tool = FunctionTool(
    func=lambda ctx: {
        "current_checkpoint_index": ctx.state["current_checkpoint_index"] + 1,
        "current_checkpoint_goal": next_checkpoint_name,
    }
)

Impact: Mission structures are flexible. Add checkpoints? Remove checkpoints? Change order? It just works.

Performance & Scalability: Built for Real Usage

Cloud Run Auto-Scaling

Min instances: 0 (scale to zero = cost savings)
Max instances: 100 (handles traffic spikes)
CPU: 2 vCPU per instance
Memory: 4Gi per instance
Concurrency: 80 requests per instance

What this means: Zero users? Zero cost. 10,000 concurrent learners? Scales automatically. No manual intervention.

Database Connection Pooling

Base pool: 10 connections
Overflow: 5 connections
Timeout: 60 seconds
Recycle: 30 minutes

What this means: Efficient connection management. No connection exhaustion. Handles thousands of concurrent sessions.

Session State Efficiency

Average session state: ~50KB. That's:

Checkpoint progress
Content search results (cached)
Video selections
User responses

Cloud SQL handles this efficiently. Thousands of concurrent sessions? No problem.

Lessons Learned: What I Wish I Knew Earlier

1. DatabaseSessionService Is Non-Negotiable for Production

In-memory sessions work for demos. Production learning platforms need persistence. The moment I switched to DatabaseSessionService, everything changed:

Users could resume sessions
Progress tracked across weeks
Concurrent learners with isolated state

Learning: Choose session storage based on use case duration, not convenience.

2. Silent Orchestration Creates Better UX

Users don't care about agent architecture. They want a seamless conversation. The orchestrator should be invisible:

# WRONG: User sees the machinery
Orchestrator: "Let me hand you over to the Sensei..."
Sensei: "Hello, let's learn..."

# RIGHT: User only sees the teacher
Sensei: "Hello, let's learn..."

Learning: Hide complexity, show simplicity.

3. Content Authority Separation Improves Quality

Teaching agents shouldn't generate content. They should delegate to specialized agents with:

Access to search APIs (real-time content)
Video curation (filtered, relevant)
Personalization (user preferences)

Learning: Separation of concerns applies to AI agents too.

4. Cloud SQL Connector Simplifies Security

No IP whitelisting. No VPNs. No exposed connection strings. Just IAM credentials and secure connections.

Learning: Use managed services for security, not manual configuration.

5. SequentialAgent Reduces Boilerplate

Content composition requires: search → video selection → formatting. SequentialAgent chains these automatically. No manual coordination needed.

Learning: ADK's built-in patterns are powerful. Use them.

6. State-Driven Flow Enables Flexibility

Hardcoded checkpoint logic breaks when mission structures change. State-driven progression adapts automatically.

Learning: Data-driven > code-driven for dynamic systems.

The Impact: What This Actually Solves

For Learners

Personalized learning paths: No more generic courses
Real-time adaptation: Content adjusts to your understanding
Session persistence: Learn at your own pace, resume anytime
Research-backed content: Latest information, not outdated materials
Multi-modal learning: Text + videos + interactive teaching

For Educators

Scalable tutoring: One AI system can teach thousands simultaneously
Adaptive content: Each learner gets personalized materials
Progress tracking: See exactly where learners are stuck
Content curation: AI finds and filters the best resources

For the Industry

Proof that multi-agent AI works: 12 agents coordinating seamlessly
Production-ready patterns: DatabaseSessionService, Cloud SQL Connector, WebSocket resume
Scalable architecture: Cloud Run auto-scaling, connection pooling
Security best practices: Secret Manager, IAM-based connections

What's Next: The Future of AI-Powered Learning

Short-term:

Multi-modal content (images, diagrams, interactive exercises)
Collaborative learning (team missions, peer review)
Advanced analytics (learning velocity, concept mastery tracking)

Long-term:

Fine-tuned models for domain-specific teaching
Adaptive difficulty based on real-time comprehension
Integration with external platforms (Coursera, edX, Khan Academy)

The vision: Every learner gets a personal tutor that:

Understands their goals
Adapts to their learning style
Remembers everything
Never gets tired
Scales to millions

Conclusion: Why This Matters

Building LearnForge taught me something important: the future of education isn't about better content, it's about better personalization.

Traditional platforms give everyone the same course. LearnForge gives everyone a personalized learning journey that:

Starts with a conversation (not a catalog)
Adapts in real-time (not static content)
Remembers everything (not ephemeral sessions)
Scales seamlessly (not manual infrastructure)

By combining:

Google ADK's hierarchical agent orchestration for complex workflows
Cloud SQL with DatabaseSessionService for persistent state
Cloud Run's auto-scaling for seamless scalability
WebSocket real-time communication for responsive UX

I created a platform that transforms how people learn, from static courses to dynamic, personalized, adaptive journeys.

The technology is here. The infrastructure is ready. The future of education is AI-powered, serverless, and personalized.

LearnForge is just the beginning.

Google Cloud Services Utilized

Service	Purpose	Why It Matters
Cloud Run	Serverless container hosting	Auto-scales from 0 to 100 instances, zero infrastructure management
Artifact Registry	Container image storage	Versioned images, CI/CD integration
Cloud SQL (PostgreSQL)	Persistent session state	Sessions survive restarts, connection drops, device switches
Cloud SQL Connector	Secure database connections	IAM-based security, no IP whitelisting needed
Firebase Authentication	User authentication	Google OAuth 2.0, secure session management
Firestore	Mission data storage	User profiles, mission definitions, enrollments
Cloud Logging	Application logs	Centralized logging, debugging, monitoring
Cloud Trace	Distributed tracing	Performance analysis, bottleneck identification
Secret Manager	Credential storage	Zero hardcoded secrets, rotation-friendly
Agent Development Kit (ADK)	Multi-agent orchestration	Hierarchical agents, sequential pipelines, tool integration
Gemini 2.5 Flash	LLM for agents	Fast, cost-effective, powerful reasoning
YouTube Data API v3	Video curation	Educational video search, filtering, metadata
Google Search API	Content discovery	Real-time research, up-to-date information

Built with Google Cloud Run and Agent Development Kit (ADK)

Transforming how people learn, one conversation at a time.

Deploy to Google Cloud Run in Minutes

Rashika Karki — Thu, 06 Nov 2025 18:33:39 +0000

How I Set Up Cloud Run CI/CD in Under 30 Minutes for the Cloud Run Hackathon

This post was created for the Cloud Run Hackathon to document my deployment setup experience.

When I decided to participate in the Cloud Run Hackathon, one of my biggest concerns was getting lost in deployment configuration. I needed a reliable, automated deployment pipeline that wouldn't eat into my development time. Following this structured approach helped me get everything running in under 30 minutes with my FastAPI application.

Why This Mattered for the Hackathon

The hackathon rewards bonus points for using Cloud Run effectively, especially when running multiple services (frontend and backend). Setting up a proper CI/CD pipeline early meant I could focus on building my actual application instead of wrestling with deployment issues every time I made a change.

What I Built On

I started with a basic FastAPI server as a foundation. FastAPI's speed and automatic API documentation made it perfect for rapid development during the hackathon. Here's the minimal setup that got me started:

main.py - A basic health check endpoint and main route:

from fastapi import FastAPI
from datetime import datetime
import os

app = FastAPI()

@app.get("/")
async def root():
    return {
        "message": "Hello from Cloud Run!",
        "timestamp": datetime.utcnow().isoformat(),
        "environment": os.getenv("ENV", "development")
    }

@app.get("/health")
async def health():
    return {"status": "healthy"}

requirements.txt - Minimal dependencies:

fastapi==0.104.1
uvicorn[standard]==0.24.0

The 30-Minute Setup Process

Phase 1: Google Cloud Project Setup (10 minutes)

I headed to the Google Cloud Console and created a new project. The key was keeping track of every identifier I created - Project ID, region selection, service names. I chose europe-west1 as my region and stuck with it consistently.

Creating a new project:

I gave it a memorable name and saved the Project ID for later use.

Phase 2: Setting Up Cloud Run (5 minutes)

I searched for "Cloud Run" in the console and clicked "Deploy Container":

Configuration was straightforward:

Service name: fastapi-server
Region: europe-west1
Authentication: Public access for testing
Container image URL: Left empty (GitHub Actions would handle this)

The missing container image error was expected at this stage.

Phase 3: Artifact Registry Configuration (5 minutes)

I created a Docker repository in Artifact Registry:

Configuration:

Format: Docker
Name: my-app-repo
Region: Same as Cloud Run (europe-west1)
Mode: Standard

Phase 4: Service Account and Permissions (8 minutes)

This was critical. I created a service account that would give GitHub permission to deploy on my behalf.

I named it github-deployer and assigned four specific roles:

Role	Purpose
Artifact Registry Reader	Allows Cloud Run to fetch images
Artifact Registry Writer	Allows GitHub Actions to push builds
Cloud Run Admin	Enables deployment updates
Service Account User	Lets Cloud Run execute containers

Then I generated a JSON key:

This JSON file is sensitive - it grants deployment permissions.

Phase 5: GitHub Secrets Configuration (5 minutes)

I configured GitHub repository secrets under Settings → Secrets and variables → Actions:

I added five secrets:

Secret Name	Value
`GCP_SA_KEY`	Entire JSON key file content
`PROJECT_ID`	My Google Cloud project ID
`PROJECT_REGION`	`europe-west1`
`ARTIFACT_REGISTRY_REPO`	`my-app-repo`
`CLOUD_RUN_SERVICE`	`fastapi-server`

Phase 6: Dockerfile and Workflow (2 minutes)

The Dockerfile was optimized for FastAPI:

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY main.py .

# Cloud Run expects port 8080
EXPOSE 8080

# Start uvicorn server
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

The GitHub Actions workflow in .github/workflows/deploy.yml:

name: Deploy to Cloud Run

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    name: Deploy to Google Cloud Run
    runs-on: ubuntu-latest

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

      - name: Authenticate to Google Cloud
        uses: google-github-actions/auth@v2
        with:
          credentials_json: ${{ secrets.GCP_SA_KEY }}

      - name: Set up Cloud SDK
        uses: google-github-actions/setup-gcloud@v2

      - name: Configure Docker for Artifact Registry
        run: |
          gcloud auth configure-docker ${{ secrets.PROJECT_REGION }}-docker.pkg.dev

      - name: Build Docker image
        run: |
          docker build -t ${{ secrets.PROJECT_REGION }}-docker.pkg.dev/${{ secrets.PROJECT_ID }}/${{ secrets.ARTIFACT_REGISTRY_REPO }}/${{ secrets.CLOUD_RUN_SERVICE }}:${{ github.sha }} .
          docker tag ${{ secrets.PROJECT_REGION }}-docker.pkg.dev/${{ secrets.PROJECT_ID }}/${{ secrets.ARTIFACT_REGISTRY_REPO }}/${{ secrets.CLOUD_RUN_SERVICE }}:${{ github.sha }} \
                     ${{ secrets.PROJECT_REGION }}-docker.pkg.dev/${{ secrets.PROJECT_ID }}/${{ secrets.ARTIFACT_REGISTRY_REPO }}/${{ secrets.CLOUD_RUN_SERVICE }}:latest

      - name: Push Docker image to Artifact Registry
        run: |
          docker push ${{ secrets.PROJECT_REGION }}-docker.pkg.dev/${{ secrets.PROJECT_ID }}/${{ secrets.ARTIFACT_REGISTRY_REPO }}/${{ secrets.CLOUD_RUN_SERVICE }}:${{ github.sha }}
          docker push ${{ secrets.PROJECT_REGION }}-docker.pkg.dev/${{ secrets.PROJECT_ID }}/${{ secrets.ARTIFACT_REGISTRY_REPO }}/${{ secrets.CLOUD_RUN_SERVICE }}:latest

      - name: Deploy to Cloud Run
        run: |
          gcloud run deploy ${{ secrets.CLOUD_RUN_SERVICE }} \
            --image ${{ secrets.PROJECT_REGION }}-docker.pkg.dev/${{ secrets.PROJECT_ID }}/${{ secrets.ARTIFACT_REGISTRY_REPO }}/${{ secrets.CLOUD_RUN_SERVICE }}:${{ github.sha }} \
            --platform managed \
            --region ${{ secrets.PROJECT_REGION }} \
            --project ${{ secrets.PROJECT_ID }} \
            --allow-unauthenticated \
            --min-instances 0 \
            --max-instances 10 \
            --memory 512Mi \
            --cpu 1 \
            --timeout 300 \
            --port 8080

      - name: Show deployment URL
        run: |
          echo "Deployment successful!"
          gcloud run services describe ${{ secrets.CLOUD_RUN_SERVICE }} \
            --platform managed \
            --region ${{ secrets.PROJECT_REGION }} \
            --project ${{ secrets.PROJECT_ID }} \
            --format 'value(status.url)'

First Deployment

I committed everything and pushed to main:

git add .
git commit -m "Initial Cloud Run deployment"
git push origin main

The GitHub Actions workflow executed automatically. Within 3-4 minutes, I had a live deployment URL with FastAPI's automatic interactive API documentation available at /docs.

Final Project Structure

my-cloud-run-app/
├── .github/
│   └── workflows/
│       └── deploy.yml
├── main.py
├── requirements.txt
└── Dockerfile

Testing the Deployment

Once deployed, I could access:

# Main endpoint
curl https://your-service-url.run.app
# Returns: {"message":"Hello from Cloud Run!","timestamp":"2025-11-09T...","environment":"development"}

# Health check
curl https://your-service-url.run.app/health
# Returns: {"status":"healthy"}

# Interactive API docs (browser)
https://your-service-url.run.app/docs

FastAPI's automatic OpenAPI documentation was a huge win during the hackathon - I could test endpoints directly from the browser.

How This Helped My Hackathon Project

With this foundation in place, I could:

Iterate quickly: Every push to main automatically deployed
Test in production: Real Cloud Run environment from day one
Scale easily: Adding a second service (frontend) followed the same pattern
Debug efficiently: FastAPI's detailed error messages and /docs endpoint
Focus on features: No more deployment anxiety

Adapting for Multiple Services

For the hackathon's bonus points, I needed both frontend and backend services. The pipeline made this straightforward:

Created a separate frontend repository
Set up another Cloud Run service with a similar workflow
Connected services using Cloud Run's internal networking
Both services deployed automatically on their respective branches
Used CORS middleware in FastAPI to handle cross-origin requests:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # Updated with actual frontend URL in production
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Cost Considerations

With min-instances: 0, the services scaled to zero when not in use. Cloud Run's free tier covers:

2 million requests per month
360,000 GB-seconds of memory
180,000 vCPU-seconds

Perfect for hackathon projects with minimal costs during development.

Key Takeaways

What worked well:

FastAPI's speed made iteration rapid
Having all configuration in one place (GitHub secrets)
Using standard Docker practices
Automated deployment removed manual errors
Service account permissions were clearly defined
Built-in API documentation at /docs for testing

Common pitfalls I avoided:

Mismatched regions across services
Forgetting to save the Project ID early
Not testing the health endpoint before deploying
Exposing the wrong port (always use 8080 for Cloud Run)
Not installing uvicorn with the [standard] extras for production

FastAPI-specific considerations:

Using uvicorn instead of development server
Setting --host 0.0.0.0 to accept external connections
Including CORS middleware for frontend integration

Beyond the Basic Setup

Once the pipeline was running, I expanded my hackathon project with:

Environment variables via Google Secret Manager for API keys
Cloud Run Jobs for background processing tasks
Pub/Sub integration for event-driven workflows
Gemini API integration for AI features (bonus points)
FastAPI's dependency injection for database connections
Pydantic models for request/response validation

Performance Notes

FastAPI on Cloud Run performed excellently:

Cold start times: ~2-3 seconds with the slim Python image
Request latency: Sub-100ms for most endpoints
The async/await support in FastAPI worked seamlessly
Auto-scaling handled traffic spikes without issues

Troubleshooting Tips

Build fails?

Check your Dockerfile syntax
Ensure requirements.txt has all dependencies
Verify the Python version matches (using Python 3.11)

Deployment fails?

Verify all GitHub secrets are correct
Check the service account has the right permissions
Ensure regions match across all services

Container crashes?

Check Cloud Run logs in Google Cloud Console
Verify your app listens on port 8080
Ensure environment variables are handled properly

Conclusion

This 30-minute setup gave me a production-ready deployment pipeline that handled the infrastructure concerns, letting me focus on building my hackathon submission. The combination of GitHub Actions and Cloud Run meant I could iterate rapidly without deployment friction.

FastAPI was the perfect choice for the backend - its speed, automatic documentation, and type safety accelerated development significantly. The deployment pipeline ensured that every feature I built was live within minutes.

For anyone participating in the Cloud Run Hackathon, I recommend setting up this pipeline first. Get your deployment working, then build your features. The automation pays for itself immediately.

The complete code structure and workflow are ready to adapt for any FastAPI application. Just replace the simple server with your actual application logic, add your models and endpoints, adjust resource limits if needed, and deploy.

This post was created to document my Cloud Run deployment experience for the Cloud Run Hackathon.