opensite-ai/opensite-skills / aws-deployment
aws-deployment
UnverifiedConfigures 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.
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
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |