# Official sources

Use this reference only when you need source grounding for AWS service behavior or the detailed source list.

## AWS documentation

Use these as starting points, not as proof of the user's live AWS state:
- https://docs.aws.amazon.com/codepipeline/latest/userguide/troubleshooting.html
- https://docs.aws.amazon.com/codebuild/latest/userguide/troubleshooting.html
- https://docs.aws.amazon.com/codedeploy/latest/userguide/troubleshooting-deployments.html
- https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-codepipeline-pipeline.html

## Grounding rule

Official documentation explains AWS service behavior. It does not prove the user's current account, Region, quota, resource configuration, IAM boundary, pricing, entitlement, or operational state. Prefer read-only AWS MCP or CLI evidence, repository evidence, or sanitized user-provided evidence for current-state claims.

## Current MCP/documentation refresh (2026-06-02)

Service facts from official docs:
- CodeDeploy troubleshooting separates deployment failures by lifecycle event, credentials, PKCS7 validation, file conflicts, DownloadBundle errors, health checks, and platform/script behavior.
- CodePipeline can be represented as CloudFormation `AWS::CodePipeline::Pipeline`; repo-side fixes must keep pipeline resource semantics and IAM roles intact.

Sampled live evidence:
- Read-only regional availability sampling reported AWS CodePipeline, AWS CodeBuild, and AWS CodeDeploy as `isAvailableIn` in `us-east-1`, `us-west-2`, `eu-west-1`, and `ap-southeast-1`.
- Sampled APIs `CodePipeline+GetPipelineState`, `CodeBuild+BatchGetBuilds`, and `CodeDeploy+GetDeployment` were reported `isAvailableIn` in those regions.

Review implications:
- Patch only the failing repo configuration unless explicitly authorized for live action. Require failing stage/action evidence, logs, minimal diff, validation command, and rollback.
- Do not guess root cause from a failed pipeline status; correlate source revision, build logs, deployment events, roles, artifacts, and environment config.

# Pipeline Failure Analysis Guide

Use this reference when fixing CodePipeline, CodeBuild, CodeDeploy, GitHub Actions, GitLab, buildspecs, artifact paths, environment variables, or deployment wiring in repository files.

## What people get wrong

The lazy story is:

> The pipeline failed, so patch the line that looks broken.

Wrong. Pipeline failures are often evidence-routing problems: wrong revision, wrong artifact, wrong role, wrong environment, or a deployment failure surfacing as a build failure.

Common bad assumptions:

- The failed stage is the root cause.
- Re-running is harmless.
- Build logs contain no secrets.
- Artifact path changes are low risk.
- A green build means deploy safety.
- Fixing CI config authorizes a live pipeline run.

## Failure-mode map

- **Source stage:** wrong branch, webhook, connection, commit, submodule, or artifact format.
- **Build stage:** buildspec path, runtime image, env var, IAM role, dependency cache, test command, artifact upload.
- **Deploy stage:** CodeDeploy lifecycle hook, ECS task set, Lambda alias, CloudFormation change set, missing permission.
- **Approval/gate:** missing manual approval, stale approval, wrong condition, Lambda approval action failure.
- **Cross-account:** artifact bucket/KMS/key policy, role trust, external ID, region mismatch.

## Minimum safe workflow

1. Identify provider and failing stage/action.
2. Confirm source revision and artifact that failed.
3. Inspect logs without exposing secrets.
4. Patch the smallest repo-side cause.
5. Preserve gates, approvals, artifact integrity, and rollback settings.
6. Run local lint/test/build validators relevant to the changed file.
7. State whether a live pipeline re-run is required and require approval for it.

## Verification targets

- pipeline definition or workflow YAML
- buildspec and artifact paths
- CodeBuild project env/runtime/image settings where represented in repo
- CodeDeploy AppSpec and deployment group references
- CloudFormation/CDK/Terraform pipeline resource definitions
- IAM role references and KMS/artifact bucket wiring
- failing log excerpt sanitized by the user or read-only tool output

## When to push back

Push back if the user asks to:

- remove tests/gates to make the pipeline green
- print or paste secret-bearing logs
- re-run production deploys without approval
- change artifact identity without release-owner signoff
- widen deploy role permissions as a blind fix
- ignore a failed post-deploy validation

# Safety checklist

- Do not ask for or print secrets, credentials, access tokens, private keys, account numbers, or customer identifiers.
- Keep edits minimal and reversible.
- Do not perform live cloud mutation by default.
- Surface rollback implications and missing validation explicitly.
- Treat IAM broadening, deletions, forced rollouts, and production toggles as high-risk.

# Workflow and output contract

Use this reference for full write-capable AWS patch work.

## Workflow

1. Classify the repo-side correction.
2. Confirm the target files and blast radius.
3. Make the smallest reversible edit.
4. Run local validators or syntax checks.
5. Report exact files changed, validation results, and rollback path.

## Guardrails

- Repo write access is allowed.
- Live AWS mutation is out of scope by default.
- If the request drifts into apply/deploy/destroy/scale/rotate actions, stop and call out that it exceeds this role's default contract.