How cloudsnorkel/cdk-github-runners works
Main Components
a. GitHub Integration Layer
• GitHub Webhook Handler (Lambda)
• Token Retriever (Lambda)
• Authentication Components (App/PAT)
b. Orchestration Layer
• Step Functions for runner lifecycle management
• Status Function (Lambda)
• Setup Function (Lambda)
c. Runner Providers Layer (show all options)
• EC2 Provider
• CodeBuild Provider
• Fargate Provider
• ECS Provider
• Lambda Provider
d. Image Building System
• AWS Image Builder components
• Image versioning system
• Build pipeline components
e. Supporting Infrastructure
• VPC (optional)
• Security Groups
• IAM Roles and Permissions
• CloudWatch Logs
• SNS Topics for notifications
┌─ GitHub ─────────────────────────────────────┐
• Actions/Workflows │ Webhooks │ Authentication │
• ┘
• ↕
┌─ Control Plane ──────────────────────────────┐
• Webhook Handler → Step Functions → Providers │
• Token Retriever Orchestration Selection │
• ┘
• ↕
┌─ Runner Providers ────────────────────────────┐
• ┌─EC2─┐ ┌─CodeBuild─┐ ┌─Fargate─┐ ┌─Lambda─┐ │
• ┘
• ↕
┌─ Image Building ─────────────────────────────┐
• AWS Image Builder Pipeline │
• Image Versioning and Management │
• ┘
Important Flows to Highlight
a. Job Request Flow:
GitHub Webhook → Webhook Handler → Step Functions → Provider Selection → Runner Provisioning
b. Image Building Flow:
Image Builder → Version Management → AMI/Container Registry → Runner Provisioning
c. Authentication Flow:
GitHub App/PAT → Token Retriever → Secure Storage → Runner Authentication
Additional Elements
• CloudWatch Logs integration points
• Monitoring and metrics flow
• Security boundaries
• VPC boundaries where applicable
• Auto-scaling components
Specific Implementation Details
• IAM role attachments
• Integration with AWS services like SNS for notifications
Notes Section
A notes section explaining:
• Default configurations
• Customization points
• Security considerations
• Scaling behavior