How octo-sts/app works
Main Components
a) Core Service Components:
• GitHub App Interface
• STS Exchange Service
• Token Federation System
• Trust Policy Manager
• Webhook Handler
• Prober Service
b) External Systems:
• GitHub API
• Client Workloads (Token Requestors)
• Google Cloud Platform (indicated by GCP KMS usage)
Client Layer
API Layer
Service Layer
Infrastructure Layer
Component Relationships
a) Primary Flow:
Client Workload → STS Exchange Service → Trust Policy Manager → GitHub API
b) Secondary Flows:
• Webhook Handler ↔ GitHub API
• Prober Service → System Health Monitoring
• GCP KMS Integration → Security Layer
Specific Implementation Details
Key technical elements:
• GRPC Service Implementation
• Trust Policy Configuration (.github/chainguard/*.sts.yaml)
• Token Exchange Flow
• Permission Management System
Detailed Component Breakdown
• envconfig: Configuration Management
• gcpkms: Security Layer
• ghtransport: GitHub Transport Layer
• octosts: Core STS Logic
• webhook: GitHub Event Handling
• prober: Health Monitoring
Infrastructure Components
• Load Balancer (gclb.tf)
• Message Broker (broker.tf)
• Probing System (prober.tf)
Implementation Notes
• Clear separation between command (cmd/) and package (pkg/) components
• Infrastructure as Code integration
• Testing components and validation flows
• Security boundary demarcation
Key Flows to Illustrate
a) Token Exchange Flow:
Client → STS Exchange → Trust Policy Validation → GitHub Token Generation
b) Webhook Processing:
GitHub → Webhook Handler → Event Processing → State Update
Additional Elements
Annotations for:
• Configuration Management
• Security Controls
• Monitoring Points
• Integration Points
This system design should emphasize the security-first nature of the project while clearly showing how it eliminates the need for GitHub Personal Access Tokens through its federation mechanism.