Skip to content

CI/CD Pipeline Documentation

Overview

This directory contains documentation for the Continuous Integration and Continuous Deployment (CI/CD) pipelines used in the Loan Defenders project.

Platform: GitHub Actions Authentication: OpenID Connect (OIDC) - Passwordless authentication to Azure Deployment Target: Azure Container Apps, Azure AI Services

📋 Documentation Index

Core Documentation

Key Workflows

Infrastructure Deployment

  • File: .github/workflows/deploy-infrastructure.yml
  • Trigger: Manual (workflow_dispatch)
  • Purpose: Deploy Azure infrastructure using Bicep templates
  • Authentication: OIDC (passwordless)
  • Stages: foundation, security, ai, apps, vpn, all

Application Deployment

  • File: .github/workflows/deploy-api.yml
  • Trigger: Push to main (auto), Manual (workflow_dispatch)
  • Purpose: Build and deploy Container Apps
  • Features: Docker build, Azure Container Registry push, rolling deployment

Testing & Quality

  • File: .github/workflows/test.yml
  • Trigger: Pull request, Push to main
  • Purpose: Run tests, linting, and code coverage checks
  • Requirements: ≥85% coverage on core modules

Environment Management

  • File: .github/workflows/teardown-dev-environment.yml
  • Trigger: Manual (workflow_dispatch)
  • Purpose: Delete dev environment resources to save costs
  • Cost Savings: ~$100-500/month when not needed

🔐 Security & Authentication

OIDC (OpenID Connect) Authentication

The project uses passwordless authentication to Azure via OIDC federation:

Benefits: - ✅ No passwords or service principal secrets stored in GitHub - ✅ Short-lived tokens (expire in minutes) - ✅ Repository-scoped (only this repo can authenticate) - ✅ Branch-restricted (only specific branches can deploy) - ✅ Full audit trail in both GitHub Actions and Azure AD

Setup: See OIDC Setup Guide

How it works: 1. GitHub Actions requests a token from GitHub's OIDC provider 2. Token includes claims: repo, branch, workflow 3. Azure AD validates token against federated credentials 4. Azure grants short-lived access token 5. Deployment proceeds with Azure permissions

Required Secrets

The following non-sensitive IDs are stored as GitHub secrets:

  • AZURE_CLIENT_ID - Application (client) ID for GitHub Actions app registration
  • AZURE_TENANT_ID - Azure AD tenant ID
  • AZURE_SUBSCRIPTION_ID - Azure subscription ID

Note: These are IDs, not secrets. The actual authentication happens via OIDC trust relationship.

🚀 Deployment Flow

Infrastructure Deployment Flow

1. Developer triggers workflow (manual)
   ↓
2. GitHub Actions authenticates via OIDC
   ↓
3. PowerShell validates Bicep templates
   ↓
4. Deploy to Azure (staged: foundation → security → ai → apps)
   ↓
5. Output deployment results
   ↓
6. Verify resources in Azure Portal

Application Deployment Flow

1. Code pushed to main (or manual trigger)
   ↓
2. Run tests and linting
   ↓
3. Build Docker image
   ↓
4. Push to Azure Container Registry
   ↓
5. Deploy to Container Apps (rolling update)
   ↓
6. Health check verification
   ↓
7. Deployment complete

📊 Pipeline Status

Production Pipelines

  • Infrastructure: Manual deployment to avoid accidental changes
  • Applications: Auto-deploy on main branch push (after tests pass)
  • Monitoring: Application Insights tracks deployments

Development Pipelines

  • Pull Requests: Automatic testing and validation
  • Feature Branches: Manual deployment option available
  • Dev Environment: Can be torn down when not needed

🛠️ Common Tasks

Deploy Infrastructure

# Via GitHub Actions UI
1. Go to: Actions → "Deploy Azure Infrastructure"
2. Click "Run workflow"
3. Select: Environment (dev/staging/prod)
4. Select: Stage (foundation/security/ai/apps/all)
5. Click "Run workflow"

Deploy Application

# Auto-deploy: Just push to main branch
git push origin main

# Manual deploy: Use GitHub Actions UI
1. Go to: Actions → "Deploy API"
2. Click "Run workflow"
3. Select: Environment (dev/staging/prod)
4. Click "Run workflow"

Teardown Dev Environment

# Via GitHub Actions UI
1. Go to: Actions → "Teardown Dev Environment"
2. Click "Run workflow"
3. Confirm environment name
4. Click "Run workflow"

# Note: Rebuild takes ~25 minutes

📈 Monitoring & Observability

Deployment Monitoring

  • Application Insights: Deployment events, performance metrics
  • Log Analytics: Centralized logs from all deployments
  • GitHub Actions Logs: Full pipeline execution logs

Key Metrics

  • Deployment Duration: Track how long deployments take
  • Success Rate: Monitor deployment failures
  • Health Checks: Post-deployment verification
  • Resource Costs: Track Azure spending per environment

🐛 Troubleshooting

OIDC Authentication Fails

Error: AADSTS700016: Application not found Fix: Run infrastructure/scripts/setup-github-service-principal.sh to configure OIDC

Deployment Timeouts

Error: Deployment exceeded maximum duration Fix: AI Foundry deployments can take 15-20 minutes - increase timeout in workflow

Bicep Validation Errors

Error: The template is not valid Fix: Test locally with az bicep build --file infrastructure/bicep/all-in-one.bicep

Container Image Not Found

Error: Failed to pull image Fix: Ensure Azure Container Registry is accessible and image was pushed successfully

Last Updated: 2025-10-06 Maintained By: Development Team