aws-deployment
aws/agent-toolkit-for-aws
Configure AWS CI/CD pipelines with CodePipeline, CodeBuild, CodeDeploy, and CodeArtifact.
What is aws-deployment?
Sets up end-to-end CI/CD pipelines on AWS using CodePipeline V2 orchestration, CodeBuild for builds, CodeDeploy for deployments with traffic-shifting strategies, and CodeArtifact for private package registries. Use this when configuring pipelines, buildspec.yml, deployment strategies, or cross-account deployments.
- Configures CodePipeline V2 with triggers, variables, execution modes, and cross-account support
- Writes and validates buildspec.yml with caching, VPC, and Docker configuration
- Sets up CodeDeploy strategies including blue/green, canary, and linear deployments
- Manages CodeArtifact private package registries with authentication and cross-account access
- Connects GitHub, GitLab, or Bitbucket via CodeConnections with OAuth
- Troubleshoots pipeline failures, build timeouts, and deployment issues
How to install aws-deployment
npx skills add https://github.com/aws/agent-toolkit-for-aws --skill aws-deployment- AWS account with CodePipeline, CodeBuild, CodeDeploy, and CodeArtifact services enabled
- AWS CLI or AWS MCP server for running commands
- GitHub, GitLab, or Bitbucket account for source connections (CodeConnections)
- IAM permissions for CodePipeline, CodeBuild, CodeDeploy, and CodeArtifact actions
How to use aws-deployment
- 1.Determine your pipeline architecture: source (CodeConnections) → build (CodeBuild) → deploy (CodeDeploy)
- 2.Create or authorize a CodeConnection to your Git repository; complete OAuth in AWS Console if status is PENDING
- 3.Write buildspec.yml with install, pre_build, build, and post_build phases; add runtime-versions for standard images
- 4.Configure CodeBuild project with VPC/NAT if needed, enable Docker privileged mode for container builds
- 5.Set up CodeDeploy application and deployment group with your chosen strategy (blue/green, canary, or linear)
- 6.Create CodePipeline with stages linking source → build → deploy; add cross-account role ARN if deploying to another account
- 7.Test the pipeline end-to-end; check troubleshooting guide if stuck at source, build timeout, or deployment failure
Use cases
- Deploy containerized applications from GitHub to ECS with blue/green traffic shifting
- Build and test Node.js/Python projects in CodeBuild with private npm/PyPI dependencies from CodeArtifact
- Set up cross-account deployments with KMS encryption and S3 artifact sharing
- Configure canary deployments for Lambda functions with automatic rollback on alarm
- Unblock pending CodeConnections by completing OAuth flow in AWS Console
- DevOps engineers setting up CI/CD pipelines
- Backend developers configuring automated deployments
- Platform teams managing cross-account infrastructure
- AWS practitioners troubleshooting pipeline and build failures
aws-deployment FAQ
CodeConnections created via CLI or CloudFormation require OAuth completion in the AWS Console. There is no API-only path; you must manually authorize in the console.
All three are required: (1) KMS key policy granting the target account, (2) S3 bucket policy for the target account, (3) cross-account IAM role with trust policy. Missing any one causes Access Denied errors.
If your build runs in a VPC without a NAT gateway, it cannot reach the internet. Add a NAT gateway to your private subnets or use VPC endpoints.
Make ApplicationStop scripts idempotent (exit 0 if the service is absent). If already blocked, use `--ignore-application-stop-failures` to unblock.
V2 is the default and recommended type, with improved triggers, variables, and execution modes (QUEUED for sequential, PARALLEL for independent executions).
Full instructions (SKILL.md)
Source of truth, from aws/agent-toolkit-for-aws.
name: aws-deployment description: "Configures CI/CD pipelines using AWS CodePipeline, CodeBuild, CodeDeploy, CodeConnections, and CodeArtifact. Covers CodePipeline V2 (triggers, variables, execution modes, cross-account), buildspec.yml (caching, VPC, Docker), CodeDeploy strategies (blue/green, canary, linear), CodeArtifact (private package registries, auth tokens, cross-account), and source connections (GitHub, GitLab, Bitbucket). Applies when CodePipeline, CodeBuild, CodeDeploy, CodeConnections, CodeArtifact, buildspec.yml, appspec.yml, or CI/CD pipeline orchestration is referenced. Does NOT cover: ECS Fargate services or task definitions (use aws-containers), CDK Pipelines or cdk deploy (use aws-cdk), sam deploy (use aws-serverless), Amplify deployments (use aws-amplify), or GitHub Actions/GitLab CI." metadata: version: "1"
AWS Deploy (CI/CD)
Works best with the AWS MCP server for running CLI commands and validating configurations directly. All guidance also works with standard AWS CLI.
Critical Warnings
CodeConnections PENDING trap: Connections created via CLI/CloudFormation remain PENDING indefinitely — MUST complete OAuth in the AWS Console. No API-only path exists.
Cross-account triple requirement: Cross-account deploys need ALL THREE: (1) KMS key policy granting target account (use key ID, not alias), (2) S3 bucket policy for target account, (3) cross-account IAM role with trust policy. Missing any one = cryptic Access Denied.
CodeDeploy ApplicationStop uses PREVIOUS revision: Broken stop scripts in a prior deployment block ALL future deploys. Make stop scripts idempotent (exit 0 if service absent). Unblock with --ignore-application-stop-failures.
CodeBuild VPC without NAT: Builds in VPC subnets without NAT gateway hang at DOWNLOAD_SOURCE silently. Private subnets MUST have NAT gateway or VPC endpoints.
CodeConnections IAM: Use codeconnections: prefix for API calls and IAM policy Actions. Resource ARNs must match exactly — new resources use codeconnections prefix, existing resources may use codestar-connections prefix. Specify both in Resource if you have mixed-age resources.
UseConnection is over-permissive: codeconnections:UseConnection grants access to ALL repositories the connection can reach. MUST specify condition keys (codeconnections:FullRepositoryId, codeconnections:ProviderAction, codeconnections:BranchName) to limit CodeBuild to only the required repository.
How These Services Compose
CodeConnections → CodeBuild → CodeDeploy, orchestrated by CodePipeline.
| Layer | Service | Role |
|---|---|---|
| Source | CodeConnections | Authenticates to GitHub/GitLab/Bitbucket, delivers code |
| Packages | CodeArtifact | Private package registry, dependency caching from public registries |
| Build/Test | CodeBuild | Compiles, tests, packages artifacts |
| Deploy | CodeDeploy | Deploys to EC2/ECS/Lambda with traffic shifting strategies |
| Orchestrator | CodePipeline | Chains stages, manages transitions, approval gates |
Default: V2 pipeline type with QUEUED execution mode. Use PARALLEL only when executions are fully independent.
Quick Navigation
| You want to... | Go to |
|---|---|
| Create a pipeline (V2, triggers, variables, modes) | codepipeline.md |
| Connect GitHub/GitLab/Bitbucket source | codeconnections.md |
| Write buildspec.yml / configure builds | codebuild.md |
| Set up private package registry for builds | codeartifact.md |
| Configure deployment strategy (blue/green, canary) | codedeploy.md |
| Cross-account or cross-region deployment | codepipeline.md |
| Fix failing pipeline, build, or deployment | troubleshooting.md |
Common Workflows
| Task | Action | Reference |
|---|---|---|
| Pipeline from GitHub to ECS | Create connection → CodeBuild Docker stage → CodeDeploy ECS blue/green | codepipeline, codedeploy |
| Pipeline stuck at source | Check connection status; if PENDING, complete OAuth in AWS Console | troubleshooting |
| Build timing out | Check VPC/NAT, increase timeoutInMinutes, verify Docker privileged mode | codebuild |
| Deploy to another account | Configure KMS + S3 bucket policy + cross-account role, add RoleArn to action | codepipeline |
| Roll back failed deployment | Auto-rollback on alarm/failure; manual: stop-deployment --auto-rollback-enabled | codedeploy |
| Lambda canary deployment | CodeBuild packages → CodeDeploy Lambda with canary traffic shifting | codedeploy |
Troubleshooting
| Error/Symptom | Cause | Fix |
|---|---|---|
YAML_FILE_ERROR in CodeBuild | Missing or malformed runtime-versions in buildspec (recommended for standard images) | Add runtime-versions block in install phase |
file already exists on CodeDeploy | Redeployment without overwrite config | Set file_exists_behavior: OVERWRITE |
| Pipeline trigger not firing | File path filter checks only first 100 files in diff | Reduce path filter scope or merge smaller |
| PARALLEL mode wrong revision | Race between event and source action | Use QUEUED mode for sequential consistency |
Docker: Cannot connect to daemon | Missing privileged mode | Set privilegedMode: true AND start dockerd in buildspec |
CODEBUILD_CLONE_REF permission error | CodeBuild role missing UseConnection | Add codeconnections:UseConnection to CodeBuild service role |
| Deployment never completes | MinimumHealthyHosts too high for instance count | Ensure healthy threshold < total instances |
| ECS deployment stuck | Health check failing on new task set | Verify target group health check path/port |
Security
- MUST store secrets in Secrets Manager or Parameter Store; reference via CodeBuild
type: SECRETS_MANAGER— MUST NOT embed in buildspec as PLAINTEXT - MUST use customer-managed KMS keys for cross-account artifact encryption (default encryption does not support cross-account)
- SHOULD scope CodeBuild/CodeDeploy service roles to specific resource ARNs; MUST NOT use
*fors3:GetObjectorkms:Decrypt - MUST use CodeConnections (not personal access tokens) for source connections; OAuth tokens cannot be rotated automatically
- See CodePipeline security best practices for comprehensive guidance
Not Covered
| Topic | Use instead |
|---|---|
CDK Pipelines (aws-cdk-lib/pipelines) | aws-cdk |
sam deploy / SAM CLI | aws-serverless |
| ECS service deployment config (circuit breaker, rolling params) | aws-containers |
| GitHub Actions / GitLab CI | Third-party tools, not covered |
Related skills
More from aws/agent-toolkit-for-aws and the wider catalog.
aws-iam
Verified IAM corrections and workflows for role management, policy generation, and edge-case handling.
aws-lambda-durable-functions
Build resilient multi-step AWS Lambda workflows that run for up to 1 year with automatic state persistence and replay-safe orchestration.
aws-lambda-managed-instances
Evaluate, configure, and migrate workloads to AWS Lambda Managed Instances for long-running, steady-traffic jobs with EC2 pricing and AWS-managed infrastructure.
aws-lambda-microvms
Build, run, and debug long-lived serverless applications on AWS Lambda MicroVMs with Firecracker isolation and snapshot-based resumption.
aws-messaging-and-streaming
Route AWS messaging and streaming questions to the right service—SQS, SNS, EventBridge, Kinesis, Kafka, and customer communication channels.
aws-network-monitoring
Install and troubleshoot CloudWatch Network Flow Monitor agents on EC2 instances to track network path health.