🚀 Enterprise Github App

Enterprise DevOps Control Plane - Governed Releases, Deployment Authorization & CI/CD Orchestration

🚀 Quick Start • 📋 Features • 🛠️ Tech Stack • 📁 Architecture • 🔧 Installation

---

🌟 What is Enterprise Github App?

Enterprise Github App is the core GitHub App that serves as the control plane for enterprise DevOps operations. A separate GitHub Action acts as a thin client calling this App's API, providing seamless integration with existing workflows.

🎯 Our Vision

• Enterprise-Ready Security - GitHub App authentication with JWT and installation tokens
• Governance First - Release validation and deployment authorization built-in
• Audit Trail - Complete logging and compliance for all operations
• Developer-Friendly - Clean API design with comprehensive documentation
• Scalable Architecture - Built for enterprise-scale deployments
• Security by Design - Webhook signature verification and least-privilege access

---

📋 Features

✅ V1 Foundation Features

• GitHub App Authentication - JWT generation and installation token handling
• Public HTTP API - Health endpoint, release validation, deployment authorization
• GitHub Webhook Handling - Installation events, ping event, signature verification
• Audit Logging - Store basic events (release check, deployment check)
• Configuration Management - Environment-based configuration with no hardcoded secrets
• Database Integration - PostgreSQL with proper migrations and schema
• Containerized Deployment - Docker and docker-compose ready

🔄 Security Features

• Webhook Signature Verification - SHA-256 HMAC verification for all webhooks
• JWT Authentication - GitHub App JWT with proper expiration handling
• Installation Access Tokens - Per-installation token management
• Least Privilege Design - Minimal required permissions and scopes
• Secure Configuration - Environment-based secrets management
• PostgreSQL Integration - Secure database with connection pooling

---

🛠️ Tech Stack

🏗️ Backend Foundation

Go 1.23+ with Clean Architecture
├── 🌐 Gin HTTP Framework (High Performance Router)
├── 🗄️ PostgreSQL (Enterprise Database)
├── 🔐 JWT Authentication (GitHub App Integration)
├── 🔒 Webhook Signature Verification (Security)
├── 📊 Audit Logging (Compliance)
├── 🐳 Docker Support (Containerization)
└── 📝 Environment Configuration (12-Factor App)

🏛️ Architecture Components

Platform Layer (HTTP Server)
├── GitHub Client (Authentication & API)
├── API Handlers (Release Validation & Deployment Auth)
├── Webhook Handlers (Event Processing)
├── Audit Service (Event Logging)
├── Storage Layer (Database Operations)
└── Configuration (Environment Management)

---

📁 Architecture

🏗️ Clean Architecture Structure

github-enterprise/
├── cmd/server/main.go              # Application Entry Point
├── app/
│   ├── platform/                   # HTTP Server & Routes
│   │   ├── server.go              # Main HTTP server
│   │   ├── api.go                 # API handlers
│   │   └── webhooks.go            # Webhook handlers
│   ├── github/                     # GitHub Integration
│   │   └── client.go              # GitHub App client
│   ├── api/                        # API Layer
│   │   └── handlers.go            # API request handlers
│   ├── releases/                   # Release Management
│   │   └── models.go              # Release data structures
│   ├── deployments/                # Deployment Management
│   │   └── models.go              # Deployment data structures
│   ├── audit/                      # Audit Logging
│   │   └── service.go             # Audit service
│   ├── config/                     # Configuration
│   │   └── config.go              # Environment config
│   └── storage/                    # Database Layer
│       ├── database.go             # Database connection
│       └── migrations/             # Database migrations
├── docs/                           # Documentation
├── .github/workflows/              # CI/CD workflows
├── Dockerfile                      # Container definition
├── docker-compose.yml              # Development environment
└── README.md                       # This file

🔄 Data Flow Architecture

GitHub Webhooks ──► Sky Genesis Enterprise ──► PostgreSQL Database
       ▲                        │                        │
       │                        ▼                        ▼
GitHub Actions ◄─────── HTTP API ◄────── Audit Logs ◄───────
         (Future Client)          (Release Validation)      (Event Storage)

---

🚀 Quick Start

📋 Prerequisites

• Go 1.23 or higher
• PostgreSQL 14.0 or higher
• Docker and Docker Compose (optional, for containerized setup)
• GitHub App configured with required permissions

🔧 Installation & Setup

Option 1: Docker Compose (Recommended)

1. Clone the repository

   git clone https://github.com/skygenesisenterprise/github-enterprise.git
   cd github-enterprise

2. Configure environment variables

   cp .env.example .env
   # Edit .env with your GitHub App credentials

3. Start services

   docker-compose up -d

4. Verify installation

   curl http://localhost:8080/api/v1/health

Option 2: Local Development

1. Install dependencies

   go mod download

2. Set up PostgreSQL database

   # Create database
   createdb sky_genesis
   
   # Run migrations
   psql -d sky_genesis -f app/storage/migrations/001_initial_schema.sql

3. Configure environment variables

   export GITHUB_APP_ID=your_app_id
   export GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
   export GITHUB_WEBHOOK_SECRET=your_webhook_secret
   export DB_HOST=localhost
   export DB_PORT=5432
   export DB_USER=postgres
   export DB_PASSWORD=your_password
   export DB_NAME=sky_genesis

4. Run the application

   go run cmd/server/main.go

🌐 API Endpoints

Once running, the following endpoints are available:

• Health Check: GET /api/v1/health
• Release Validation: POST /api/v1/releases/validate
• Deployment Authorization: POST /api/v1/deployments/authorize
• GitHub Webhooks: POST /webhook/github

🔧 Environment Configuration

Variable	Required	Description	Default
PORT	No	HTTP server port	8080
GITHUB_APP_ID	Yes	GitHub App ID	-
GITHUB_PRIVATE_KEY	Yes	GitHub App private key (PEM format)	-
GITHUB_WEBHOOK_SECRET	Yes	GitHub webhook secret	-
GITHUB_BASE_URL	No	GitHub API base URL	https://api.github.com
DB_HOST	No	Database host	localhost
DB_PORT	No	Database port	5432
DB_USER	No	Database user	postgres
DB_PASSWORD	Yes	Database password	-
DB_NAME	No	Database name	sky_genesis
DB_SSLMODE	No	Database SSL mode	disable

---

🔧 GitHub App Configuration

📋 Required Permissions

Configure your GitHub App with these permissions for V1 functionality:

Repository Permissions

• Read access to:
  • Metadata - Read repository metadata
  • Contents - Read repository contents
  • Issues - Read issues (for audit context)
  • Pull requests - Read pull requests

Organization Permissions

• Read access to:
  • Members - Read organization members
  • Administration - Read organization settings

Webhook Events

• Installation - Installation/uninstallation events
• Installation repositories - Repository added/removed from installation
• Ping - GitHub ping events
• Release - Release events (for future V2 features)
• Deployment - Deployment events (for future V2 features)

🔧 Webhook Configuration

• Webhook URL: https://your-domain.com/webhook/github
• Content type: application/json
• Secret: Use a strong, randomly generated secret
• SSL verification: Enabled (recommended for production)

---

🔒 Security

🛡️ Security Features

• Webhook Signature Verification - All webhooks verified using SHA-256 HMAC
• JWT Authentication - GitHub App JWT with 10-minute expiration
• Installation Token Management - Secure token handling with proper expiration
• Environment-Based Configuration - No hardcoded secrets or credentials
• Least Privilege Access - Minimal required permissions and scopes
• Secure Database Connections - SSL/TLS support with connection pooling

🔐 Security Best Practices

1. Environment Variables - All secrets managed via environment variables
2. Token Rotation - JWT tokens expire in 10 minutes, installation tokens in 1 hour
3. Input Validation - All API inputs validated and sanitized
4. Error Handling - Sensitive information never leaked in error messages
5. Audit Logging - All security events logged for compliance
6. CORS Configuration - Proper cross-origin resource sharing settings

---

📊 API Documentation

🔍 Health Check

GET /api/v1/health

Response:

{
  "status": "ok",
  "timestamp": "2025-01-15T10:30:00Z",
  "service": "skygenesisenterprise"
}

✅ Release Validation

POST /api/v1/releases/validate
Content-Type: application/json

{
  "repository_id": 123456789,
  "repository_name": "my-repo",
  "owner_login": "my-org",
  "tag_name": "v1.0.0",
  "target_commitish": "main",
  "installation_id": 987654321
}

Response:

{
  "release_id": "uuid-string",
  "validation_status": "approved",
  "validation_message": "Release validated successfully"
}

🚀 Deployment Authorization

POST /api/v1/deployments/authorize
Content-Type: application/json

{
  "repository_id": 123456789,
  "repository_name": "my-repo",
  "owner_login": "my-org",
  "ref": "main",
  "sha": "abc123def456",
  "environment": "production",
  "installation_id": 987654321
}

Response:

{
  "deployment_id": "uuid-string",
  "authorization_status": "approved",
  "authorization_message": "Deployment authorized successfully"
}

---

🗺️ Development Roadmap

🎯 Phase 1: Foundation (✅ Complete - Q1 2025)

• ✅ GitHub App Authentication - JWT and installation token handling
• ✅ HTTP API Server - Core endpoints with Gin framework
• ✅ Webhook Processing - Signature verification and event handling
• ✅ Database Integration - PostgreSQL with migrations
• ✅ Audit Logging - Basic event storage and retrieval
• ✅ Containerization - Docker and docker-compose support

🚀 Phase 2: Enhanced Features (🔄 In Progress - Q2 2025)

• 🔄 Advanced Validation Rules - Custom release validation policies
• 🔄 Deployment Approval Workflows - Multi-level authorization
• 🔄 Enhanced Audit System - Detailed event correlation and reporting
• 📋 Admin Dashboard - Web-based configuration interface
• 📋 Metrics & Monitoring - Prometheus integration and health checks

🌟 Phase 3: Enterprise Features (Q3-Q4 2025)

• 📋 Multi-Environment Support - Staging, production, custom environments
• 📋 Policy Engine - Advanced governance rules engine
• 📋 Integration Marketplace - Third-party tool integrations
• 📋 Advanced Security - SAML/OIDC integration, RBAC
• 📋 Analytics & Reporting - Comprehensive DevOps insights

---

🤝 Contributing

We welcome contributions to Sky Genesis Enterprise! Whether you're experienced with Go, GitHub Apps, or enterprise DevOps, there's a place for you.

🎯 How to Get Started

1. Fork the repository and create a feature branch
2. Check the issues for tasks that need help
3. Review the architecture and code patterns
4. Start small - Documentation, tests, or minor features
5. Follow our coding standards and commit guidelines

🏗️ Areas Needing Help

• Backend Development - Go services, API endpoints, business logic
• Security Experts - Authentication, authorization, vulnerability assessment
• DevOps Engineers - Deployment, monitoring, CI/CD optimization
• Database Specialists - Schema design, query optimization, migrations
• Documentation - API docs, user guides, technical writing
• Testing - Unit tests, integration tests, security testing

📝 Development Guidelines

• Clean Architecture - Follow established patterns and separation of concerns
• Idiomatic Go - Use standard Go conventions and best practices
• Security First - All code reviewed for security implications
• Comprehensive Testing - Unit tests for all business logic
• Documentation - Clear, concise documentation for all APIs

---

📞 Support & Community

💬 Get Help

• 📖 Documentation - Comprehensive guides and API documentation
• 🐛 GitHub Issues - Bug reports and feature requests
• 💡 GitHub Discussions - General questions and ideas
• 📧 Email - support@skygenesisenterprise.com

🐛 Reporting Issues

When reporting bugs, please include:

• Clear description of the problem
• Steps to reproduce the issue
• Environment information (Go version, PostgreSQL version, etc.)
• Error logs or screenshots
• Expected vs actual behavior

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 Sky Genesis Enterprise

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

---

🙏 Acknowledgments

• Sky Genesis Enterprise - Project leadership and development
• Go Team - Excellent programming language and ecosystem
• Gin Framework - High-performance HTTP web framework
• GitHub - Platform and excellent developer tools
• PostgreSQL - Powerful, reliable database system
• Docker - Container platform simplifying deployment
• Open Source Community - Tools, libraries, and inspiration

---

🚀 Join Us in Building the Future of Enterprise DevOps!

⭐ Star This Repo • 🐛 Report Issues • 💡 Start a Discussion

---

🔧 V1 Foundation Complete - Ready for Enterprise Deployment!

Made with ❤️ by the Sky Genesis Enterprise team

Building enterprise DevOps governance with security-first design and scalable architecture