How to get notified when AWS CodePipeline fails

The short version

Option 1: a notification rule (console, a few clicks)

Notification rules are built into the AWS Developer Tools console; the API is still called CodeStar Notifications. A rule can post to an Amazon SNS topic — which can email or text people — or to Slack and Microsoft Teams through Amazon Q Developer in chat applications (formerly AWS Chatbot).

1. Open the pipeline in the CodePipeline console and choose Notify → Create notification rule.
2. Name the rule and choose Full as the detail type, so the message includes the error.
3. Under Events that trigger notifications, tick Pipeline execution → Failed (event ID codepipeline-pipeline-pipeline-execution-failed). Stage- and action-level Failed events exist too if you want more detail.
4. Choose a target: an SNS topic (you can create one here; its name starts with codestar-notifications-) or a Slack or Teams client you’ve already set up in Amazon Q Developer.
5. Submit, then subscribe your email address to the SNS topic and confirm the subscription. Nothing arrives until someone is subscribed.

The same rule from the AWS CLI:

aws codestar-notifications create-notification-rule \
  --name my-pipeline-failed \
  --resource arn:aws:codepipeline:us-east-1:111122223333:my-pipeline \
  --event-type-ids codepipeline-pipeline-pipeline-execution-failed \
  --detail-type FULL \
  --targets TargetType=SNS,TargetAddress=arn:aws:sns:us-east-1:111122223333:codestar-notifications-my-pipeline

If you reuse an existing SNS topic, its access policy must let the notifications service publish to it:

{
  "Sid": "AWSCodeStarNotifications_publish",
  "Effect": "Allow",
  "Principal": { "Service": ["codestar-notifications.amazonaws.com"] },
  "Action": "SNS:Publish",
  "Resource": "arn:aws:sns:us-east-1:111122223333:my-topic"
}

Good to know: the rule must be in the same Region as the pipeline, one rule can have up to 10 targets, and creating rules needs codestar-notifications permissions — the AWSCodePipeline_FullAccess managed policy includes them; the read-only policy doesn’t.

Option 2: an EventBridge rule (for custom routing)

CodePipeline sends every state change to Amazon EventBridge. A rule that matches failed pipeline executions can fan out to SNS, a Lambda function, or any other target. Save this pattern as pattern.json:

{
  "source": ["aws.codepipeline"],
  "detail-type": ["CodePipeline Pipeline Execution State Change"],
  "detail": {
    "state": ["FAILED"],
    "pipeline": ["my-pipeline"]
  }
}

Drop the pipeline filter to catch failures from every pipeline in the Region. Then create the rule and point it at a topic:

aws events put-rule --name pipeline-failed --event-pattern file://pattern.json
aws events put-targets --rule pipeline-failed \
  --targets Id=1,Arn=arn:aws:sns:us-east-1:111122223333:my-topic

The topic policy must allow events.amazonaws.com to call sns:Publish. A pipeline’s state can be STARTED, SUCCEEDED, FAILED, CANCELED, STOPPED, STOPPING, SUPERSEDED or RESUMED. Stage and action changes arrive with their own detail types: CodePipeline Stage Execution State Change and CodePipeline Action Execution State Change.

Option 3: a desktop notification on your Mac

Emails get filtered and Slack channels get muted. If what you actually want is to see a failure within seconds of it happening while you work, a menu-bar app is the shortest path, and it needs no changes in AWS at all.

ShipBoard reads your existing ~/.aws profiles with three read-only permissions (codepipeline:ListPipelines, GetPipeline and GetPipelineState), shows each pipeline’s stages in the menu bar, and posts a native macOS notification when a run goes from running to failed. It’s free.

The trade-off: it only alerts you, and only while your Mac is on. Many teams use both — a notification rule for the shared channel, and a menu-bar app for the person who’s shipping.

Sources

• AWS: notification concepts and event types
• AWS: create a notification rule for a pipeline
• AWS: configure an SNS topic for notifications
• AWS: monitoring CodePipeline events with EventBridge