Notification Concepts - Developer Tools Console

Notification Concepts

Setting up and using notifications is easier if you understand the concepts and terms. Here are some concepts to know about as you use notifications.

Notifications

A notification is a message that contains information about events that occur in the resources you and your developers use. You can set up notifications so that users of a resource, such as a build project, repository, deployment application, or pipeline, receive emails about the event types you specify according to the notification rule you create.

Notifications for AWS CodeCommit can contain user identity information, such as a display name or an email address, through the use of session tags. CodeCommit supports the use of session tags, which are key-value pair attributes that you pass when you assume an IAM role, use temporary credentials, or federate a user in AWS Security Token Service (AWS STS). You can also associate tags with an IAM user. CodeCommit includes the values for displayName and emailAddress in notification content if those tags are present. For more information, see Using Tags to Provide Additional Identity Information in CodeCommit.

Important

Notifications include project-specific information such as build status, deployment status, lines of code that have comments, and pipeline approvals. Notification content might change as new features are added. As a security best practice, you should regularly review the targets of notification rules and the Amazon SNS topic subscribers. For more information, see Understanding Notification Contents and Security.

Notification Rules

A notification rule is an AWS resource that you create to specify when and where notifications are sent. It defines:

  • The conditions under which a notification is created. These conditions are based on events that you choose, which are specific to the resource type. Supported resource types include build projects in AWS CodeBuild, deployment applications in AWS CodeDeploy, pipelines in AWS CodePipeline, and repositories in AWS CodeCommit.

  • The targets to which the notification is sent. You can specify up to 10 targets for a notification rule.

Notification rules are scoped to individual build projects, deployment applications, pipelines, and repositories. Notification rules have both user-defined friendly names and Amazon Resource Names (ARNs). Notification rules must be created in the same AWS Region where the resource exists. For example, if your build project is in the US East (Ohio) Region, your notification rule must be created in the US East (Ohio) Region, too.

You can define up to 10 notification rules for a resource.

Events

An event is a change of state on a resource that you want to monitor. Each resource has a list of event types you can choose from. When you set up a notification rule on a resource, you specify the events that cause notifications to be sent. For example, if you set up notifications for a repository in CodeCommit, and you select Created for both Pull request and Branches and tags, a notification is sent every time a user in that repository creates a pull request, branch, or Git tag.

Detail Types

When you create a notification rule, you can choose the level of detail or detail type included in notifications (Full or Basic). The Full setting (the default) includes all information available for the event in the notification, including any enhanced information provided by services for specific events. The Basic setting includes only a subset of the available information.

The following table lists the enhanced information available for specific event types and describes the differences between the detail types.

Service Event Full includes Basic does not include

CodeCommit

Comments on commits

Comments on pull requests

All event details and the content of the comment, including any replies or comment threads. It also includes the line number and the line of code upon which the comment was made.

The content of the comment. line number, line of code, or any comment threads.

CodeCommit

Pull request created

All event details and the number of files that were added, modified, or deleted in the pull request in relation to the destination branch.

No list of files or details about whether the pull request source branch has added, modified, or deleted files.

CodePipeline

Manual approval needed

All event details and custom data (if configured). The notification also includes a link to the required approval in the pipeline.

No custom data or link.

CodePipeline

Action execution failed

Pipeline execution failed

Stage execution failed

All event details and the content of the error message for the failure.

No error message content.

Targets

A target is a location for receiving notifications from notification rules. The allowed target types are Amazon SNS topics and AWS Chatbot clients configured for Slack channels. Any user subscribed to the target receives notifications about the events that you specify in the notification rule.

If you want to extend the reach of notifications, you can manually configure integration between notifications and AWS Chatbot so that notifications are sent to Amazon Chime chatrooms. You can then choose the Amazon SNS topic that is configured for that AWS Chatbot client as the target for the notification rule. For more information, see To integrate notifications with AWS Chatbot and Amazon Chime.

If you choose to use an AWS Chatbot client as a target, you must first create that client in AWS Chatbot. When you choose an AWS Chatbot client as a target for a notification rule, an Amazon SNS topic is configured for that AWS Chatbot client with all the policies required for notifications to be sent to the Slack channel. You don't have to configure any existing Amazon SNS topics for the AWS Chatbot client.

You can choose to create an Amazon SNS topic as a target as part of creating a notification rule (recommended). You can also choose an existing Amazon SNS topic in the same AWS Region as the notification rule, but you must configure it with the required policy. The Amazon SNS topic that you use for a target must be in your AWS account. It also must be in the same AWS Region as the notification rule and the AWS resource for which the rule was created.

For example, if you create a notification rule for a repository in the US East (Ohio) Region, the Amazon SNS topic must also exist in that Region. If you create an Amazon SNS topic as part of creating a notification rule, the topic is configured with the policy required to allow the publication of events to the topic. This is the best method for working with targets and notification rules. If you choose to use an already-existing topic or create one manually, you must configure it with the required permissions before users receive notifications. For more information, see Configure Amazon SNS Topics for Notifications.

Note

If you want to use an existing Amazon SNS topic instead of creating a new one, in Targets, choose its ARN. Make sure the topic has the appropriate access policy, and that the subscriber list contains only those users who are allowed to see information about the resource. If the Amazon SNS topic is a topic that was used for CodeCommit notifications before November 5, 2019, it will contain a policy that allows CodeCommit to publish to it that contains different permissions than those required for AWS CodeStar Notifications. Using these topics is not recommended. If you want to use one created for that experience, you must add the required policy for AWS CodeStar Notifications in addition to the one that already exists. For more information, see Configure Amazon SNS Topics for Notifications and Understanding Notification Contents and Security.

Notifications and AWS CodeStar Notifications

While a feature of the Developer Tools console, notifications has its own API, AWS CodeStar Notifications. It also has its own AWS resource type (notification rules), permissions, and events. Events for notification rules are logged in AWS CloudTrail. API actions can be allowed or denied through IAM policies.

Events for Notification Rules on Repositories

Category Events Event IDs

Comments

On commits

On pull requests

codecommit-repository-comments-on-commits

codecommit-repository-comments-on-pull-requests

Approvals

Status changed

Rule override

codecommit-repository-approvals-status-changed

codecommit-repository-approvals-rule-override

Pull request

Created

Source updated

Status changed

Merged

codecommit-repository-pull-request-created

codecommit-repository-pull-request-source-updated

codecommit-repository-pull-request-status-changed

codecommit-repository-pull-request-merged

Branches and tags

Created

Deleted

Updated

codecommit-repository-branches-and-tags-created

codecommit-repository-branches-and-tags-deleted

codecommit-repository-branches-and-tags-updated

Events for Notification Rules on Build Projects

Category Events Event IDs

Build state

Failed

Succeeded

In-progress

Stopped

codebuild-project-build-state-failed

codebuild-project-build-state-succeeded

codebuild-project-build-state-in-progress

codebuild-project-build-state-stopped

Build phase

Failure

Success

codebuild-project-build-phase-failure

codebuild-project-build-phase-success

Events for Notification Rules on Deployment Applications

Category Events Event IDs

Deployment

Failed

Succeeded

Started

codedeploy-application-deployment-failed

codedeploy-application-deployment-succeeded

codedeploy-application-deployment-started

Events for Notification Rules on Pipelines

Category Events Event IDs

Action execution

Succeeded

Failed

Canceled

Started

codepipeline-pipeline-action-execution-succeeded

codepipeline-pipeline-action-execution-failed

codepipeline-pipeline-action-execution-canceled

codepipeline-pipeline-action-execution-started

Stage execution

Started

Succeeded

Resumed

Canceled

Failed

codepipeline-pipeline-stage-execution-started

codepipeline-pipeline-stage-execution-succeeded

codepipeline-pipeline-stage-execution-resumed

codepipeline-pipeline-stage-execution-canceled

codepipeline-pipeline-stage-execution-failed

Pipeline execution

Failed

Canceled

Started

Resumed

Succeeded

Superseded

codepipeline-pipeline-pipeline-execution-failed

codepipeline-pipeline-pipeline-execution-canceled

codepipeline-pipeline-pipeline-execution-started

codepipeline-pipeline-pipeline-execution-resumed

codepipeline-pipeline-pipeline-execution-succeeded

codepipeline-pipeline-pipeline-execution-superseded

Manual approval

Failed

Needed

Succeeded

codepipeline-pipeline-manual-approval-failed

codepipeline-pipeline-manual-approval-needed

codepipeline-pipeline-manual-approval-succeeded