AWS CI/CD Pipeline: Complete Guide to Building Deployment Pipelines on AWS
DevOps / SRE Engineer & CEO, Cloud DevOps Solutions
Every team deploying to AWS needs a CI/CD pipeline. The question is not whether to automate deployments, but which tools to use and how to wire them together. AWS offers its own CI/CD services (CodePipeline, CodeBuild, CodeDeploy), but most teams also consider GitHub Actions, GitLab CI, or Jenkins because that is where their source code already lives.
This guide covers the three most common approaches to building CI/CD pipelines on AWS, compares their strengths and trade-offs, and walks through architecture patterns for deploying to ECS, EKS, Lambda, and EC2.
AWS-native CI/CD: CodePipeline, CodeBuild, and CodeDeploy
AWS provides a suite of CI/CD services that integrate tightly with each other and with AWS deployment targets.
CodePipeline
CodePipeline is the orchestration layer. It defines the stages of your pipeline (source, build, test, deploy) and connects them. Key characteristics:
- Source integrations: CodeCommit, GitHub (via CodeStar Connections), Bitbucket, S3
- Stage model: sequential stages with parallel actions within each stage
- Approval gates: manual approval actions for production deployments
- Pricing: $1 per active pipeline per month (free tier: 1 pipeline)
CodeBuild
CodeBuild runs your build and test commands in managed containers. You define a buildspec.yml file that specifies the build commands, environment, and artifacts.
version: 0.2
phases:
pre_build:
commands:
- echo Logging in to ECR...
- aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $ECR_REPO
build:
commands:
- echo Building Docker image...
- docker build -t $ECR_REPO:$CODEBUILD_RESOLVED_SOURCE_VERSION .
- docker push $ECR_REPO:$CODEBUILD_RESOLVED_SOURCE_VERSION
post_build:
commands:
- echo Writing image definition...
- printf '[{"name":"app","imageUri":"%s"}]' $ECR_REPO:$CODEBUILD_RESOLVED_SOURCE_VERSION > imagedefinitions.json
artifacts:
files:
- imagedefinitions.json
Key features:
- Managed compute (no build servers to maintain)
- Docker layer caching for faster builds
- VPC connectivity for accessing private resources during builds
- Multiple compute types including ARM (Graviton) and GPU
- Pricing: $0.005 per build minute (general1.small Linux), free tier: 100 build minutes/month
CodeDeploy
CodeDeploy handles the deployment itself with support for different strategies:
- In-place deployment: updates instances sequentially (EC2, on-premises)
- Blue/green deployment: launches new instances, shifts traffic, terminates old ones (EC2, ECS)
- Canary and linear deployment: gradually shifts traffic percentages (ECS, Lambda)
CodeDeploy is free. You pay only for the underlying compute.
When AWS-native works best
The AWS-native stack is a good fit when:
- Your source code is in CodeCommit (rare) or you want minimal external dependencies
- You need tight integration with AWS deployment targets (ECS blue/green, Lambda canary)
- Compliance requires keeping all CI/CD activity within AWS
- You want to use AWS-native IAM for all pipeline permissions without external OIDC setup
When it falls short
- Developer experience: CodePipeline’s UI and debugging tools lag behind GitHub Actions and GitLab CI
- Pipeline-as-code maturity:
buildspec.ymlworks but lacks the ecosystem of reusable actions/templates that GitHub and GitLab offer - Source code integration: most teams use GitHub or GitLab, not CodeCommit. The CodeStar connection works but adds a layer of configuration.
- Community: fewer examples, templates, and community support compared to GitHub Actions
GitHub Actions with AWS
GitHub Actions is the most popular CI/CD tool for teams using GitHub. For AWS deployments, the combination of GitHub Actions with OIDC authentication provides a secure, maintainable pipeline.
OIDC authentication (no long-lived credentials)
The critical setup: configure GitHub as an OIDC identity provider in AWS IAM so that GitHub Actions workflows assume an IAM role without storing AWS access keys.
name: Deploy to ECS
on:
push:
branches: [main]
permissions:
id-token: write
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
aws-region: us-east-1
- name: Login to ECR
id: ecr-login
uses: aws-actions/amazon-ecr-login@v2
- name: Build and push image
env:
ECR_REGISTRY: ${{ steps.ecr-login.outputs.registry }}
IMAGE_TAG: ${{ github.sha }}
run: |
docker build -t $ECR_REGISTRY/myapp:$IMAGE_TAG .
docker push $ECR_REGISTRY/myapp:$IMAGE_TAG
- name: Deploy to ECS
uses: aws-actions/amazon-ecs-deploy-task-definition@v2
with:
task-definition: task-definition.json
service: myapp-service
cluster: production
wait-for-service-stability: true
Why OIDC matters
With OIDC, GitHub Actions workflows request short-lived credentials from AWS STS. No AWS access keys are stored in GitHub Secrets. This eliminates key rotation burden and reduces the blast radius of a compromised repository.
The IAM role’s trust policy restricts which repositories, branches, and environments can assume it:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
},
"StringLike": {
"token.actions.githubusercontent.com:sub": "repo:myorg/myrepo:ref:refs/heads/main"
}
}
}
]
}
GitHub Actions strengths for AWS
- Marketplace: thousands of pre-built actions, including official AWS actions for ECR, ECS, EKS, Lambda, S3, and CloudFormation
- Reusable workflows: define a deployment workflow once and call it from multiple repositories
- Environments: environment-level protection rules (required reviewers, wait timers) for production deployments
- Self-hosted runners: run builds inside your VPC on your own EC2 instances or EKS pods for private resource access
- Matrix builds: test across multiple runtime versions or configurations in parallel
GitHub Actions limitations
- Pricing: GitHub-hosted runners cost $0.008/minute (Linux). Self-hosted runners avoid this but require infrastructure management.
- Long-running workflows: 6-hour timeout per job, which can be a constraint for large builds or integration test suites
- No native blue/green for ECS: the
amazon-ecs-deploy-task-definitionaction does a rolling update. For blue/green, you need CodeDeploy as the deployment controller (GitHub Actions triggers it).
For a detailed migration guide, see our post on migrating from Jenkins to GitHub Actions.
GitLab CI with AWS
GitLab CI is built into GitLab and uses .gitlab-ci.yml for pipeline definitions. For AWS deployments, GitLab provides OIDC integration similar to GitHub Actions.
Pipeline structure
stages:
- test
- build
- deploy-staging
- deploy-production
variables:
ECR_REPO: 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp
test:
stage: test
image: node:20
script:
- npm ci
- npm test
build:
stage: build
image: docker:24
services:
- docker:24-dind
id_tokens:
AWS_TOKEN:
aud: https://gitlab.com
before_script:
- apk add --no-cache aws-cli
- >
export $(printf "AWS_ACCESS_KEY_ID=%s AWS_SECRET_ACCESS_KEY=%s AWS_SESSION_TOKEN=%s"
$(aws sts assume-role-with-web-identity
--role-arn $AWS_ROLE_ARN
--role-session-name gitlab-ci
--web-identity-token $AWS_TOKEN
--duration-seconds 3600
--query "Credentials.[AccessKeyId,SecretAccessKey,SessionToken]"
--output text))
script:
- aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $ECR_REPO
- docker build -t $ECR_REPO:$CI_COMMIT_SHA .
- docker push $ECR_REPO:$CI_COMMIT_SHA
deploy-staging:
stage: deploy-staging
script:
- aws ecs update-service --cluster staging --service myapp --force-new-deployment
environment:
name: staging
deploy-production:
stage: deploy-production
script:
- aws ecs update-service --cluster production --service myapp --force-new-deployment
environment:
name: production
when: manual
GitLab CI strengths for AWS
- Built-in container registry: no ECR setup needed for intermediate images
- Auto DevOps: pre-configured pipelines for common patterns (detect, build, test, deploy)
- Security scanning: SAST, DAST, dependency scanning, and container scanning built into the platform
- Environments with review apps: automatic per-branch deployments for feature review
- Kubernetes integration: native cluster management and Helm/Kustomize deployment support
GitLab CI limitations
- Runner management: GitLab.com shared runners are limited; production pipelines typically need self-managed runners on EC2 or EKS
- AWS integration: less polished than GitHub Actions. Fewer pre-built templates for AWS services.
- OIDC setup: more manual than GitHub’s implementation (no equivalent of
aws-actions/configure-aws-credentials)
Choosing between the three
| Dimension | AWS CodePipeline | GitHub Actions | GitLab CI |
|---|---|---|---|
| Source code home | CodeCommit (or GitHub/Bitbucket via connector) | GitHub | GitLab |
| Setup complexity | Medium (multiple AWS services to configure) | Low (YAML in repo) | Low (YAML in repo) |
| ECS blue/green | Native (via CodeDeploy) | Requires CodeDeploy trigger | Requires CodeDeploy trigger |
| EKS deployment | Via CodeBuild + kubectl/Helm | Via actions + kubectl/Helm | Via runners + kubectl/Helm |
| Lambda deployment | Native (via CodeDeploy canary/linear) | Via SAM/CDK actions | Via SAM/CDK scripts |
| OIDC (no stored keys) | N/A (runs in AWS) | Native support | Supported (manual setup) |
| Security scanning | Requires third-party tools | Dependabot + marketplace actions | Built-in SAST, DAST, container scan |
| Pricing | $1/pipeline + CodeBuild minutes | $0.008/min (hosted) or self-hosted | Free tier + $0.005/min (hosted) or self-hosted |
| Community/ecosystem | Small | Largest | Large |
| Best for | All-AWS shops, compliance | GitHub-native teams | GitLab-native teams, security-first |
Our recommendation: use the CI/CD tool where your source code lives. GitHub teams should use GitHub Actions. GitLab teams should use GitLab CI. Use AWS CodePipeline only when you need native ECS blue/green or Lambda canary deployments, or when compliance requires all pipeline activity within AWS. In many cases, the best approach is a hybrid: GitHub Actions for build and test, with CodeDeploy handling the deployment strategy.
Architecture patterns for AWS deployments
Pattern 1: Container deployment to ECS
GitHub push → Build image → Push to ECR → Update ECS task definition → ECS rolling update
This is the simplest pattern. The CI tool builds a Docker image, pushes it to ECR, and updates the ECS service to use the new image. ECS handles the rolling deployment.
For zero-downtime deployments, ensure:
- Health checks are configured on the target group
- Deregistration delay is set (default 300s, reduce to 30-60s for faster deployments)
- The container handles SIGTERM gracefully (stops accepting new requests, completes in-flight requests)
Pattern 2: ECS blue/green with CodeDeploy
GitHub push → Build image → Push to ECR → Update task def → CodeDeploy blue/green → Traffic shift
CodeDeploy creates a new task set (green), validates it with health checks, then shifts ALB traffic. If the green deployment fails health checks, CodeDeploy rolls back automatically.
This pattern requires:
- An Application Load Balancer with two target groups (blue and green)
- A CodeDeploy application and deployment group configured for ECS
- An
appspec.ymldefining the task definition and container port
Pattern 3: Kubernetes deployment to EKS
GitHub push → Build image → Push to ECR → Helm upgrade / kubectl apply → ArgoCD sync
Two approaches:
Push-based (CI deploys directly):
The CI pipeline runs helm upgrade or kubectl apply against the EKS cluster. Simple but requires the CI tool to have cluster credentials.
GitOps (CI updates manifests, ArgoCD deploys): The CI pipeline updates the image tag in a Git repository. ArgoCD detects the change and syncs the cluster. More secure because CI never needs cluster credentials, and ArgoCD provides drift detection and rollback.
For teams adopting GitOps, we recommend the ArgoCD pattern. See our ArgoCD on EKS tutorial for a step-by-step walkthrough.
Pattern 4: Lambda deployment with SAM or CDK
GitHub push → SAM build → SAM deploy → Lambda version published → Alias shifted (canary/linear)
AWS SAM (Serverless Application Model) or CDK handles Lambda deployments. For production, configure gradual deployment preferences:
- Canary10Percent5Minutes: shifts 10% of traffic to the new version, waits 5 minutes, then shifts the rest
- Linear10PercentEvery1Minute: shifts traffic in 10% increments every minute
- AllAtOnce: immediate shift (use for non-critical functions)
SAM integrates with CodeDeploy for these traffic-shifting strategies. CloudWatch alarms can trigger automatic rollback if error rates spike.
Pattern 5: Infrastructure deployment with Terraform
GitHub push → Terraform plan → Manual approval → Terraform apply
Infrastructure changes need a different pipeline pattern:
- Plan in CI:
terraform planruns on every pull request, with the plan output posted as a PR comment - Review: a human reviews the plan diff
- Apply on merge:
terraform applyruns after the PR is merged to main - State locking: use S3 backend with DynamoDB for state locking to prevent concurrent applies
Infracost adds cost estimation to the plan output, showing the financial impact of infrastructure changes before they are applied.
Secrets management in pipelines
Secrets (database credentials, API keys, third-party tokens) must never be hardcoded in pipeline definitions or source code.
AWS Secrets Manager
Store secrets in AWS Secrets Manager and retrieve them at build or deploy time:
# In a CodeBuild buildspec or GitHub Actions step
DB_PASSWORD=$(aws secretsmanager get-secret-value \
--secret-id prod/myapp/db \
--query SecretString --output text | jq -r .password)
GitHub Actions secrets
GitHub encrypts secrets at rest and masks them in logs. For AWS deployments, use OIDC instead of storing AWS credentials as secrets. Store only non-AWS secrets (third-party API keys, signing certificates) in GitHub Secrets.
Parameter Store
For non-sensitive configuration (feature flags, endpoint URLs, version numbers), use AWS Systems Manager Parameter Store. It is free for standard parameters and integrates with ECS task definitions and Lambda environment variables.
Monitoring and observability for pipelines
A pipeline that fails silently is worse than no pipeline.
Build metrics
Track these metrics across all pipelines:
- Deployment frequency: how often you deploy to production (DORA metric)
- Lead time for changes: time from commit to production (DORA metric)
- Change failure rate: percentage of deployments that cause incidents (DORA metric)
- Mean time to recovery: how quickly you recover from a failed deployment (DORA metric)
- Build duration: trend over time to catch regressions
- Build success rate: broken builds should be fixed immediately, not normalised
Notifications
Route pipeline status to your team’s communication channel:
- GitHub Actions: use the
slackapi/slack-github-actionfor Slack notifications - GitLab CI: configure webhook notifications or use the Slack integration
- CodePipeline: route state change events via EventBridge to SNS, Slack, or PagerDuty
Deployment tracking
Tag every deployment with the commit SHA, pipeline run ID, and timestamp. This makes it possible to correlate application behaviour with specific deployments when debugging production issues.
Cost comparison
CI/CD costs are often overlooked. Here is a realistic comparison for a team running 100 builds per day at 5 minutes each:
| Tool | Monthly compute cost | Notes |
|---|---|---|
| CodeBuild (general1.small) | ~$75 | 500 build-minutes/day x 30 days x $0.005 |
| GitHub Actions (hosted) | ~$120 | 500 min/day x 30 x $0.008 |
| GitLab CI (SaaS, Linux) | ~$75 | 500 min/day x 30 x $0.005 |
| Self-hosted (t3.medium) | ~$30 | 1 runner on-demand, but add management overhead |
| Self-hosted (Spot) | ~$10 | Same runner on Spot, but handle interruptions |
Self-hosted runners are cheapest but require maintenance. For most teams, the managed option is worth the premium. Use Spot-based self-hosted runners (on EC2 or EKS) for build-heavy teams that want the cost benefit without full infrastructure management.
Production best practices
Pin action/image versions
Never use latest tags in pipeline definitions. Pin to specific versions:
# Good
- uses: actions/[email protected]
- image: node:20.11.1
# Risky
- uses: actions/checkout@main
- image: node:latest
Unpinned versions break builds without warning and introduce supply chain risks.
Separate build and deploy
Keep build (compile, test, package) and deploy (push to target) as separate stages. This allows:
- Redeploying a previous build artifact without rebuilding
- Different IAM permissions per stage (build needs ECR push, deploy needs ECS update)
- Manual approval gates between build and production deploy
Use environments for promotion
Define a promotion path: dev, staging, production. Each environment has its own:
- AWS account (or at minimum, separate IAM roles)
- Deployment configuration
- Approval requirements (none for dev, automatic for staging, manual for production)
Cache aggressively
Docker layer caching, dependency caching (node_modules, .m2, pip cache), and build artifact caching reduce build times by 50-80%. Every CI tool supports caching; configure it from day one.
Scan before deploying
Integrate security scanning into the pipeline:
- Dependency scanning: Dependabot (GitHub),
npm audit, Trivy - Container scanning: Trivy, Snyk Container, ECR image scanning
- Infrastructure scanning: tfsec, checkov, or Snyk IaC for Terraform
- SAST: CodeQL (GitHub), Semgrep, SonarQube
Block deployments that introduce critical or high-severity vulnerabilities. See our CI/CD pipeline best practices guide for more detail.
Key takeaways
- Use the CI/CD tool where your source code lives: GitHub Actions for GitHub, GitLab CI for GitLab
- AWS CodePipeline adds value when you need native ECS blue/green or Lambda canary deployments
- Always use OIDC for AWS authentication in external CI tools, never store long-lived AWS credentials
- For Kubernetes on EKS, the GitOps pattern (CI updates Git, ArgoCD deploys) is more secure than CI pushing directly to the cluster
- Separate build and deploy stages, use environments for promotion, and require manual approval for production
- Pin all action and image versions to prevent supply chain surprises
- Monitor pipeline health with DORA metrics and route failures to your team channel
Need help designing a CI/CD pipeline for your AWS environment? Book a free consultation and we will review your deployment workflow together.
Related service
Need hands-on help? Our certified engineers deliver this as a managed service.
CI/CD Pipeline Services