> ## Documentation Index
> Fetch the complete documentation index at: https://docs.handauncle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CI/CD Pipeline

> Continuous Integration and Deployment workflow for HandaUncle Backend

## Overview

This document describes the Continuous Integration and Continuous Deployment (CI/CD) pipeline for the HandaUncle Backend application. The pipeline automates building, testing, security scanning, and deploying the application across multiple environments.

<Info>
  The pipeline uses **GitHub Actions** for automation and **Google Cloud Run** for deployments with **Workload Identity Federation** for secure, keyless authentication.
</Info>

## Architecture

```mermaid theme={null}
flowchart TB
    subgraph GitHub["GitHub Repository"]
        A[HandaUncle/handauncle-backend-new]
    end
    
    subgraph Actions["GitHub Actions"]
        B[ci.yml]
        C[claim-dev.yml]
        D[deploy-dev.yml]
        E[release-dev.yml]
        F[deploy-staging.yml]
        G[pr-checks.yml]
    end
    
    subgraph Environments["Deployment Targets"]
        H[DEV<br/>Manual Deploy]
        I[STAGING<br/>develop]
        J[PRODUCTION<br/>main]
    end
    
    subgraph CloudRun["Google Cloud Run"]
        K[Dev Project]
        L[Staging Project]
        M[Prod Project]
    end
    
    A --> Actions
    B --> H & I & J
    C --> H
    D --> H
    E --> H
    F --> I
    G --> I & J
    H --> K
    I --> L
    J --> M
```

## Environments

<CardGroup cols={3}>
  <Card title="Development" icon="code" color="#22c55e">
    **Trigger:** Manual (Claim → Deploy → Release)

    **Project:** Dev GCP Project

    **Purpose:** Feature development and testing
  </Card>

  <Card title="Staging" icon="flask" color="#f59e0b">
    **Branch:** `develop`

    **Project:** Staging GCP Project

    **Purpose:** Pre-production testing and QA
  </Card>

  <Card title="Production" icon="globe" color="#ef4444">
    **Branch:** `main`

    **Project:** Production GCP Project

    **Purpose:** Live production environment
  </Card>
</CardGroup>

## Branch Strategy

### Git Flow

```mermaid theme={null}
gitGraph
    commit id: "initial"
    branch develop
    checkout develop
    commit id: "setup"
    branch feature/xyz
    checkout feature/xyz
    commit id: "feature work"
    commit id: "more work"
    checkout develop
    merge feature/xyz id: "merge feature"
    checkout main
    merge develop id: "release v1.0"
```

### Branch Rules

<AccordionGroup>
  <Accordion title="feature/* - Development branches" icon="code-branch">
    * Created from `develop`
    * **Manual deployment** to Dev environment (Claim → Deploy → Release)
    * Must pass CI checks before merging
    * Used for individual feature development
  </Accordion>

  <Accordion title="develop - Integration branch" icon="code-merge">
    * Receives merges from feature branches via PR
    * Auto-deploys to **Staging environment** on push
    * Protected: Requires PR with passing checks
    * Used for integration testing
  </Accordion>

  <Accordion title="main - Production branch" icon="shield-check">
    * Only accepts PRs from `develop`
    * Auto-deploys to **Production** on push
    * Protected: Requires PR from develop only
    * Never push directly to main
  </Accordion>
</AccordionGroup>

<Warning>
  Never push directly to `main`. All production deployments must go through `develop` first.
</Warning>

***

## Dev Environment Lock System

<Info>
  The Dev environment uses a **claim/release system** to prevent multiple developers from overwriting each other's deployments during testing.
</Info>

### How It Works

```mermaid theme={null}
sequenceDiagram
    participant DevA as Developer A
    participant GH as GitHub Actions
    participant Dev as Dev Environment
    participant DevB as Developer B

    DevA->>GH: 🔒 Claim Dev Environment
    GH-->>DevA: ✅ Claimed successfully
    
    DevA->>GH: 🚀 Deploy to Dev (feature/xyz)
    GH->>Dev: Deploy feature/xyz
    GH-->>DevA: ✅ Deployed
    
    Note over DevA,Dev: Developer A testing...
    
    DevB->>GH: 🚀 Deploy to Dev (feature/abc)
    GH-->>DevB: ❌ Blocked - Claimed by @DevA
    
    DevA->>GH: 🔓 Release Dev Environment
    GH-->>DevA: ✅ Released
    
    DevB->>GH: 🔒 Claim Dev Environment
    GH-->>DevB: ✅ Claimed successfully
    
    DevB->>GH: 🚀 Deploy to Dev (feature/abc)
    GH->>Dev: Deploy feature/abc
    GH-->>DevB: ✅ Deployed
```

### Workflow Steps

<Steps>
  <Step title="Claim the Environment" icon="lock">
    Run **🔒 Claim Dev Environment** workflow

    * Blocks other developers from deploying
    * Shows who has the environment claimed
  </Step>

  <Step title="Deploy Your Branch" icon="rocket">
    Run **🚀 Deploy to Dev** workflow

    * Enter your branch name (e.g., `feature/my-feature`)
    * Only works if you own the claim
  </Step>

  <Step title="Test Your Changes" icon="flask">
    Test as long as needed

    * Environment stays locked to you
    * Other developers see "claimed by @you"
  </Step>

  <Step title="Release When Done" icon="unlock">
    Run **🔓 Release Dev Environment** workflow

    * Frees the environment for others
    * **Don't forget this step!**
  </Step>
</Steps>

### Emergency Release

If a developer forgets to release and is unavailable:

1. Run **🔓 Release Dev Environment**
2. Check the **Force release** checkbox
3. This will release even if claimed by someone else

<Warning>
  Only use force release in emergencies. Always try to contact the developer first.
</Warning>

***

## Workflow Files

### CI Pipeline (`ci.yml`)

<Tabs>
  <Tab title="Overview" icon="eye">
    **Triggers:**

    * Push to: `main`, `develop`, `feature/**`
    * Pull requests to: `main`, `develop`

    **Artifacts:**

    * Vulnerability report (JSON) - 30-day retention
  </Tab>

  <Tab title="Jobs" icon="list-check">
    | Job                  | Description                           | Duration  |
    | -------------------- | ------------------------------------- | --------- |
    | 🔍 Lint & Type Check | ESLint + TypeScript validation        | \~1-2 min |
    | 🧪 Unit Tests        | Bun test suite with coverage          | \~1-3 min |
    | 🐳 Docker Build      | Multi-stage Docker build with caching | \~2-4 min |
    | 🔒 Security Scan     | Container vulnerability scan          | \~1-2 min |
    | 📦 Dependency Scan   | Filesystem/dependency scan            | \~1 min   |
    | 🔐 Secret Scan       | Secret detection                      | \~1 min   |
    | 📊 CI Summary        | Aggregated status report              | \~10 sec  |
  </Tab>
</Tabs>

### Dev Environment Workflows

| Workflow                   | File              | Purpose                                 |
| -------------------------- | ----------------- | --------------------------------------- |
| 🔒 Claim Dev Environment   | `claim-dev.yml`   | Claim exclusive access to dev           |
| 🚀 Deploy to Dev           | `deploy-dev.yml`  | Deploy a branch to dev (requires claim) |
| 🔓 Release Dev Environment | `release-dev.yml` | Release dev for others to use           |

### Deploy to Staging (`deploy-staging.yml`)

<Steps>
  <Step title="Authenticate to GCP" icon="key">
    Uses Workload Identity Federation for keyless authentication
  </Step>

  <Step title="Build Docker Image" icon="docker">
    Build with commit SHA tag for traceability
  </Step>

  <Step title="Push to Artifact Registry" icon="upload">
    Push to regional Docker registry
  </Step>

  <Step title="Deploy to Cloud Run" icon="rocket">
    Deploy with all secrets injected from Secret Manager
  </Step>

  <Step title="Output URL" icon="link">
    Display the deployment URL in workflow summary
  </Step>
</Steps>

**Concurrency:** Only one staging deployment runs at a time (others queue)

### PR Checks (`pr-checks.yml`)

| Job               | Description                                        |
| ----------------- | -------------------------------------------------- |
| Branch Protection | Blocks direct PRs to main (must come from develop) |
| PR Summary        | Displays PR information and merge path             |

***

## GCP Infrastructure

### Projects

| Environment | Purpose                         |
| ----------- | ------------------------------- |
| Dev         | Feature development and testing |
| Staging     | Pre-production QA               |
| Production  | Live environment                |

### Enabled APIs

<CardGroup cols={2}>
  <Card title="Cloud Run Admin API" icon="server">
    Container deployment and management
  </Card>

  <Card title="Artifact Registry API" icon="box-archive">
    Docker image storage
  </Card>

  <Card title="Secret Manager API" icon="key">
    Secure secrets storage
  </Card>

  <Card title="IAM API" icon="user-shield">
    Identity and access management
  </Card>
</CardGroup>

### Workload Identity Federation

<Note>
  Enables keyless authentication from GitHub Actions to GCP - no service account keys needed!
</Note>

**How it works:**

1. GitHub Actions generates an OIDC token
2. GCP exchanges it for a short-lived access token
3. No long-lived credentials stored anywhere

### Service Accounts

| Purpose           | Description                          |
| ----------------- | ------------------------------------ |
| GitHub Actions SA | Used by CI/CD to deploy              |
| Cloud Run SA      | Runtime identity for the application |

**IAM Roles (GitHub Actions SA):**

* Cloud Run Admin
* Artifact Registry Writer
* Service Account User
* Secret Manager Accessor

***

## Secrets Management

### GitHub Repository Secrets

| Category          | Description                            |
| ----------------- | -------------------------------------- |
| Workload Identity | Provider URLs for each environment     |
| Service Accounts  | Email addresses for GCP authentication |

### GitHub Repository Variables

| Variable         | Description                                |
| ---------------- | ------------------------------------------ |
| `DEV_CLAIMED_BY` | Tracks who has claimed the dev environment |

### GCP Secret Manager

<AccordionGroup>
  <Accordion title="Core Configuration" icon="gear" defaultOpen>
    Server port, backend secrets, environment settings
  </Accordion>

  <Accordion title="Database" icon="database">
    Database connection strings, Redis configuration
  </Accordion>

  <Accordion title="Authentication" icon="shield">
    OAuth provider credentials, JWT secrets
  </Accordion>

  <Accordion title="AI Services" icon="brain">
    API keys for various AI providers (LLMs, embeddings)
  </Accordion>

  <Accordion title="Vector DB & Memory" icon="memory">
    Vector database and memory service credentials
  </Accordion>

  <Accordion title="Observability" icon="chart-line">
    Monitoring and analytics service credentials
  </Accordion>

  <Accordion title="File Processing" icon="file">
    Document processing and storage credentials
  </Accordion>

  <Accordion title="Web Search" icon="magnifying-glass">
    Search API credentials
  </Accordion>

  <Accordion title="Payments" icon="credit-card">
    Payment gateway credentials
  </Accordion>

  <Accordion title="Feature Flags" icon="flag">
    Feature configuration values
  </Accordion>
</AccordionGroup>

***

## Development Workflow

### Creating a New Feature

<Steps>
  <Step title="Start from develop">
    ```bash theme={null}
    git checkout develop
    git pull origin develop
    ```
  </Step>

  <Step title="Create feature branch">
    ```bash theme={null}
    git checkout -b feature/my-new-feature
    ```
  </Step>

  <Step title="Make changes and commit">
    ```bash theme={null}
    git add .
    git commit -m "feat: Add new feature"
    ```
  </Step>

  <Step title="Push your branch">
    ```bash theme={null}
    git push origin feature/my-new-feature
    ```
  </Step>
</Steps>

### Deploying to Dev

<Steps>
  <Step title="Claim the environment">
    Go to **Actions** → **🔒 Claim Dev Environment** → **Run workflow**
    <Check>You now have exclusive access to dev!</Check>
  </Step>

  <Step title="Deploy your branch">
    Go to **Actions** → **🚀 Deploy to Dev** → **Run workflow**

    * Enter your branch name (e.g., `feature/my-new-feature`)
      <Check>Your code is deploying to Dev!</Check>
  </Step>

  <Step title="Test your changes">
    Use the deployment URL shown in the workflow summary
  </Step>

  <Step title="Release when done">
    Go to **Actions** → **🔓 Release Dev Environment** → **Run workflow**
    <Check>Environment is now available for others!</Check>
  </Step>
</Steps>

### Promoting to Staging

<Steps>
  <Step title="Create Pull Request">
    Go to GitHub and create a PR: `feature/my-new-feature` → `develop`
  </Step>

  <Step title="Wait for CI checks">
    All lint, tests, and security scans must pass
  </Step>

  <Step title="Get code review">
    Have a teammate review your changes
  </Step>

  <Step title="Merge PR">
    <Check>Merging automatically triggers staging deployment!</Check>
  </Step>
</Steps>

### Promoting to Production

<Steps>
  <Step title="Create PR from develop to main">
    Go to GitHub and create a PR: `develop` → `main`
  </Step>

  <Step title="Wait for CI checks">
    All checks must pass
  </Step>

  <Step title="Get approval">
    Production deployments require approval
  </Step>

  <Step title="Merge PR">
    <Check>Merging automatically triggers production deployment!</Check>
  </Step>
</Steps>

***

## Monitoring & Debugging

### Viewing Workflow Runs

1. Go to: [GitHub Actions](https://github.com/HandaUncle/handauncle-backend-new/actions)
2. Select the workflow (CI Pipeline, Deploy Dev, etc.)
3. Click on a specific run to see logs

### Viewing Deployment Logs

```bash theme={null}
# View logs for a Cloud Run service
gcloud run services logs read SERVICE_NAME \
  --project=PROJECT_ID \
  --region=REGION
```

### Getting Deployment URLs

```bash theme={null}
# Get the URL for a Cloud Run service
gcloud run services describe SERVICE_NAME \
  --project=PROJECT_ID \
  --region=REGION \
  --format='value(status.url)'
```

### Downloading Security Reports

1. Go to the CI Pipeline workflow run
2. Scroll to "Artifacts" section
3. Download the vulnerability report

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Dev Environment Claimed by Someone Else" icon="lock">
    **Error:** `Dev environment is claimed by @username`

    **Solution:**

    1. Contact the developer and ask them to release
    2. If unavailable, use **Force release** option in the Release workflow
  </Accordion>

  <Accordion title="Deploy Blocked - Not Claimed" icon="triangle-exclamation">
    **Error:** `Dev environment is not claimed`

    **Solution:**
    Run **🔒 Claim Dev Environment** workflow first, then deploy
  </Accordion>

  <Accordion title="Workload Identity Authentication Failed" icon="key">
    **Error:** `Unable to get federated token`

    **Solution:**
    Verify the Workload Identity pool and provider exist in GCP
  </Accordion>

  <Accordion title="Secret Access Denied" icon="shield">
    **Error:** `Permission denied on secret`

    **Solution:**
    Ensure the service account has Secret Manager Accessor role
  </Accordion>

  <Accordion title="Cloud Run Deployment Failed" icon="server">
    **Error:** `Could not find service account`

    **Solution:**
    Verify the Cloud Run service account exists in the project
  </Accordion>

  <Accordion title="Docker Build Cache Miss" icon="clock">
    **Symptom:** Slow builds despite caching

    **Solution:** GitHub Actions cache has a 10GB limit. Old caches are automatically evicted. This is normal behavior.
  </Accordion>
</AccordionGroup>

***

## Security Considerations

<CardGroup cols={2}>
  <Card title="Secrets Protection" icon="shield-check" color="#22c55e">
    * All secrets stored in GCP Secret Manager (encrypted at rest)
    * Workload Identity Federation (no long-lived keys)
    * Minimal IAM permissions (principle of least privilege)
    * Security scanning on every build
  </Card>

  <Card title="Branch Protection" icon="code-branch" color="#3b82f6">
    * `main` only accepts PRs from `develop`
    * CI checks must pass before merge
    * Code review recommended
  </Card>

  <Card title="Container Security" icon="docker" color="#8b5cf6">
    * Multi-stage Docker builds (minimal attack surface)
    * Non-root user in container
    * Vulnerability scanning
    * Secret scanning to prevent credential leaks
  </Card>

  <Card title="Network Security" icon="network-wired" color="#f59e0b">
    * HTTPS only endpoints
    * Cloud Run automatic TLS
    * No exposed ports except 443
  </Card>
</CardGroup>

***

## Maintenance

### Updating Secrets

```bash theme={null}
# Update a secret value in GCP Secret Manager
echo -n "new-value" | gcloud secrets versions add SECRET_NAME \
  --project=PROJECT_ID \
  --data-file=-

# The next deployment will use the new value
```

### Adding New Secrets

<Steps>
  <Step title="Create the secret in GCP">
    ```bash theme={null}
    echo -n "value" | gcloud secrets create NEW_SECRET \
      --project=PROJECT_ID \
      --data-file=-
    ```
  </Step>

  <Step title="Update the deployment workflow">
    Add to the secrets section in the workflow file
  </Step>
</Steps>

### Cleaning Up Old Images

```bash theme={null}
# List images in Artifact Registry
gcloud artifacts docker images list \
  REGISTRY_PATH/REPOSITORY

# Delete old images
gcloud artifacts docker images delete \
  REGISTRY_PATH/REPOSITORY/IMAGE@DIGEST
```

***

## Cost Optimization

<Tip>
  Cloud Run is pay-per-use and scales to zero when idle, making it very cost-effective for development environments.
</Tip>

| Service               | Pricing Model                                  |
| --------------------- | ---------------------------------------------- |
| **Cloud Run**         | Pay-per-use, scales to zero                    |
| **Artifact Registry** | Standard storage pricing                       |
| **Secret Manager**    | Per-access operation pricing                   |
| **GitHub Actions**    | Free for public repos, usage-based for private |

***

## References

<CardGroup cols={2}>
  <Card title="GitHub Actions" icon="github" href="https://docs.github.com/en/actions">
    Official GitHub Actions documentation
  </Card>

  <Card title="Cloud Run" icon="google" href="https://cloud.google.com/run/docs">
    Google Cloud Run documentation
  </Card>

  <Card title="Workload Identity" icon="id-card" href="https://cloud.google.com/iam/docs/workload-identity-federation">
    Keyless authentication to GCP
  </Card>

  <Card title="Trivy Scanner" icon="shield" href="https://aquasecurity.github.io/trivy/">
    Security vulnerability scanner
  </Card>
</CardGroup>