https://github.com/skygenesisenterprise/github-enterprise
The Official Github App for Sky Genesis Enterprise Git Integration
https://github.com/skygenesisenterprise/github-enterprise
api-service docker github-actions github-app github-deployment javascript typescript
Last synced: 24 days ago
JSON representation
The Official Github App for Sky Genesis Enterprise Git Integration
- Host: GitHub
- URL: https://github.com/skygenesisenterprise/github-enterprise
- Owner: skygenesisenterprise
- License: mit
- Created: 2025-10-27T05:54:49.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-12-22T02:24:39.000Z (about 1 month ago)
- Last Synced: 2025-12-22T15:48:05.083Z (about 1 month ago)
- Topics: api-service, docker, github-actions, github-app, github-deployment, javascript, typescript
- Language: Go
- Homepage: https://skygenesisenterprise.com
- Size: 77.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Support: .github/SUPPORT.md
- Governance: Governance.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 🚀 Enterprise Github App
[](https://opensource.org/licenses/MIT)
[](https://golang.org/)
[](https://www.docker.com/)
[](https://docs.github.com/en/developers/apps)
**Enterprise DevOps Control Plane - Governed Releases, Deployment Authorization & CI/CD Orchestration**
[🚀 Quick Start](#-quick-start) • [📋 Features](#-features) • [🛠️ Tech Stack](#️-tech-stack) • [📁 Architecture](#-architecture) • [🔧 Installation](#-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**
```bash
git clone https://github.com/skygenesisenterprise/github-enterprise.git
cd github-enterprise
```
2. **Configure environment variables**
```bash
cp .env.example .env
# Edit .env with your GitHub App credentials
```
3. **Start services**
```bash
docker-compose up -d
```
4. **Verify installation**
```bash
curl http://localhost:8080/api/v1/health
```
#### Option 2: Local Development
1. **Install dependencies**
```bash
go mod download
```
2. **Set up PostgreSQL database**
```bash
# Create database
createdb sky_genesis
# Run migrations
psql -d sky_genesis -f app/storage/migrations/001_initial_schema.sql
```
3. **Configure environment variables**
```bash
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**
```bash
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**
```http
GET /api/v1/health
```
**Response:**
```json
{
"status": "ok",
"timestamp": "2025-01-15T10:30:00Z",
"service": "skygenesisenterprise"
}
```
### ✅ **Release Validation**
```http
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:**
```json
{
"release_id": "uuid-string",
"validation_status": "approved",
"validation_message": "Release validated successfully"
}
```
### 🚀 **Deployment Authorization**
```http
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:**
```json
{
"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](./docs/)** - Comprehensive guides and API documentation
- 🐛 **[GitHub Issues](https://github.com/skygenesisenterprise/github-enterprise/issues)** - Bug reports and feature requests
- 💡 **[GitHub Discussions](https://github.com/skygenesisenterprise/github-enterprise/discussions)** - General questions and ideas
- 📧 **Email** - [support@skygenesisenterprise.com](mailto: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](./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](https://github.com/skygenesisenterprise/github-enterprise) • [🐛 Report Issues](https://github.com/skygenesisenterprise/github-enterprise/issues) • [💡 Start a Discussion](https://github.com/skygenesisenterprise/github-enterprise/discussions)
---
**🔧 V1 Foundation Complete - Ready for Enterprise Deployment!**
**Made with ❤️ by the [Sky Genesis Enterprise](https://skygenesisenterprise.com) team**
*Building enterprise DevOps governance with security-first design and scalable architecture*