AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides guidance on configuring and managing end-to-end CI/CD pipelines within the AWS ecosystem. It covers the integration of source control connections, build environments, package management, and deployment strategies. The content focuses on service orchestration, security best practices, and troubleshooting common infrastructure-level failures in build and deployment processes.
What it does
- Configures CI/CD pipelines using CodePipeline and CodeConnections.
- Defines build environments and buildspec logic for CodeBuild.
- Manages private package registries via CodeArtifact.
- Implements deployment strategies like blue/green, canary, and linear using CodeDeploy.
- Provides troubleshooting steps for pipeline, build, and deployment failures.
- Details security configurations for service roles and cross-account access.
When to use it
- When setting up automated build and deployment pipelines on AWS.
- When integrating external source providers like GitHub, GitLab, or Bitbucket.
- When managing private dependencies for build processes.
- When implementing traffic shifting strategies for application updates.
- When debugging pipeline stalls or deployment errors.
Advantages
- Native integration with AWS security and IAM policies.
- Supports complex deployment patterns like blue/green and canary.
- Enables secure cross-account artifact management.
- Provides centralized control over build and deployment phases.
Usage examples
- “How do I set up a pipeline that pulls from GitHub and deploys to ECS?”
- The agent provides a sequence to create a connection, configure a build stage for container packaging, and set up a deployment stage using blue/green traffic shifting.
- “My CodeBuild project is hanging at the download source phase.”
- The agent identifies the likely cause as a VPC configuration issue and suggests verifying the presence of a NAT gateway in the private subnets.
- “How can I share packages across different AWS accounts?”
- The agent explains how to configure CodeArtifact domain policies and use customer-managed KMS keys to enable cross-account access.
- “How do I handle a failed deployment in CodeDeploy?”
- The agent outlines how to use automated rollback settings or manual commands to stop and revert the deployment.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/aws/aws-deployment/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip aws-deployment.zip -d .agents/skills
Documentation by AWS
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 PLAINTEXTMUST 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:DecryptMUST 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 |
Files
- ATTRIBUTION.mdAdded by AutoGineer893 B
- LICENSELicence file added by AutoGineer9.9 KiB
- NOTICELicence file added by AutoGineer67 B
- SKILL.md7.0 KiB
- references/codeartifact.md6.4 KiB
- references/codebuild.md7.3 KiB
- references/codeconnections.md6.8 KiB
- references/codedeploy.md10.4 KiB
- references/codepipeline.md10.3 KiB
- references/troubleshooting.md7.9 KiB
references/troubleshooting.md
Troubleshooting
First Check These 5 Things
Connection status:
aws codeconnections get-connection --connection-arn ARN— if PENDING, complete OAuth in consolePipeline state:
aws codepipeline get-pipeline-state --name NAME— find which action failed and whyBuild logs:
aws codebuild batch-get-builds --ids BUILD_ID— checkphasesarray for first failed phaseDeployment status:
aws deploy get-deployment --deployment-id ID— checkdeploymentOverviewanderrorInformationService role permissions:
aws iam simulate-principal-policy --policy-source-arn ROLE_ARN --action-names ACTION— verify IAM
Error Table
CodePipeline
| Error/Symptom | Cause | Fix |
|---|---|---|
InternalError on action | Artifact bucket wrong region or KMS permission denied | Ensure S3 bucket same region as pipeline; check KMS key policy |
ActionConfigurationError | Referenced resource deleted (CodeBuild project, deployment group) | Verify all resource names in action config still exist |
AccessDeniedException on action | Service role missing permissions for the action's provider | Add required permissions to pipeline service role |
| Pipeline stuck InProgress | Disabled transition, waiting approval, or slow action | Check get-pipeline-state for actionStates; look for PENDING approval |
PipelineExecutionNotStoppableException | Execution in terminal state (Succeeded/Failed) | Already finished — no action needed |
InvalidStructureException on create/update | Malformed pipeline JSON | Validate JSON; check all required fields per action type |
StageNotRetryableException | Stage not in Failed state | Only failed stages can be retried |
RevisionOutOfSyncException | PARALLEL mode race between executions | Use QUEUED mode for sequential consistency |
| Trigger fires on unrelated changes | File path filter skipped (>100 files in commit) | Add branch filter as primary gate |
| Trigger never fires | sourceActionName mismatch or connection PENDING | Verify trigger config matches source action name exactly |
AccessDenied on cross-account action | Missing KMS/S3/IAM trust (need all three) | Verify: KMS key policy, S3 bucket policy, target role trust policy |
CodeBuild
| Error/Symptom | Cause | Fix |
|---|---|---|
DOWNLOAD_SOURCE failure | VPC without NAT, connection PENDING, or repo not found | Check VPC NAT gateway; verify connection AVAILABLE; check repo access |
YAML_FILE_ERROR | Missing runtime-versions, bad YAML syntax, or wrong filename | Add runtime-versions block; validate YAML; file must be buildspec.yml at root |
| Build hangs indefinitely | VPC subnet without NAT gateway or S3 endpoint | Add NAT gateway to private subnet route table |
Cannot connect to Docker daemon | Privileged mode not enabled or dockerd not started | Set privilegedMode=true AND start dockerd in pre_build phase |
BUILD_GENERAL1_SMALL not available | Compute type not available in region or quota reached | Try different compute type or request quota increase |
| Build timeout (default 60 min) | Long-running build or hanging dependency download | Increase timeoutInMinutes; check for network issues (VPC) |
CODEBUILD_CLONE_REF permission error | CodeBuild role missing UseConnection | Add codeconnections:UseConnection to CodeBuild service role (not pipeline role) |
CLIENT_ERROR: unable to locate credentials | Service role insufficient for operation | Check CodeBuild service role has needed permissions |
| Artifacts not found by next stage | base-directory wrong or files pattern too restrictive | Verify artifacts.base-directory matches build output location |
CodeDeploy
| Error/Symptom | Cause | Fix |
|---|---|---|
| "no instances were found" | Tag filters match zero instances or agent not running | Verify EC2 tags; check codedeploy-agent status on instances |
| "specified key does not exist" | S3 revision artifact location wrong | Verify S3 path matches revision location in create-deployment |
ApplicationStop fails every deploy | Previous revision's stop script is broken | Deploy fix-only revision or use --ignore-application-stop-failures |
| "file already exists at this location" | file_exists_behavior not set | Set OVERWRITE in deployment or appspec files.overwrite: true |
InstanceLimitExceeded | ASG scaling faster than deployment completes | Suspend ASG Launch process, fix deployment, resume |
| "agent was not able to receive the lifecycle event" | Agent not running or network timeout | SSH to instance; sudo service codedeploy-agent status; check SG |
| HEALTH_CONSTRAINTS error | Not enough healthy instances to proceed | Reduce minimumHealthyHosts or fix unhealthy instances |
| ECS deployment stuck | Health check failing on replacement task set | Verify target group health check path and port match container |
| ECS "replacement task set did not stabilize" | Task crashes on startup or resource limits | Check ECS task stopped reason; verify CPU/memory, image exists |
| Lambda deployment failed at BeforeAllowTraffic | Validation Lambda errored or timed out | Check Lambda logs; ensure it calls codedeploy:PutLifecycleEventHookExecutionStatus |
CodeConnections
| Error/Symptom | Cause | Fix |
|---|---|---|
| Connection stays PENDING | Created via CLI/CFN without console completion | Complete OAuth handshake in AWS Console |
| "Unable to use Connection" | IAM policy only has one service prefix | Add codeconnections:UseConnection and codestar-connections:UseConnection |
| Repository not found | Wrong FullRepositoryId format or no repo access | Use org/repo format (case-sensitive); verify app has repo access |
| Host in VPC_CONFIG_FAILED_INITIALIZATION | Network or TLS issue | Verify VPC routes to provider endpoint; validate TLS certificate |
| Cookie error during GitHub authorization | Non-owner attempting GitHub App install | Organization owner must perform the installation |
Diagnostic Commands
# Pipeline: Get execution history
aws codepipeline list-pipeline-executions --pipeline-name NAME --max-items 5
# Pipeline: Get action execution details
aws codepipeline list-action-executions --pipeline-name NAME \
--filter pipelineExecutionId=EXEC_ID
# Build: Get failed phase details
aws codebuild batch-get-builds --ids BUILD_ID \
--query "builds[0].phases[?phaseStatus=='FAILED']"
# Build: Stream logs (if CloudWatch configured)
aws logs tail /aws/codebuild/PROJECT_NAME --follow
# Deploy: Get deployment target status
aws deploy list-deployment-targets --deployment-id DEPLOY_ID
# Deploy: Get lifecycle event details for failed target
aws deploy get-deployment-target --deployment-id DEPLOY_ID --target-id TARGET_ID
# Connections: List all with status
aws codeconnections list-connections --query "Connections[].[ConnectionName,ConnectionStatus]" --output tableEnd-to-End Trace
When a pipeline fails and you don't know which service caused it:
aws codepipeline get-pipeline-state --name NAME→ find failed stage/actionCheck
latestExecution.externalExecutionIdon the failed action — this is the build ID or deployment IDFor build actions:
aws codebuild batch-get-builds --ids BUILD_IDFor deploy actions:
aws deploy get-deployment --deployment-id DEPLOY_IDFor source actions:
aws codeconnections get-connection --connection-arn ARN(check status)
Related
codepipeline.md for pipeline-specific errors
codebuild.md for build configuration issues
codedeploy.md for deployment strategy issues
codeconnections.md for connection setup issues
Security
MUST NOT include secrets, credentials, or sensitive data in diagnostic commands shared with users
Use CloudTrail to audit API calls across all CodeSuite services when investigating security incidents
Verify IAM permissions using
aws iam simulate-principal-policyrather than granting broad access for debugging
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs an MCP server
Security
What our scanner noticed· Low risk
- Instructions that use the network
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- AWS
- Publisher
- AWS (Official)
- Source
- aws/agent-toolkit-for-aws · skills/core-skills/aws-deployment · commit 0a218f8
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- NOTICE (added by AutoGineer from NOTICE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
- Also distributed in
- aws/agent-toolkit-for-aws
AutoGineer is not affiliated with or endorsed by AWS.
Related skills
Shipping And Launch
Addy Osmani· Community
A comprehensive framework for managing safe, observable, and reversible production software deployments.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository113.9k
Quantized Export
Seth Hobson· Community
Export a promoted fine-tuned model in the right deployment format — merged safetensors, LoRA-only, GGUF with imatrix, or FP8. Use after a checkpoint passes promotion, when choosing a quantization format for a target device, or when an exported model fails its smoke test.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 moreMITLow riskGitHub stars of the source repository42.3k
Deployment Pipeline Design
Seth Hobson· Community
Design robust, secure, and automated CI/CD pipelines with multi-stage promotion, approval gates, and progressive delivery strategies.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 moreMITLow riskGitHub stars of the source repository42.3k
Gitops Workflow
Seth Hobson· Community
A guide to implementing GitOps workflows for Kubernetes using ArgoCD and Flux.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository42.3k
Spark Environment Setup
Seth Hobson· Community
Set up and troubleshoot ML training and inference environments on NVIDIA DGX Spark hardware.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 moreMITLow riskGitHub stars of the source repository42.3k
Cloud Infrastructure Deployment Engineer
Seth Hobson· Community
An expert deployment engineer agent specializing in CI/CD pipelines, GitOps workflows, and advanced containerized deployment automation.
Cloud and DevOpsClaude CodeMITGitHub stars of the source repository42.3k
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download aws-deployment.zip