Implement release workflow (build Docker images, deploy to staging)

[Hyperkit-dev]

🎯 Layer 1: Intent Parsing

What needs to be done?

Task Title:

Implement release workflow (build Docker images, deploy to staging)

Area: infra | Repos: infra/

Primary Goal:

Configure automated release workflow that builds Docker images for all HyperAgent services and deploys them to staging environment, enabling continuous delivery

User Story / Context:

As a DevOps engineer, I want an automated release workflow that builds Docker images and deploys to staging so that new releases can be tested in a production-like environment before production deployment

Business Impact:

Enables automated, reliable deployments with full audit trail. Supports Phase 1 Foundation goals for CI/CD and infrastructure automation. Critical for production readiness.

Task Metadata:

• Sprint: Sprint 3
• Related Epic/Project: GitHub Project 9 - Phase 1 Foundation
• Issue Type: Feature
• Area: Infra
• Related Documentation:
  • Platform Blueprint - Complete platform specification
  • System Architecture - Infrastructure design
  • Execution Strategy - Deployment strategy

---

📚 Layer 2: Knowledge Retrieval

What information do I need?

Required Skills / Knowledge:

• DevOps/Infra (CI/CD, Docker, Kubernetes)
• Container orchestration
• Release management

Estimated Effort:

M (Medium - 3-5 days)

Knowledge Resources:

• Review .cursor/skills/ for relevant patterns (devops-engineer, github-actions-templates)
• Check .cursor/llm/docs/ for implementation examples
• Read Platform Blueprint: docs/draft.md
• Read System Architecture: docs/planning/4-System-Architecture-Design.md
• Read Execution Strategy: docs/reference/spec/execute.md
• Study tech docs / ADRs in docs/adrs/ directory
• Review GitHub Actions workflows and Docker best practices

Architecture Context:

According to the Platform Blueprint, HyperAgent uses a microservice architecture with orchestrator, agent services, and core services. The release workflow will build Docker images for all services and deploy them to staging.

System Architecture Diagram:

graph TB
    subgraph "CI/CD Pipeline"
        GitHub[GitHub Actions]
        Build[Docker Build]
        Test[Test Suite]
        Push[Push to Registry]
        Deploy[Deploy to Staging]
    end
    
    subgraph "Container Registry"
        Registry[Docker Registry<br/>GHCR/AWS ECR]
    end
    
    subgraph "Staging Environment"
        K8s[Kubernetes Cluster]
        Services[HyperAgent Services]
    end
    
    GitHub --> Build
    Build --> Test
    Test --> Push
    Push --> Registry
    Registry --> Deploy
    Deploy --> K8s
    K8s --> Services

Loading

Code Examples & Patterns:

GitHub Actions Workflow Example:

name: Release Workflow

on:
  push:
    branches: [main]
    tags:
      - 'v*'

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Docker images
        run: |
          docker build -t hyperagent/orchestrator:${{ github.sha }} ./services/orchestrator
          docker build -t hyperagent/spec-agent:${{ github.sha }} ./services/agent-spec
      
      - name: Push to registry
        run: |
          docker push hyperagent/orchestrator:${{ github.sha }}
          docker push hyperagent/spec-agent:${{ github.sha }}
      
      - name: Deploy to staging
        run: |
          kubectl set image deployment/orchestrator \
            orchestrator=hyperagent/orchestrator:${{ github.sha }} \
            -n staging

---

⚠️ Layer 3: Constraint Analysis

What constraints and dependencies exist?

Known Dependencies:

• Docker registry must be configured (GHCR or AWS ECR)
• Kubernetes cluster must be available for staging
• Service Dockerfiles must exist
• Kubernetes manifests must be configured (see issue Configure K8s overlays for development environment #237)

Technical Constraints:

Scope limited to release workflow for staging environment. Production deployment tracked separately.

Current Blockers:

None identified (update as work progresses)

Risk Assessment & Mitigations:

Risk of failed deployments breaking staging. Mitigation: Implement health checks, automatic rollback on failure, staging environment isolation.

Resource Constraints:

• Deadline: Mar 3–16 (Sprint 3)
• Effort Estimate: M (Medium - 3-5 days)

---

💡 Layer 4: Solution Generation

How should this be implemented?

Solution Approach:

Implement GitHub Actions workflow:

1. Build Docker images for all services on push to main or version tags
2. Run tests before building
3. Tag images with commit SHA and version tags
4. Push images to container registry (GHCR or AWS ECR)
5. Deploy to staging Kubernetes cluster
6. Run health checks and smoke tests
7. Notify team on success/failure

Design Considerations:

• Follow established patterns from .cursor/skills/devops-engineer
• Maintain consistency with existing CI/CD configurations
• Consider build caching for faster builds
• Ensure proper image tagging and versioning
• Plan for testing and validation
• Support rollback on deployment failure

Acceptance Criteria (Solution Validation):

• Release workflow builds all service Docker images
• Images pushed to container registry successfully
• Automatic deployment to staging on main branch push
• Health checks and smoke tests run after deployment
• Rollback mechanism implemented
• Team notifications configured
• Documentation updated with workflow procedures
• Code reviewed and approved

---

📋 Layer 5: Execution Planning

What are the concrete steps?

Implementation Steps:

1. Configure container registry (GHCR or AWS ECR)
2. Create GitHub Actions workflow file
3. Configure Docker build steps for each service
4. Set up image tagging strategy
5. Configure registry push steps
6. Set up Kubernetes deployment steps
7. Implement health checks and smoke tests
8. Configure rollback mechanism
9. Set up team notifications
10. Test workflow end-to-end
11. Document workflow procedures
12. Code review and approval

Environment Setup:
Repos / Services:

• Infra / IaC repo: hyperagent/infra/
• Container registry: GHCR or AWS ECR
• Staging Kubernetes cluster

Required Environment Variables:

• DOCKER_REGISTRY= (Container registry URL)
• KUBECONFIG= (Kubernetes cluster configuration)
• REGISTRY_USERNAME= (Registry authentication)
• REGISTRY_PASSWORD= (Registry authentication)

Access & Credentials:

• Container registry access: GitHub secrets or AWS credentials
• Kubernetes cluster access: kubeconfig file
• Access request: Contact @devops or project lead

---

✅ Layer 6: Output Formatting & Validation

How do we ensure quality delivery?

Ownership & Collaboration:

• Owner: @JustineDevs
• Reviewer: @ArhonJay
• Access Request: @JustineDevs or @ArhonJay
• Deadline: Mar 3–16 (Sprint 3)
• Communication: Daily stand-up updates, GitHub issue comments

Quality Gates:

• Code follows project style guide (see .cursor/rules/rules.mdc)
• All tests pass (unit, integration, e2e)
• No critical lint/security issues
• Documentation updated (README, workflow docs)
• Meets all acceptance criteria from Layer 4
• Follows production standards (see .cursor/rules/production.mdc)

Review Checklist:

• Code review approved by @ArhonJay
• CI/CD pipeline passes (GitHub Actions)
• Release workflow tested and verified
• Security scan passes (no critical vulnerabilities)
• Documentation complete and accurate

Delivery Status:

• Initial Status: To Do
• Progress Tracking: Use issue comments for updates
• Sign-off: Approved by @Hyperionkit on [YYYY-MM-DD]
• PR Link: [Link to merged PR(s)]

Related Issues:

• Implement PR CI workflow (lint, tests, contract checks, static analysis) #231: Implement PR CI workflow (lint, tests, contract checks, static analysis)
• Configure canary deployments and basic SLOs for core services #233: Configure canary deployments and basic SLOs for core services
• Configure K8s overlays for development environment #237: Configure K8s overlays for development environment

Documentation References:

• Platform Blueprint
• System Architecture
• Execution Strategy
• Project Phases