{"id":35266553,"url":"https://github.com/emma-ola/envpromote-ecs","last_synced_at":"2026-05-06T04:03:35.185Z","repository":{"id":330423750,"uuid":"1122030299","full_name":"emma-ola/envpromote-ecs","owner":"emma-ola","description":"Reusable GitHub Actions CI/CD promotion pipeline for deploying containerized applications to Amazon ECS with environment gates, approvals, and immutable artifact promotion.","archived":false,"fork":false,"pushed_at":"2025-12-26T23:13:31.000Z","size":75,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-26T23:14:29.452Z","etag":null,"topics":["aws","ci-cd","devops","ecs","github-actions","infrastructure-as-code","platform-engineering","terraform"],"latest_commit_sha":null,"homepage":"","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emma-ola.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-24T01:43:30.000Z","updated_at":"2025-12-26T15:37:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/emma-ola/envpromote-ecs","commit_stats":null,"previous_names":["emma-ola/envpromote-ecs"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/emma-ola/envpromote-ecs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emma-ola%2Fenvpromote-ecs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emma-ola%2Fenvpromote-ecs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emma-ola%2Fenvpromote-ecs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emma-ola%2Fenvpromote-ecs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emma-ola","download_url":"https://codeload.github.com/emma-ola/envpromote-ecs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emma-ola%2Fenvpromote-ecs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32677933,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T02:33:58.958Z","status":"ssl_error","status_checked_at":"2026-05-06T02:33:39.611Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","ci-cd","devops","ecs","github-actions","infrastructure-as-code","platform-engineering","terraform"],"created_at":"2025-12-30T10:47:13.107Z","updated_at":"2026-05-06T04:03:35.178Z","avatar_url":"https://github.com/emma-ola.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EnvPromote ECS\n\nPromotion-based CI/CD for Amazon ECS using GitHub Actions, Terraform, and immutable artifacts\n\n## 📌 Overview\n\nEnvPromote ECS is a production-grade CI/CD system that demonstrates how to safely deploy containerized applications to Amazon ECS using immutable artifact promotion instead of environment-specific builds.\n\nThe system builds a container image once, pushes it to Amazon ECR, and promotes the same image digest across dev → staging → production using GitHub Actions, with approval gates, automated rollback, and full auditability.\n\nThis mirrors how engineering teams reduce deployment risk and eliminate configuration drift.\n\n## ❗ Problem / Context\n\nIn many teams, deployments suffer from:\n\n- environment-specific pipelines\n- manual promotion steps\n- rebuilding the same code for each environment\n- lack of clear release ownership\n- unsafe \"latest\" image deployments\n\nThese practices increase:\n\n- deployment risk\n- debugging time\n- production incidents\n- audit complexity\n\n## 🎯 Goals\n\n- Build once, deploy everywhere\n- Reduce human error in deployments\n- Enforce clear promotion gates\n- Make deployments deterministic and auditable\n- Use modern cloud-native best practices (OIDC, IaC, immutable images)\n\n## 💡 Solution Summary\n\nThis project implements a promotion-based CI/CD pipeline with the following characteristics:\n\n- Single build → image pushed to ECR\n- Promotion by image digest, not tag\n- Separate ECS services and task definition families per environment\n- GitHub Environments for scoped secrets and approvals\n- Reusable GitHub Actions workflows\n- Automatic rollback on failed health checks\n- Promotion history recorded per deployment\n\n## 🏗️ Architecture (High Level)\n\n**GitHub Actions**\n- CI build \u0026 push with security scanning\n- Reusable deploy workflow\n- Manual promotion workflows\n- Automated testing with Jest\n\n**Amazon ECR**\n- Single repository\n- Immutable image digests\n- Vulnerability scanning with Trivy\n\n**Amazon ECS (Fargate)**\n- Separate clusters/services per environment\n- Deployment circuit breaker enabled\n- Container Insights for enhanced monitoring\n- Graceful shutdown handling (SIGTERM/SIGINT)\n\n**Terraform**\n- Infrastructure as Code\n- Separate state per environment\n- Modular design for reusability\n\n**AWS IAM (OIDC)**\n- No long-lived AWS credentials\n\n**CloudWatch**\n- Environment-specific log groups\n- Automated alarms (CPU, memory, health, response time)\n- SNS integration for notifications\n\n**Slack Integration**\n- Real-time alarm notifications via AWS Chatbot\n- Environment-specific channels\n\n## 🧭 Deployment Flow\n\n1. Code is pushed to main\n2. CI builds a Docker image and pushes it to ECR\n3. Image is tagged with the commit SHA\n4. ECS dev deploys automatically\n5. Staging promotion is triggered manually\n6. Production promotion requires approval\n7. ECS rolls back automatically if health checks fail\n8. Each promotion generates a release record artifact\n\n## 🔐 Security Model\n\n- GitHub Actions authenticates to AWS using OIDC\n- Each environment has its own IAM role\n- No static AWS credentials\n- Production secrets are protected by approval gates\n\n## 🔁 Automatic Rollback\n\nEach ECS service is configured with:\n\n- Deployment circuit breaker\n- ALB health checks\n- Grace period for startup\n\nIf a new deployment fails:\n\n- ECS automatically rolls back to the last healthy task definition\n- CI detects the rollback and marks the deployment as failed\n\n## 📜 Promotion History\n\nEvery deployment writes a JSON promotion record and uploads it as a GitHub Actions artifact:\n\n```json\n{\n  \"timestamp_utc\": \"2025-01-02T14:32:01Z\",\n  \"environment\": \"production\",\n  \"digest\": \"sha256:...\",\n  \"image_uri\": \"repo@sha256:...\",\n  \"status\": \"success\",\n  \"run_id\": 123456\n}\n```\n\nThis provides:\n\n- traceability\n- audit history\n- easy rollback reference\n\n## 📂 Repository Structure\n\n```\n.github/workflows/\n  reusable-deploy-ecs.yml    # Reusable deployment workflow\n  dev.yml                    # Dev environment CI/CD\n  promote-staging.yml        # Staging promotion workflow\n  promote-production.yml     # Production promotion workflow\n  reuseable-build.yml        # Reusable build workflow with security scanning\n  ci.yml                     # CI checks (test, security audit)\n\napp/\n  ecs-taskdef.dev.json       # Dev task definition\n  ecs-taskdef.staging.json   # Staging task definition\n  ecs-taskdef.production.json # Production task definition\n  Dockerfile                 # Multi-stage optimized build\n  .dockerignore              # Docker build exclusions\n  src/                       # Application source code\n  tests/                     # Jest test suite\n  jest.config.js             # Jest configuration\n  jest.setup.js              # Jest test environment setup\n\ninfra/\n  bootstrap/\n    bootstrap-oidc/          # OIDC provider setup\n    us-east-1/               # State bucket\n  modules/\n    ecr/                     # ECR repository module\n    ecs-fargate-service/     # ECS service + ALB + CloudWatch alarms\n    github-oidc-role/        # IAM OIDC role module\n    sns-topic/               # SNS topic with KMS encryption\n  envs/\n    dev/                     # Dev environment config\n    staging/                 # Staging environment config\n    prod/                    # Production environment config\n\nREADME.md\n```\n\n## 🧪 Local Development\n\nRun the application locally without Docker:\n\n```bash\ncd app\nnpm install\nnpm test\nnpm run dev\n```\n\nService starts at:\n\n```\nhttp://localhost:3000\n```\n\nEndpoints:\n\n- `/` — service response\n- `/health` — ECS / ALB health check\n\n## 🐳 Docker Build (Local)\n\nBuild and run the same container used in CI/CD:\n\n```bash\ndocker build -t envpromote-ecs:local ./app\ndocker run -p 3000:3000 envpromote-ecs:local\n```\n\nContainer features:\n- Multi-stage build for optimized image size\n- Runs as non-root user for security\n- Graceful shutdown handling\n\n## 🧪 Testing\n\nRun the test suite with Jest:\n\n```bash\ncd app\nnpm test              # Run all tests\nnpm run test:watch    # Watch mode for development\nnpm run test:coverage # Generate coverage report\n```\n\nAll tests run in CI before deployment.\n\n## 🔒 Security Features\n\n**Container Security**\n- Multi-stage Docker builds\n- Non-root container user\n- Vulnerability scanning with Trivy in CI/CD\n- Regular npm security audits\n\n**Infrastructure Security**\n- OIDC authentication (no long-lived credentials)\n- KMS encryption for SNS topics\n- State locking to prevent concurrent modifications\n- IAM least-privilege policies\n\n**Monitoring \u0026 Alerting**\n- CloudWatch alarms for critical metrics\n- Real-time Slack notifications via AWS Chatbot\n- Container Insights for enhanced observability\n- Automatic health checks and rollback\n\n## 📊 CloudWatch Alarms\n\nEach environment includes the following alarms:\n\n- **High CPU Utilization** — triggers when CPU \u003e 80%\n- **High Memory Utilization** — triggers when memory \u003e 80%\n- **Unhealthy Target Count** — triggers when targets are unhealthy\n- **Low Running Task Count** — triggers when tasks \u003c desired count\n- **High Response Time** — triggers when response time \u003e 2 seconds\n\nAll alarms send notifications to environment-specific SNS topics, which can be routed to Slack via AWS Chatbot.\n\n## 🧠 Key Takeaways\n\n- CI should build artifacts; CD should promote them\n- Image digests eliminate environment drift\n- Production deployments should require intent and approval\n- Rollback must be automatic, not manual\n- Reusable workflows scale better than copy-paste pipelines\n- Security scanning and testing should be built into the pipeline\n- Monitoring and alerting are critical for production readiness\n- Infrastructure as Code enables reproducibility and consistency\n\n## 🚀 Why This Matters\n\nThis project demonstrates real-world DevOps practices:\n\n- **Promotion-based delivery** — build once, deploy everywhere\n- **Safe production releases** — automated testing, rollback, and approvals\n- **Auditability** — promotion history and deployment records\n- **Cloud-native security** — OIDC, encryption, least-privilege IAM\n- **Infrastructure as Code** — reproducible, version-controlled infrastructure\n- **Observability** — comprehensive monitoring, alerting, and logging\n- **Container best practices** — multi-stage builds, security scanning, graceful shutdown\n\n## 📚 Additional Documentation\n\n- [Infrastructure Setup Guide](infra/README.md) — Terraform deployment instructions\n- [GitHub Actions Workflows](.github/workflows/) — CI/CD pipeline configuration","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femma-ola%2Fenvpromote-ecs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femma-ola%2Fenvpromote-ecs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femma-ola%2Fenvpromote-ecs/lists"}