CI/CD Deployment Guide

Target Audience: DevOps engineers, AI agents, deployment teams Status: Production Ready

Overview
Multi-Agent Deployment Orchestration
Environment Variables
Workflow Triggers
6-Phase Deployment Process
Troubleshooting

Overview

What This Guide Covers

Complete CI/CD deployment workflow using multi-agent orchestration:

6-phase deployment process from planning to documentation
Agent-based automation for each deployment stage
GitHub Actions integration for CI/CD pipelines
Infrastructure as Code (Terraform/Pulumi)
Security auditing and compliance validation
Comprehensive documentation generation

Key Benefits

Automated Deployment: End-to-end automation with minimal human intervention
Multi-Agent Coordination: Specialized agents for each deployment phase
Quality Gates: Automated testing and security checks
Reproducible: Infrastructure as Code ensures consistency
Documented: Auto-generated deployment documentation

Multi-Agent Deployment Orchestration

Phase 1: Planning (orchestrator)

Purpose: Create deployment plan with agent assignments and dependency resolution

Agent: orchestrator

Invocation

Task(subagent_type="orchestrator",
     description="Plan deployment workflow",
     prompt="Create deployment plan for [application] with agent assignments and dependency resolution")

Deliverables

Deployment plan document
Agent assignment matrix
Dependency graph
Timeline and milestones

Example Output

## Deployment Plan: my-web-app

### Phases:
1. Infrastructure setup (cloud-architect)
2. CI/CD pipeline (devops-engineer)
3. Application deployment (devops-engineer)
4. Security audit (security-specialist)
5. Documentation (codi-documentation-writer)

### Dependencies:
- Infrastructure must complete before pipeline setup
- Security audit after initial deployment
- Documentation concurrent with all phases

### Timeline:
- Week 1: Infrastructure + CI/CD
- Week 2: Deployment + Security
- Week 3: Documentation + Polish

Phase 2: CI/CD Pipeline (devops-engineer)

Purpose: Implement GitHub Actions workflows for testing, building, and deployment

Agent: codi-devops-engineer

Invocation

Task(subagent_type="codi-devops-engineer",
     description="Implement CI/CD pipeline",
     prompt="Create GitHub Actions workflows for [application] with testing, building, and deployment stages")

Deliverables

.github/workflows/ci.yml - Continuous integration
.github/workflows/cd.yml - Continuous deployment
.github/workflows/test.yml - Test automation
Build and deployment scripts

Example Workflow (CI)

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: |
          npm install
          npm test
      - name: Build
        run: npm run build

Example Workflow (CD)

# .github/workflows/cd.yml
name: CD

on:
  push:
    branches: [main]

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v3
      - name: Deploy to staging
        run: ./scripts/deploy.sh staging
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}

Phase 3: Infrastructure (cloud-architect)

Purpose: Design production infrastructure using Infrastructure as Code

Agent: cloud-architect

Invocation

Task(subagent_type="cloud-architect",
     description="Design production infrastructure",
     prompt="Create IaC (Terraform/Pulumi) for [application] deployment to [cloud-platform]")

Deliverables

Infrastructure as Code (Terraform/Pulumi)
Network configuration
Security groups and firewall rules
Load balancer configuration
Auto-scaling policies

Example Terraform

# main.tf
provider "google" {
  project = var.project_id
  region  = var.region
}

resource "google_compute_instance" "app" {
  name         = "coditect-app"
  machine_type = "e2-medium"

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-11"
    }
  }

  network_interface {
    network = "default"
    access_config {}
  }

  metadata_startup_script = file("startup.sh")
}

resource "google_compute_firewall" "http" {
  name    = "allow-http"
  network = "default"

  allow {
    protocol = "tcp"
    ports    = ["80", "443"]
  }

  source_ranges = ["0.0.0.0/0"]
}

Phase 4: Docker Environment (devops-engineer)

Purpose: Create production-ready Docker configuration

Agent: codi-devops-engineer

Invocation

Task(subagent_type="codi-devops-engineer",
     description="Create Docker development environment",
     prompt="Build production-ready Dockerfile and docker-compose.yml for [application]")

Deliverables

Dockerfile - Production container image
docker-compose.yml - Multi-service orchestration
.dockerignore - Build optimization
Container health checks
Multi-stage builds for optimization

Example Dockerfile

# Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s \
  CMD node healthcheck.js
CMD ["node", "dist/server.js"]

Example Docker-compose.yml

# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DATABASE_URL=${DATABASE_URL}
    depends_on:
      - postgres
      - redis
    restart: unless-stopped

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=appdb
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    restart: unless-stopped

volumes:
  postgres-data:

Phase 5: Security (security-specialist)

Purpose: Audit deployment security and provide hardening recommendations

Agent: security-specialist

Invocation

Task(subagent_type="security-specialist",
     description="Security audit",
     prompt="Audit deployment security for [application] and provide hardening recommendations")

Deliverables

Security audit report
Vulnerability assessment
Hardening recommendations
Compliance checklist (OWASP, CIS)
Secrets management review

Example Audit Report

## Security Audit Report: my-web-app

### Critical Issues (Must Fix)
- [ ] Secrets stored in environment variables (use secret manager)
- [ ] No rate limiting on API endpoints
- [ ] HTTPS not enforced (redirect HTTP → HTTPS)

### High Priority
- [ ] Add Content Security Policy headers
- [ ] Enable CORS with whitelist
- [ ] Implement request validation

### Medium Priority
- [ ] Add dependency vulnerability scanning
- [ ] Implement audit logging
- [ ] Add intrusion detection

### Recommendations:
1. Use Google Cloud Secret Manager for sensitive data
2. Implement rate limiting with express-rate-limit
3. Add helmet.js for security headers
4. Enable HTTPS with Let's Encrypt

Phase 6: Documentation (codi-documentation-writer)

Purpose: Create comprehensive deployment documentation

Agent: codi-documentation-writer

Invocation

Task(subagent_type="codi-documentation-writer",
     description="Create deployment docs",
     prompt="Write comprehensive deployment documentation for [application] with runbooks and troubleshooting")

Deliverables

Deployment guide
Runbooks for common operations
Troubleshooting guide
Architecture diagrams
API documentation

Example Deployment Guide

## Deployment Guide: my-web-app

### Prerequisites
- Docker and Docker Compose installed
- GitHub Actions secrets configured
- Cloud platform account (GCP/AWS)

### Deployment Steps

**1. Prepare environment:**

Clone repository

git clone https://github.com/org/my-web-app.git cd my-web-app

Configure secrets

cp .env.example .env

Edit .env with production values

**2. Deploy infrastructure:**

Initialize Terraform

cd terraform terraform init

Plan deployment

terraform plan -out=deployment.tfplan

Apply infrastructure

terraform apply deployment.tfplan

**3. Deploy application:**

Push to main branch (triggers CD)

git push origin main

Monitor deployment

gh run watch

**4. Verify deployment:**

Check application health

curl https://my-app.example.com/health

Expected: {"status": "ok"}

Environment Variables

Set in GitHub repository Settings → Secrets:

Cloud Platform Secrets

# Google Cloud Platform

GCP_SA_KEY              # Service account key (JSON)
GCP_PROJECT_ID          # Project ID
GCP_REGION              # Deployment region

# AWS

AWS_ACCESS_KEY_ID       # Access key
AWS_SECRET_ACCESS_KEY   # Secret key
AWS_REGION              # Deployment region

# Azure

AZURE_CREDENTIALS       # Service principal
AZURE_SUBSCRIPTION_ID   # Subscription

Container Registry Secrets

DOCKERHUB_USERNAME      # Docker Hub username
DOCKERHUB_TOKEN         # Docker Hub token
GHCR_TOKEN              # GitHub Container Registry token

Application Secrets

DATABASE_URL            # Database connection string
Redis_URL               # Redis connection string
API_KEY                 # Third-party API keys
JWT_SECRET              # JWT signing key
ENCRYPTION_KEY          # Data encryption key

Notification Secrets

SLACK_WEBHOOK_URL       # Slack notifications
EMAIL_API_KEY           # Email service
PAGERDUTY_KEY           # PagerDuty integration

Workflow Triggers

Trigger Configuration

Push to main branch → build + deploy to staging

on:
  push:
    branches: [main]

Pull request → build + test only

on:
  pull_request:
    branches: [main]

Manual deployment with environment selection

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

Scheduled deployments

on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM UTC

6-Phase Deployment Process

Complete Workflow Example

Scenario: Deploy a web application to Google Cloud Platform

Step 1: Orchestrator Planning

Task(subagent_type="orchestrator",
     description="Plan GCP deployment",
     prompt="""
     Create deployment plan for web application:
     - Target: Google Cloud Platform
     - Services: App Engine, Cloud SQL, Redis
     - CI/CD: GitHub Actions
     - Security: IAM, Secret Manager
     """)

Step 2: DevOps - CI/CD Pipeline

Task(subagent_type="codi-devops-engineer",
     description="Implement CI/CD",
     prompt="""
     Create GitHub Actions workflows:
     - CI: Test + Build on PR
     - CD: Deploy to staging on main push
     - CD: Deploy to production on release
     - Include: Docker build, GCP deployment
     """)

Step 3: Cloud Architect - Infrastructure

Task(subagent_type="cloud-architect",
     description="Design GCP infrastructure",
     prompt="""
     Create Terraform configuration:
     - App Engine standard environment
     - Cloud SQL PostgreSQL instance
     - Memorystore Redis instance
     - Cloud Load Balancing
     - Cloud CDN
     - IAM roles and service accounts
     """)

Step 4: DevOps - Docker Environment

Task(subagent_type="codi-devops-engineer",
     description="Create Docker configuration",
     prompt="""
     Build production Dockerfile:
     - Multi-stage build for optimization
     - Node.js 18 Alpine base
     - Health checks
     - Security best practices
     - docker-compose for local development
     """)

Step 5: Security Specialist - Audit

Task(subagent_type="security-specialist",
     description="Security audit",
     prompt="""
     Audit deployment security:
     - Review IAM permissions
     - Validate secret management
     - Check network security
     - Assess application security
     - Verify compliance (OWASP, CIS)
     """)

Step 6: Documentation Writer - Documentation

Task(subagent_type="codi-documentation-writer",
     description="Create deployment documentation",
     prompt="""
     Write comprehensive deployment docs:
     - Step-by-step deployment guide
     - Runbooks for common operations
     - Troubleshooting guide
     - Architecture diagrams
     - Security documentation
     """)

Timeline

Week	Phase	Activities	Deliverables
1	Planning + CI/CD	Agent coordination, pipeline setup	Deployment plan, CI/CD workflows
2	Infrastructure + Docker	IaC creation, container config	Terraform files, Dockerfiles
3	Security + Testing	Audit, hardening, testing	Security report, test results
4	Documentation + Launch	Docs, final review, deployment	Complete documentation, production deployment

Troubleshooting

Issue 1: GitHub Actions Secrets Not Found

Problem: Workflow fails with "secret not found" error

Solution

# Verify secret exists
gh secret list

# Add missing secret
gh secret set SECRET_NAME

# Or via GitHub UI:
# Settings → Secrets → Actions → New repository secret

Issue 2: Deployment Fails on GCP

Problem: Terraform apply fails with authentication error

Solution

# Verify service account key
echo $GCP_SA_KEY | base64 -d | jq .

# Test authentication
gcloud auth activate-service-account --key-file=key.json
gcloud projects list

# Update secret
gh secret set GCP_SA_KEY < service-account-key.json

Issue 3: Docker Build Fails

Problem: Docker build fails in CI/CD

Solution

# Add debugging to workflow
- name: Build Docker image
  run: |
    docker build -t app:latest . --progress=plain
  env:
    DOCKER_BUILDKIT: 1

# Check build logs
gh run view --log

Issue 4: Security Audit Failures

Problem: Security specialist identifies critical issues

Solution

## Remediation Plan

1. **Fix critical issues immediately:**
   - Move secrets to secret manager
   - Enable HTTPS enforcement
   - Add rate limiting

2. **Schedule high priority fixes:**
   - Implement CSP headers (Week 2)
   - Add CORS whitelist (Week 2)
   - Request validation (Week 3)

3. **Plan medium priority improvements:**
   - Dependency scanning (Month 2)
   - Audit logging (Month 2)
   - Intrusion detection (Month 3)

Issue 5: Documentation Incomplete

Problem: Deployment docs missing critical information

Solution

# Re-run documentation agent with expanded prompt
Task(subagent_type="codi-documentation-writer",
     description="Expand deployment documentation",
     prompt="""
     Enhance deployment documentation with:
     - Detailed troubleshooting section
     - Rollback procedures
     - Disaster recovery
     - Performance tuning
     - Monitoring setup
     """)

Additional Resources

Docker Development Guide - Local development environment
Agent Selection for CI/CD - Complete multi-agent workflow
Local Development Docker - Container setup (10 minutes)

Agent Documentation

orchestrator - Planning and coordination
codi-devops-engineer - CI/CD and Docker
cloud-architect - Infrastructure design
security-specialist - Security auditing
codi-documentation-writer - Documentation creation

Example Workflows

Location: examples/deployment-workflows/

gcp-app-engine/ - Google Cloud Platform deployment
aws-ecs/ - AWS Elastic Container Service
azure-container-apps/ - Azure Container Apps
Kubernetes/ - Kubernetes cluster deployment

Document Status: Production Ready Last Validation: December 4, 2025 Deployment Version: v1.0 Next Review: March 2026

Table of Contents​

Overview​

What This Guide Covers​

Key Benefits​

Multi-Agent Deployment Orchestration​

For deployment-related tasks, use this 6-phase workflow​

Phase 1: Planning (orchestrator)​

Invocation​

Deliverables​

Example Output​

Phase 2: CI/CD Pipeline (devops-engineer)​

Invocation​

Deliverables​

Example Workflow (CI)​

Example Workflow (CD)​

Phase 3: Infrastructure (cloud-architect)​

Invocation​

Deliverables​

Example Terraform​

Phase 4: Docker Environment (devops-engineer)​

Invocation​

Deliverables​

Example Dockerfile​

Example Docker-compose.yml​

Phase 5: Security (security-specialist)​

Invocation​

Deliverables​

Example Audit Report​

Phase 6: Documentation (codi-documentation-writer)​

Invocation​

Deliverables​

Example Deployment Guide​

Clone repository​

Configure secrets​

Edit .env with production values​

Initialize Terraform​

Plan deployment​

Apply infrastructure​

Push to main branch (triggers CD)​

Monitor deployment​

Check application health​

Expected: {"status": "ok"}​

Environment Variables​

Set in GitHub repository Settings → Secrets:​

Cloud Platform Secrets​

Container Registry Secrets​

Application Secrets​

Notification Secrets​

Workflow Triggers​

Trigger Configuration​

Push to main branch → build + deploy to staging​

Pull request → build + test only​

Manual deployment with environment selection​

Scheduled deployments​

6-Phase Deployment Process​

Complete Workflow Example​

Step 1: Orchestrator Planning​

Step 2: DevOps - CI/CD Pipeline​

Step 3: Cloud Architect - Infrastructure​

Step 4: DevOps - Docker Environment​

Step 5: Security Specialist - Audit​

Step 6: Documentation Writer - Documentation​

Timeline​

Troubleshooting​

Issue 1: GitHub Actions Secrets Not Found​

Solution​

Issue 2: Deployment Fails on GCP​

Solution​

Issue 3: Docker Build Fails​

Solution​

Issue 4: Security Audit Failures​

Solution​

Issue 5: Documentation Incomplete​

Solution​

Additional Resources​

Related Documentation​

Agent Documentation​

Example Workflows​

Table of Contents

Overview

What This Guide Covers

Key Benefits

Multi-Agent Deployment Orchestration

For deployment-related tasks, use this 6-phase workflow

Phase 1: Planning (orchestrator)

Invocation

Deliverables

Example Output

Phase 2: CI/CD Pipeline (devops-engineer)

Invocation

Deliverables

Example Workflow (CI)

Example Workflow (CD)

Phase 3: Infrastructure (cloud-architect)

Invocation

Deliverables

Example Terraform

Phase 4: Docker Environment (devops-engineer)

Invocation

Deliverables

Example Dockerfile

Example Docker-compose.yml

Phase 5: Security (security-specialist)

Invocation

Deliverables

Example Audit Report

Phase 6: Documentation (codi-documentation-writer)

Invocation

Deliverables

Example Deployment Guide

Clone repository

Configure secrets

Edit .env with production values

Initialize Terraform

Plan deployment

Apply infrastructure

Push to main branch (triggers CD)

Monitor deployment

Check application health

Expected: {"status": "ok"}

Environment Variables

Set in GitHub repository Settings → Secrets:

Cloud Platform Secrets

Container Registry Secrets

Application Secrets

Notification Secrets

Workflow Triggers

Trigger Configuration

Push to main branch → build + deploy to staging

Pull request → build + test only

Manual deployment with environment selection

Scheduled deployments

6-Phase Deployment Process

Complete Workflow Example

Step 1: Orchestrator Planning

Step 2: DevOps - CI/CD Pipeline

Step 3: Cloud Architect - Infrastructure

Step 4: DevOps - Docker Environment

Step 5: Security Specialist - Audit

Step 6: Documentation Writer - Documentation

Timeline

Troubleshooting

Issue 1: GitHub Actions Secrets Not Found

Solution

Issue 2: Deployment Fails on GCP

Solution

Issue 3: Docker Build Fails

Solution

Issue 4: Security Audit Failures

Solution

Issue 5: Documentation Incomplete

Solution

Additional Resources

Related Documentation

Agent Documentation

Example Workflows