DeployGuard AI – Self-Hosted Deployment Orchestration Platform

DeployGuard AI is a modern, lightweight, self-hosted CI/CD and deployment orchestration platform. It integrates directly with GitHub repositories via authenticated push webhooks, automatically orchestrates Docker builds and container deployments, enforces automated HTTP health checks, and automatically rolls back to the previous stable release whenever verification fails—ensuring zero downtime and ironclad deployment safety.

Additionally, DeployGuard AI incorporates a Machine Learning Risk Engine (Random Forest Classifier) that evaluates incoming commit churn (lines added/deleted, dependency changes, previous failure history, and file counts) to predict deployment failure risk before execution.

---

Architecture Diagram

+-------------------------------------------------------------------------+
|                              Developer Push                             |
+-------------------------------------------------------------------------+
                                    |
                                    v
+-------------------------------------------------------------------------+
|                            GitHub Repository                            |
+-------------------------------------------------------------------------+
                                    |
                                    | Push Webhook (HMAC SHA-256)
                                    v
+-------------------------------------------------------------------------+
|                  FastAPI Webhook & Ingestion Gateway                    |
|      - Validate HMAC Signature (X-Hub-Signature-256)                    |
|      - Match Target Deployment Branch                                   |
|      - Extract Commit SHA, Message & Pusher                             |
+-------------------------------------------------------------------------+
                                    |
                                    v
+-------------------------------------------------------------------------+
|                   AI Deployment Risk Predictor                          |
|      - Evaluates Code Churn & Dependency Changes                        |
|      - Computes Risk Score (0-100%) & Contributing Factors              |
+-------------------------------------------------------------------------+
                                    |
                                    v
+-------------------------------------------------------------------------+
|                     State Machine Deployment Engine                     |
|                                                                         |
|   [PENDING]                                                             |
|       |                                                                 |
|       v                                                                 |
|   [CLONING]          --> Git clone & checkout exact commit SHA          |
|       |                                                                 |
|       v                                                                 |
|   [BUILDING]         --> Build Docker image                             |
|       |                                                                 |
|       v                                                                 |
|   [TESTING]          --> Run automated validation suite                 |
|       |                                                                 |
|       v                                                                 |
|   [DEPLOYING]        --> Start candidate container on mapped port       |
|       |                                                                 |
|       v                                                                 |
|   [HEALTH_CHECKING]  --> Periodic HTTP GET health checks                |
+-------------------------------------------------------------------------+
               |                                            |
         (Health Passes)                              (Health Fails)
               v                                            v
+-------------------------------+            +----------------------------------+
|           [SUCCESS]           |            |         [ROLLING_BACK]           |
| - Promote commit to STABLE    |            | - Halt failed container          |
| - Decommission old candidate  |            | - Restore previous stable        |
| - Update Project Healthy      |            |   container & verify health      |
+-------------------------------+            | - Mark state: [ROLLED_BACK]      |
                                             | - Log full failure timeline      |
                                             +----------------------------------+

---

Core Features

• GitHub Webhook Integration: Secure POST /api/webhooks/github receiver with HMAC SHA-256 signature verification (X-Hub-Signature-256).
• State Machine Deployment Pipeline: Step-by-step progression through PENDING -> CLONING -> BUILDING -> TESTING -> DEPLOYING -> HEALTH_CHECKING -> SUCCESS.
• Automatic Rollback Guarantee: If a build fails, tests fail, container crashes, or the health check does not return HTTP 2xx within configured retries, the candidate container is immediately stopped, the previous stable container is restored, and the deployment is marked as ROLLED_BACK.
• AI Deployment Risk Prediction: Random Forest ML model analyzing commit metrics (lines added/deleted, file count, dependency manifests modified, historical failure rate) to generate an explainable 0–100% Risk Score and risk factor breakdown.
• Terminal-Style Live Log Streaming: Dark IDE-themed terminal viewer featuring real-time WebSocket streaming (/api/ws/deployments/{id}), auto-scroll, log level filtering (INFO, SUCCESS, WARNING, ERROR), and one-click copy.
• Interactive Webhook Simulator: Built-in test modal to simulate real GitHub push events directly from the dashboard—test both clean deployments and failing deployments to watch the self-healing automatic rollback live.
• Dual Database Flexibility: Uses PostgreSQL in production/Docker Compose and seamlessly defaults to SQLite for zero-dependency local development.
• Docker Engine + High-Fidelity Simulation: Runs real Docker containers via Docker SDK when connected, or switches automatically to simulated mode if running in an environment without Docker daemon.

---

Technology Stack

Frontend

• React 18 with Vite
• Tailwind CSS (DevOps dark theme, glassmorphism, glowing status badges)
• Lucide React (icons)
• Recharts (deployment throughput & AI risk trajectory charts)
• Axios (REST API client)
• WebSockets (live terminal streaming)

Backend

• Python 3.9+ with FastAPI
• SQLAlchemy 2.0 ORM
• Pydantic v2 & Pydantic Settings
• Uvicorn ASGI server
• Docker SDK for Python
• Scikit-Learn 1.6.1, Pandas, and Joblib for ML risk prediction

DevOps & Infrastructure

• Docker & Docker Compose
• PostgreSQL 15 & Redis 7
• Nginx reverse proxy

---

Getting Started

Prerequisites

• Python 3.9+
• Node.js 18+ and npm
• Docker and Docker Compose (optional for local dev)

---

Local Development Setup

1. Clone Repository & Setup Environment

git clone https://github.com/your-org/deployguard-ai.git
cd deployguard-ai

# Copy environment variables
cp .env.example .env

2. Backend Setup

cd backend

# Install dependencies
pip install -r requirements.txt

# Train / bundle the AI Risk Model
python -m app.ml.train

# Run automated tests
python -m pytest tests/test_platform.py -v

# Start FastAPI backend server
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

The backend will start at http://localhost:8000. Interactive OpenAPI documentation is available at http://localhost:8000/docs.

3. Frontend Setup

In a separate terminal:

cd frontend

# Install dependencies
npm install

# Start Vite development server
npm run dev

The dashboard will open at http://localhost:5173.

---

Docker Compose Setup (Production)

To launch the full production stack (Backend, Frontend, PostgreSQL, and Redis):

docker-compose up --build

• Frontend Dashboard: http://localhost:3000
• Backend API & Docs: http://localhost:8000/docs
• PostgreSQL: localhost:5432

---

Environment Variables

Variable	Default	Description
DATABASE_URL	sqlite:///./deployguard.db	Database connection string (PostgreSQL or SQLite)
GITHUB_WEBHOOK_SECRET	deployguard-super-secret-key-12345	HMAC SHA256 secret shared with GitHub
DEMO_MODE	true	When true or Docker daemon is absent, orchestrator runs safe simulation
HOST	0.0.0.0	API bind host
PORT	8000	API port
POSTGRES_USER	deployguard	PostgreSQL username
POSTGRES_PASSWORD	deployguard_secret_pwd	PostgreSQL password
POSTGRES_DB	deployguard_db	PostgreSQL database name

---

GitHub Webhook Configuration

To connect a live GitHub repository to DeployGuard:

1. Open your repository on GitHub and navigate to Settings -> Webhooks -> Add webhook.
2. Set Payload URL to:

   http://<YOUR_DEPLOYGUARD_HOST>:8000/api/webhooks/github
   

3. Set Content type to:

   application/json
   

4. Set Secret to your configured GITHUB_WEBHOOK_SECRET (e.g. deployguard-super-secret-key-12345).
5. Under Which events would you like to trigger this webhook?, choose Just the push event.
6. Click Add webhook.

---

How Automatic Rollback Works

DeployGuard enforces a strict Blue-Green candidate validation principle:

1. Previous Stable Isolation: The currently running container and current_stable_commit are retained untouched during candidate build and startup.
2. Candidate Deployment: The newly pushed commit is cloned, built, and launched inside candidate container dg-<project>-<sha>.
3. Health Validation: DeployGuard executes HTTP GET requests against the configured health_check_path (e.g. /health or /status) with configurable retries and timeouts.
4. Failure Trigger:
   • If the candidate container crashes, Docker build fails, or the health check returns anything other than HTTP 2xx, the rollback mechanism is triggered immediately.
5. Rollback Execution:
   • Candidate container is decommissioned and removed.
   • The previous stable container is restarted and verified healthy.
   • The deployment status transitions to ROLLING_BACK -> ROLLED_BACK.
   • Comprehensive audit logs are saved and broadcasted to WebSocket subscribers.
   • The previous stable commit remains active—preventing broken code from serving production traffic.

---

AI Deployment Risk Prediction

DeployGuard includes a machine-learning module trained with Scikit-Learn:

• Model: Random Forest Classifier (max_depth=8, n_estimators=100)
• Features Evaluated:
  • files_changed: Total files touched in commit
  • lines_added & lines_deleted: Code churn volume
  • dependency_files_changed: Modifications to package.json, requirements.txt, Dockerfile, etc.
  • previous_deployment_failures: Historical failure rate for this project
  • previous_build_duration: Mean build time
  • commit_count: Number of commits in push event
• Outputs:
  • Risk Score: 0 to 100%
  • Risk Tier: LOW (0–30%), MEDIUM (31–60%), HIGH (61–100%)
  • Contributing Factors: Human-readable list of specific risk drivers.

---

API Documentation

Projects

• GET /api/projects - List all projects
• POST /api/projects - Register a new project
• GET /api/projects/{id} - Get project details
• PUT /api/projects/{id} - Update project configuration
• DELETE /api/projects/{id} - Delete project
• GET /api/projects/{id}/deployments - List project deployment history
• POST /api/projects/{id}/deploy - Trigger candidate deployment
• POST /api/projects/{id}/rollback - Manually revert to previous stable commit

Deployments & Live Streaming

• GET /api/deployments - Global list of recent deployments
• GET /api/deployments/stats/summary - Platform KPI metrics and success rates
• GET /api/deployments/{id} - Detailed deployment run status
• GET /api/deployments/{id}/logs - Retrieve execution logs
• WebSocket /api/ws/deployments/{id} - Real-time terminal log stream

Webhooks

• POST /api/webhooks/github - GitHub push webhook handler
• POST /api/webhooks/simulate - Built-in test simulator
• GET /api/webhooks/config - View webhook configuration details

System

• GET /api/health - Platform health check

---

Testing & Verification

Run the full automated pytest suite:

cd backend
python -m pytest tests/test_platform.py -v

All 5 core test suites pass:

1. test_system_health: Verifies platform readiness
2. test_ai_risk_predictor: Tests Scikit-Learn ML risk inference and factor analysis
3. test_signature_verification: Verifies HMAC SHA-256 GitHub signature security
4. test_project_crud: Validates project lifecycle
5. test_deploy_and_auto_rollback_simulation: Simulates push, health check failure, and automatic rollback verification

---

License

MIT License. Built for resilient DevOps operations.