# cloudsnorkel/cdk-github-runners architecture

> Architecture diagram of the GitHub repository cloudsnorkel/cdk-github-runners, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudsnorkel/cdk-github-runners
- Repository: https://github.com/cloudsnorkel/cdk-github-runners

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph GitHub
        GH_Actions[GitHub Actions/Workflows]
        GH_Webhooks[Webhooks]
        GH_Auth[Authentication]
    end

    subgraph ControlPlane
        WebhookHandler[Webhook Handler]:::lambda
        TokenRetriever[Token Retriever]:::lambda
        WebhookProcessor[Webhook Processing]:::component
        StepFunctions[Step Functions]
        SetupFunction[Setup Function]:::lambda
        StatusFunction[Status Function]:::lambda
    end

    subgraph RunnerProviders
        EC2[EC2 Provider]:::compute
        CodeBuild[CodeBuild Provider]:::compute
        Fargate[Fargate Provider]:::compute
        ECS[ECS Provider]:::compute
        Lambda[Lambda Provider]:::compute
    end

    subgraph ImageBuilding
        ImageBuilder[AWS Image Builder]:::image
        ImageVersioning[Image Versioning]:::image
        BuildWorkflow[Image Builder Workflow]:::image
        BuildImage[Build Image Function]:::lambda
    end

    subgraph SupportingInfra
        RunnerMgmt[Runner Management]:::support
        SecretsMgmt[Secrets Management]:::support
        AccessControl[Access Control]:::support
        Utils[Common Utilities]:::support
    end

    subgraph DockerImages
        CodeBuildImg[CodeBuild Images]:::docker
        FargateImg[Fargate Images]:::docker
        LambdaImg[Lambda Images]:::docker
    end

    %% Connections
    GH_Webhooks --> WebhookHandler
    GH_Auth --> TokenRetriever
    WebhookHandler --> WebhookProcessor
    WebhookProcessor --> StepFunctions
    StepFunctions --> SetupFunction
    StepFunctions --> StatusFunction
    
    SetupFunction --> |provision| RunnerProviders
    StatusFunction --> |monitor| RunnerProviders
    
    ImageBuilder --> ImageVersioning
    ImageVersioning --> BuildWorkflow
    BuildWorkflow --> BuildImage
    
    RunnerProviders --> RunnerMgmt
    RunnerMgmt --> SecretsMgmt
    AccessControl --> RunnerProviders
    
    CodeBuild --> CodeBuildImg
    Fargate --> FargateImg
    Lambda --> LambdaImg

    %% Click Events
    click WebhookHandler "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/webhook-handler.lambda.ts"
    click TokenRetriever "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/token-retriever.lambda.ts"
    click WebhookProcessor "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/webhook.ts"
    click SetupFunction "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/setup.lambda.ts"
    click StatusFunction "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/status.lambda.ts"
    click EC2 "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/providers/ec2.ts"
    click CodeBuild "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/providers/codebuild.ts"
    click Fargate "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/providers/fargate.ts"
    click ECS "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/providers/ecs.ts"
    click Lambda "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/providers/lambda.ts"
    click ImageBuilder "https://github.com/CloudSnorkel/cdk-github-runners/tree/main/src/image-builders/aws-image-builder/"
    click ImageVersioning "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/image-builders/aws-image-builder/versioner.lambda.ts"
    click BuildWorkflow "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/image-builders/aws-image-builder/workflow.ts"
    click BuildImage "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/image-builders/build-image.lambda.ts"
    click RunnerMgmt "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/runner.ts"
    click SecretsMgmt "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/secrets.ts"
    click AccessControl "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/access.ts"
    click Utils "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/src/utils.ts"
    click CodeBuildImg "https://github.com/CloudSnorkel/cdk-github-runners/tree/main/src/providers/docker-images/codebuild/"
    click FargateImg "https://github.com/CloudSnorkel/cdk-github-runners/tree/main/src/providers/docker-images/fargate/"
    click LambdaImg "https://github.com/CloudSnorkel/cdk-github-runners/tree/main/src/providers/docker-images/lambda/"

    %% Styles
    classDef lambda fill:#90EE90
    classDef compute fill:#FFA500
    classDef image fill:#DDA0DD
    classDef support fill:#A9A9A9
    classDef docker fill:#1E90FF
    classDef component fill:#ADD8E6
```
