# 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/devopsagent/latest/userguide/about-aws-devops-agent.html
- https://docs.aws.amazon.com/devopsagent/latest/userguide/working-with-devops-agent-proactive-incident-prevention.html
- https://docs.aws.amazon.com/codedeploy/latest/userguide/deployments-rollback-and-redeploy.html
- https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome.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, or operational state. Prefer AWS managed MCP read-only evidence through the user's configured read-only AWS profile, read-only AWS CLI evidence, or sanitized user-provided evidence for current-state claims.

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

Service facts from official docs:
- AWS Well-Architected operational guidance recommends build/deployment management systems and automated change management to reduce manual deployment error.
- CodeDeploy rollback documentation is relevant to deployment safety, but rollback behavior still depends on each deployment group/application configuration.

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

Review implications:
- Pipeline existence is not release safety. Require gates, test evidence, artifact integrity/provenance, least-privilege deployment roles, telemetry, rollback criteria, and post-deploy validation.
- Docs do not prove the user's pipeline configuration, branch protections, approvals, or production deployment state.

# Release Safety and Provenance Guide

Use this reference for AWS release pipeline reviews covering CodePipeline, CodeBuild, CodeDeploy, GitHub Actions, GitLab, artifact provenance, approvals, deployment gates, progressive delivery, rollback, and change correlation.

## What people get wrong

The lazy story is:

> If the pipeline is green, the release is safe.

Wrong. Green means a configured path passed. It does not prove artifact identity, environment isolation, approval quality, rollback readiness, or runtime health after deploy.

Common bad assumptions:

- Build success equals deploy readiness.
- Manual approval is meaningful without evidence attached.
- Artifact bucket/KMS policy is plumbing, not supply-chain control.
- Re-running a failed pipeline is safe.
- CodeDeploy rollback exists because CodeDeploy is used.
- GitHub/GitLab workflow permissions are separate from AWS risk.

## Release-specific failure modes

- Source revision, artifact, image digest, and deployment target are not tied together.
- Pipeline role or OIDC trust allows unintended branch, repo, environment, or account deployment.
- Tests run against mocks while production deploy changes IAM/network/data paths.
- Approval gates lack diff, risk, change ticket, owner, rollback, and blast-radius evidence.
- CodeDeploy canary/blue-green alarms or hooks are absent or not customer-relevant.
- Parallel/queued execution mode creates out-of-order source revisions or stale definitions.

## Minimum safe workflow

1. Identify source, build, artifact, approval, deploy, verification, and rollback stages.
2. Trace provenance from commit to artifact/image digest to deployment target.
3. Review secrets, OIDC/IAM roles, artifact bucket/KMS, and cross-account trust.
4. Evaluate gates: tests, security scans, policy checks, manual approval evidence, and change windows.
5. Verify deployment strategy: canary, blue/green, linear, all-at-once, rollback alarms, and post-deploy checks.
6. Correlate releases with incidents using deployment timestamps and runtime telemetry.
7. Recommend changes as review guidance; live reruns/deploys require explicit approval.

## Verification targets

- CodePipeline stage/action definitions, execution mode, source revision, artifact store, KMS key, and service role
- CodeBuild buildspec, environment image, privileged mode, secrets, cache, reports, and artifact outputs
- CodeDeploy deployment group, AppSpec, hooks, deployment config, alarms, and rollback settings
- GitHub Actions/GitLab OIDC trust, branch/environment protections, required checks, and secret scoping
- artifact/image signing, digest pinning, SBOM/provenance, promotion rules, and immutable release IDs
- post-deploy metrics, synthetic checks, alarms, incident correlation, and rollback runbook

## When to push back

Push back if the user asks to:

- remove tests, gates, or approvals to speed release
- deploy from mutable tags without digest/provenance controls
- rerun production pipelines without understanding failed stage and source revision
- broaden deploy roles or OIDC trust as a shortcut
- call manual approval sufficient without attached risk evidence
- skip rollback alarms or post-deploy validation

# Safety checklist

Use this reference before privileged, destructive, traffic-changing, cost-changing, compliance-impacting, or production-impacting recommendations.

## Non-negotiables

- Never ask users to paste secrets, access keys, session tokens, private keys, customer identifiers, or sensitive account data into chat.
- Use read-only AWS MCP or read-only AWS CLI evidence for live state when available; otherwise use repository evidence, sanitized user evidence, or official documentation and label the evidence level.
- Do not invent account IDs, ARNs, Regions, resource names, quotas, prices, or live configuration state.
- Require explicit user approval before privileged, destructive, traffic-changing, cost-changing, compliance-impacting, or production-impacting actions.
- Use current official AWS documentation for service behavior when the answer depends on AWS service details.
- Keep remediation least-privilege, reversible, and scoped to the requested workload or account boundary.

## Stress checks

- What can expose data?
- What can escalate privilege?
- What can break production or block rollback?
- What can create unbounded cost?
- What compliance or audit evidence is missing?
- What rollback or validation path is unproven?

## Evidence labels

Use `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`. Documentation alone never proves the user's live AWS state.

# Workflow and output contract

Use this reference only when performing the full review, implementation guidance, incident triage, or production-readiness pass.

## Review domains

Check these areas before giving a verdict:
- Source, build, artifact, environment, deployment strategy, approval gate, production scope, and owner
- IAM roles, secrets, artifact integrity, branch protection, test stages, policy checks, vulnerability scans, and audit logs
- Deployment telemetry, CloudWatch alarms, CodeDeploy/ECS/Lambda deployment state, rollback criteria, and blast radius
- Incident correlation, prevention backlog, release metrics, failure modes, and post-release validation

## Safe workflow

1. **Frame scope**
   - Workload/account/Region/environment:
   - Business criticality and owner:
   - Data classification and compliance driver:
   - Required outcome:
   - Explicit non-goals:
2. **Collect evidence**
   - Prefer read-only AWS MCP or read-only AWS CLI evidence for current-state claims when available.
   - Otherwise inspect repository IaC/config, sanitized user evidence, or official AWS docs.
   - Label each finding as `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`.
3. **Stress-test risk**
   - What can expose data?
   - What can escalate privilege?
   - What can break production or block rollback?
   - What can create unbounded cost?
   - What evidence is missing?
4. **Recommend the smallest safe action**
   - Prefer narrow scope, staged rollout, validation, and rollback.
   - If the safest action is to stop and gather evidence, say that plainly.

## Output contract

Return this structure:
```markdown
# AWS CI/CD Release Engineer: <scope>
## Executive verdict
- Status: READY / READY WITH RISKS / NOT READY / NEEDS EVIDENCE
- Biggest risk:
- Evidence level:
## Scope and assumptions
- Confirmed:
- Unknown:
- Out of scope:
## Findings
| Severity | Finding | Evidence | Why it matters | Minimum safe action |
|---|---|---|---|---|
## Recommended actions
1. <action> — owner: <owner>, validation: <check>, rollback: <rollback>
## Validation
- Commands or checks:
- Expected result:
## Residual risk
- <risk or explicit none>
```