Skip to content

AWS DevOps (CodePipeline, CodeBuild, CodeDeploy, CodeArtifact, ECR)

Scope

AWS CI/CD and DevOps tooling. Covers CodePipeline (pipeline orchestration, cross-account deployment), CodeBuild (managed build environments, VPC access, caching), CodeDeploy (EC2/ECS/Lambda deployment strategies), CodeArtifact (package management), CodeCatalyst (unified developer experience), ECR (container registry, scanning, replication), Proton (service templates), App Runner (simplified container deployment), CDK Pipelines, and pipeline security patterns (IAM per stage, artifact signing, SLSA).

Checklist

  • [Critical] Design CodePipeline stage and action structure: source stage (CodeStar Connections for GitHub/Bitbucket, CodeCommit, S3, ECR), build stage (CodeBuild), deploy stage (CodeDeploy, CloudFormation, ECS, S3); use parallel actions within stages for independent tasks and sequential stages for promotion gates; configure manual approval actions between environments with SNS notifications
  • [Critical] Configure CodeBuild projects with least-privilege IAM: define buildspec.yml with phases (install, pre_build, build, post_build), use custom build environments (managed images or ECR-hosted custom images), enable VPC access for builds requiring private resources (RDS, ElastiCache, internal APIs), and configure compute types (BUILD_GENERAL1_SMALL through BUILD_GENERAL1_2XLARGE or Lambda compute for faster cold starts)
  • [Critical] Implement pipeline security with per-stage IAM roles: each pipeline stage should assume a dedicated IAM role with minimum required permissions; use cross-account roles for multi-account deployments (tooling account pipeline deploys to dev/staging/prod accounts); encrypt pipeline artifacts with KMS customer-managed keys; enable CloudTrail logging for all pipeline API calls
  • [Critical] Set up ECR with lifecycle policies and image scanning: configure lifecycle rules to expire untagged images and limit image count per repository; enable scan-on-push with Amazon Inspector for vulnerability detection (replaces legacy basic scanning); use immutable tags for production images to prevent tag overwriting; configure cross-account and cross-region replication for disaster recovery and multi-region deployments
  • [Recommended] Design CodeDeploy deployment strategies per compute platform: EC2/on-premises (in-place rolling or blue/green with Auto Scaling groups), ECS (blue/green with traffic shifting -- linear 10% every 1 minute, canary 10% then 90%, all-at-once), Lambda (canary, linear, all-at-once with alias traffic shifting); configure automatic rollback on deployment failure, CloudWatch alarm triggers, and lifecycle event hooks (BeforeInstall, AfterInstall, ValidateService)
  • [Recommended] Configure CodeBuild caching for build performance: local caching (Docker layer cache, source cache, custom cache -- persists on build host), S3 caching (dependency cache shared across builds -- node_modules, .m2, pip cache), or both; cache key based on lock file hash to invalidate on dependency changes; caching can reduce build times by 40-70% for dependency-heavy projects
  • [Recommended] Implement artifact signing and supply chain security: sign container images with cosign or AWS Signer, generate SBOMs (SPDX/CycloneDX) during build, use ECR image signing with Notation/cosign, configure IAM policies to enforce image provenance at deployment; target SLSA Level 2+ by ensuring build service authenticity and provenance generation
  • [Recommended] Set up CodeArtifact for package management: create domains for organizational isolation, configure repositories for npm, Maven (Java), Python (pip/twine), NuGet, Swift, and generic packages; set up upstream repositories to proxy public registries (npmjs.com, pypi.org, Maven Central) with automatic caching; use CodeArtifact authorization tokens in CodeBuild via buildspec commands (aws codeartifact get-authorization-token)
  • [Recommended] Design cross-account CI/CD pipeline architecture: tooling account hosts CodePipeline and CodeBuild, deployment accounts (dev/staging/prod) have cross-account IAM roles; use CodePipeline cross-account actions with assumed roles; store artifacts in a central S3 bucket with KMS encryption shared via key policy; use AWS Organizations SCPs to enforce pipeline-only deployment (prevent manual console changes)
  • [Recommended] Evaluate CDK Pipelines for infrastructure and application deployment: CDK Pipelines (aws-cdk-lib/pipelines) auto-generates a self-mutating CodePipeline from CDK code; supports wave-based parallel deployments across accounts and regions, automatic asset publishing (Docker images, Lambda bundles), and built-in conformance checks (ShellStep for validation); ideal for teams using CDK as their primary IaC tool
  • [Optional] Consider CodeCatalyst for unified developer experience: provides integrated IDE (Dev Environments with Cloud9 or VS Code), source repositories, CI/CD workflows (GitHub Actions-compatible syntax), issue tracking, and blueprints for project scaffolding; useful for greenfield projects wanting a single platform; evaluate maturity against established alternatives
  • [Optional] Evaluate Proton for platform engineering: define environment templates (shared infrastructure) and service templates (application deployment patterns) that development teams instantiate; supports CloudFormation or Terraform as template engines; useful for platform teams managing standardized deployment patterns across many application teams; overkill for small organizations
  • [Optional] Consider App Runner for simplified container or source deployments: automatic build and deploy from ECR images or source code (GitHub), managed scaling (including scale to zero), built-in load balancing and TLS; suitable for web APIs and microservices that do not require VPC-level networking control or custom deployment strategies; compare cost with ECS Fargate for sustained workloads

Why This Matters

AWS CI/CD service selection and pipeline architecture directly impact deployment velocity, security posture, and operational overhead. CodePipeline orchestrates multi-stage workflows but requires careful IAM design -- a common audit finding is overly permissive pipeline roles with AdministratorAccess that create a blast radius spanning the entire account. Cross-account pipeline architecture is essential for AWS Organizations environments, where a dedicated tooling account separates CI/CD infrastructure from workload accounts, enforcing the principle of least privilege at the account boundary.

CodeBuild eliminates the operational burden of managing build servers (no Jenkins controller patching, no agent fleet scaling), but default configurations often miss critical optimizations. Builds without caching re-download hundreds of megabytes of dependencies on every run. Builds without VPC access cannot reach private databases for integration testing. Builds using the default service role often have permissions far beyond what is needed.

ECR lifecycle policies are frequently neglected, leading to unbounded storage costs as every CI build pushes new images. A single busy repository can accumulate thousands of images costing hundreds of dollars monthly. Lifecycle policies that expire untagged images after 1 day and retain only the last N tagged images are a baseline requirement. Image scanning with Amazon Inspector (replacing the legacy basic scanner) provides CVE detection at push time, enabling quality gates that block deployment of images with critical vulnerabilities.

Supply chain security is an increasing concern. AWS Signer, cosign integration, and SBOM generation during build provide artifact provenance. Combined with ECR image scanning and IAM policies that restrict which images can be deployed (by tag pattern, account, or signing status), teams can establish verifiable trust from source commit to production deployment.

Common Decisions (ADR Triggers)

  • CodePipeline vs GitHub Actions vs GitLab CI -- CodePipeline provides native AWS integration (IAM roles, cross-account actions, CloudFormation deployment actions, ECS blue/green) and runs entirely within the AWS account boundary (no credentials leave AWS). GitHub Actions provides a richer ecosystem of community actions, simpler YAML syntax, native GitHub PR integration, and OIDC federation to AWS. GitLab CI provides built-in security scanning (SAST, DAST, container scanning) and a self-hosted option. Use CodePipeline for AWS-centric teams needing cross-account deployment orchestration without credentials leaving AWS. Use GitHub Actions for GitHub-native teams wanting community ecosystem and simpler configuration. Use GitLab CI for teams needing integrated DevSecOps scanning.
  • CodeBuild vs self-hosted runners (Jenkins, GitHub Actions self-hosted) -- CodeBuild is fully managed (no servers to patch or scale), supports VPC access for private resources, and scales to concurrent builds automatically. Self-hosted runners provide unlimited customization, persistent caches, and pre-installed tooling but require infrastructure management. Use CodeBuild for AWS-native pipelines wanting zero infrastructure management. Use self-hosted runners for complex build environments, existing Jenkins investments, or workloads requiring persistent GPU/specialized hardware.
  • CodeDeploy blue/green vs rolling vs ECS native deployment -- CodeDeploy blue/green for ECS creates a new task set, shifts traffic via ALB target groups (canary, linear, or all-at-once), and supports automatic rollback. ECS rolling update replaces tasks incrementally without CodeDeploy (simpler but no traffic shifting control). CodeDeploy for EC2 supports blue/green with Auto Scaling group replacement. Use CodeDeploy blue/green for ECS workloads needing canary or linear traffic shifting with automatic rollback. Use ECS rolling update for simpler services where basic health-check-based rollback is sufficient.
  • ECR vs third-party container registry (Docker Hub, GHCR, JFrog Artifactory) -- ECR provides native IAM integration, cross-account and cross-region replication, Amazon Inspector scanning, and no data transfer cost within the same region to ECS/EKS. Third-party registries may offer richer UI, multi-cloud support, or specific scanning features. Use ECR for AWS-centric deployments wanting native integration and zero cross-service data transfer cost. Use third-party registries for multi-cloud organizations or teams needing features ECR does not provide.
  • CodeArtifact vs self-hosted Nexus/Artifactory -- CodeArtifact is fully managed with upstream repository proxying, IAM-based access control, and no servers to manage. Self-hosted registries (Nexus, Artifactory) provide richer features (build promotion, property-based search, advanced retention policies, universal package support) but require infrastructure management. Use CodeArtifact for teams wanting managed package management integrated with IAM. Use self-hosted registries for organizations with complex artifact management requirements or existing investments.
  • CDK Pipelines vs custom CodePipeline vs Terraform-based pipelines -- CDK Pipelines auto-generates a self-mutating pipeline from CDK code, handles asset publishing, and supports multi-account wave deployments. Custom CodePipeline provides full control over stage and action configuration. Terraform-based pipelines use CodePipeline or GitHub Actions with Terraform plan/apply stages. Use CDK Pipelines for CDK-native projects wanting minimal pipeline configuration. Use custom CodePipeline for non-CDK projects or pipelines requiring actions CDK Pipelines does not support. Use Terraform pipelines for Terraform-based infrastructure deployment.
  • Monorepo vs polyrepo pipeline architecture -- Monorepo with CodePipeline requires multiple pipelines or complex source action filtering (EventBridge rules to trigger specific pipelines based on changed paths). Polyrepo uses one pipeline per repository with simpler trigger configuration. Monorepo enables atomic cross-service changes. Polyrepo provides independent release cycles. CodeBuild supports monorepo triggers with file path filters on webhook events. Consider GitHub Actions with path-based triggers as an alternative for monorepo CI.

See Also

  • general/ci-cd.md -- general CI/CD pipeline patterns, platform comparison, branching strategies
  • general/deployment.md -- deployment strategies (rolling, blue-green, canary) and rollback procedures
  • providers/aws/containers.md -- ECS, EKS, and ECR as deployment targets for container CI/CD
  • providers/aws/iam.md -- IAM role design for pipeline cross-account access and least-privilege policies
  • providers/aws/cdk.md -- CDK constructs and CDK Pipelines integration
  • providers/aws/cloudformation.md -- CloudFormation deployment actions in CodePipeline
  • providers/aws/secrets-manager.md -- secrets injection in CodeBuild and deployment pipelines