Menu
AWS CodePipeline
User Guide (API Version 2015-07-09)

Detect and React to Changes in Pipeline State with Amazon CloudWatch Events

Amazon CloudWatch Events is a web service that monitors your AWS resources and the applications you run on AWS. You can use Amazon CloudWatch Events to detect and react to changes in the state of a pipeline, stage, or action. Then, based on rules you create, CloudWatch Events invokes one or more target actions when a pipeline, stage, or action enters the state you specify in a rule. Depending on the type of state change, you might want to send notifications, capture state information, take corrective action, initiate events, or take other actions.

Amazon CloudWatch Events are composed of:

  • Rules. An event in Amazon CloudWatch Events is configured by first creating a rule with a selected service as the event source.

  • Targets. The new rule receives a selected service as the event target. For a list of services available as Amazon CloudWatch Events targets, see What Is Amazon CloudWatch Events.

Examples of Amazon CloudWatch Events rules and targets:

  • A rule that sends a notification when the instance state changes, where an EC2 instance is the event source and Amazon SNS is the event target.

  • A rule that sends a notification when the build phase changes, where an AWS CodeBuild configuration is the event source and Amazon SNS is the event target.

  • A rule that detects pipeline changes and invokes an AWS Lambda function.

To configure AWS CodePipeline as an event source:

  1. Create an Amazon CloudWatch Events rule that uses AWS CodePipeline as an event source.

  2. Create a target for your rule that uses one of the services available as targets in Amazon CloudWatch Events, such as AWS Lambda or Amazon SNS.

  3. Grant permissions to Amazon CloudWatch Events to allow it to invoke the selected target service.

Understand How a Pipeline Execution State Change Rule Works

You build rules for detecting and reacting to pipeline state changes using the Events window in Amazon CloudWatch. As you build your rule, the Event Pattern Preview box in the console (or the --event-pattern output in the CLI) displays the event fields, in JSON format.

You can configure notifications to be sent when the state changes for:

  • Specified pipelines or all your pipelines. You control this by using "detail-type": "CodePipeline Pipeline Execution State Change".

  • Specified stages or all your stages, within a specified pipeline or all your pipelines. You control this by using "detail-type": "CodePipeline Stage Execution State Change".

  • Specified actions or all actions, within a specified stage or all stages, within a specified pipeline or all your pipelines. You control this by using "detail-type": "CodePipeline Action Execution State Change".

Each type of execution state change event emits notifications with specific message content, where:

  • The initial version entry shows the version number for the CloudWatch event.

  • The version entry under pipeline detail shows the pipeline structure version number.

  • The execution-id entry under pipeline detail shows the execution ID for the pipeline execution that caused the state change. Refer to the GetPipelineExecution API call in the AWS CodePipeline API Reference.

Pipeline execution state change message content: When a pipeline execution starts, it emits an event that sends notifications with the following content. This example is for the pipeline named "myPipeline" in the us-east-1 region.

Copy
{ "version": "0", "id": event_Id, "detail-type": "CodePipeline Pipeline Execution State Change", "source": "aws.codepipeline", "account": Pipeline_Account, "time": TimeStamp, "region": "us-east-1", "resources": [ "arn:aws:codepipeline:us-east-1:account_ID:pipeline:myPipeline" ], "detail": { "pipeline": "myPipeline", "version": "1", "state": "STARTED", "execution-id": execution_Id } }

Stage execution state change message content: When a stage execution starts, it emits an event that sends notifications with the following content. This example is for the pipeline named "myPipeline" in the us-east-1 region, for the stage "Prod".

Copy
{ "version": "0", "id": event_Id, "detail-type": "CodePipeline Stage Execution State Change", "source": "aws.codepipeline", "account": Pipeline_Account, "time": TimeStamp, "region": "us-east-1", "resources": [ "arn:aws:codepipeline:us-east-1:account_ID:pipeline:myPipeline" ], "detail": { "pipeline": "myPipeline", "version": "1", "execution-id": execution_Id, "stage": "Prod", "state": "STARTED" } }

Action execution state change message content: When an action execution starts, it emits an event that sends notifications with the following content. This example is for the pipeline named "myPipeline" in the us-east-1 region, for the action "myAction".

Copy
{ "version": "0", "id": event_Id, "detail-type": "CodePipeline Action Execution State Change", "source": "aws.codepipeline", "account": Pipeline_Account, "time": TimeStamp, "region": "us-east-1", "resources": [ "arn:aws:codepipeline:us-east-1:account_ID:pipeline:myPipeline" ], "detail": { "pipeline": "myPipeline", "version": "1", "execution-id": execution_Id, "stage": "Prod", "action": "myAction", "state": "STARTED", "type": { "owner": "AWS", "category": "Deploy", "provider": "CodeDeploy", "version": 1 } } }

Valid state values:

Pipeline-level states

Pipeline State Description
STARTED The pipeline execution is currently running.
SUCCEEDED The pipeline execution was completed successfully.
RESUMED A failed pipeline execution has been retried in response to the RetryStageExecution API call.
FAILED The pipeline execution was not completed successfully.
CANCELED The pipeline execution was canceled because the pipeline structure was updated.
SUPERSEDED

While this pipeline execution was waiting for the next stage to be completed, a newer pipeline execution advanced and continued through the pipeline instead.

Stage-level states

Stage State Description
STARTED The stage is currently running.
SUCCEEDED The stage was completed successfully.
RESUMED A failed stage has been retried in response to the RetryStageExecution API call.
FAILED The stage was not completed successfully.
CANCELED The stage was canceled because the pipeline structure was updated.

Action-level states

Action State Description
STARTED The action is currently running.
SUCCEEDED The action was completed successfully.
FAILED For Approval actions, the FAILED state means the action was either rejected by the reviewer or failed due to an incorrect action configuration.
CANCELED The action was canceled because the pipeline structure was updated.

Prerequisites

Before you create event rules for use in your AWS CodePipeline operations, you should do the following:

Send a Notification Whenever Pipeline State Changes (Console)

These steps show how to use the CloudWatch console to create a rule to send notifications of changes in AWS CodePipeline.

To create a CloudWatch Events rule with AWS CodePipeline as the event source

  1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

  2. In the navigation pane, choose Events.

  3. Choose Create rule. Under Event source, from the Service Name drop-down list, choose CodePipeline.

  4. From the Event Type drop-down list, choose the level of state change for the notification.

    • For a rule that applies to pipeline-level events, choose CodePipeline Pipeline Execution State Change.

    • For a rule that applies to stage-level events, choose CodePipeline Stage Execution State Change.

    • For a rule that applies to action-level events, choose CodePipeline Action Execution State Change.

  5. Specify the state changes the rule applies to:

    • For a rule that applies to all state changes, choose Any state.

    • For a rule that applies to some state changes only, choose Specific state(s), and then choose one or more state values from the list.

  6. For event patterns that are more detailed than the selectors allow, you can also use the Edit option in the Event Pattern Preview window to designate an event pattern in JSON format. The following example shows the JSON structure edited manually to specify a pipeline named "myPipeline."

    
              A pipeline name can be edited manually in the JSON structure for the
                rule.

    Note

    If not otherwise specified, then the event pattern is created for all pipelines/stages/actions and states.

    For more detailed event patterns, you can copy and paste the following example event patterns into the Edit window.

    • Use this sample event pattern to capture failed deploy and build actions across all the pipelines.

      Copy
      { "source": [ "aws.codepipeline" ], "detail-type": [ "CodePipeline Action Execution State Change" ], "detail": { "state": [ "FAILED" ], "type": { "category": ["Deploy", "Build"] } } }
    • Use this sample event pattern to capture all rejected or failed approval actions across all the pipelines.

      Copy
      { "source": [ "aws.codepipeline" ], "detail-type": [ "CodePipeline Action Execution State Change" ], "detail": { "state": [ "FAILED" ], "type": { "category": ["Approval"] } } }
    • Use this sample event pattern to capture all the events from the specified pipelines.

      Copy
      { "source": [ "aws.codepipeline" ], "detail-type": [ "CodePipeline Pipeline Execution State Change", "CodePipeline Action Execution State Change", "CodePipeline Stage Execution State Change" ], "detail": { "pipeline": ["myPipeline", "my2ndPipeline"] } }
  7. In the Targets area, choose Add target*.

  8. In the Select target type list, choose the type of target for this rule, and then configure options required by that type.

  9. Choose Configure details.

  10. On the Configure rule details page, type a name and description for the rule, and then select the State box to enable to rule now.

  11. Choose Create rule.

Send a Notification Whenever Pipeline State Changes (CLI)

These steps show how to use the CLI to create a CloudWatch Events rule to send notifications of changes in AWS CodePipeline.

To use the AWS CLI to create a rule, call the put-rule command, specifying:

  • A name that uniquely identifies the rule you are creating. This name must be unique across all of the pipelines you create with AWS CodePipeline associated with your AWS account.

  • The event pattern for the source and detail fields used by the rule. For more information, see Amazon CloudWatch Events and Event Patterns.

To create a CloudWatch Events rule with AWS CodePipeline as the event source

  1. Call the put-rule command to create a rule specifying the event pattern. (See the preceding tables for valid states.)

    The following sample command uses --event-pattern to create a rule called “MyPipelineStateChanges” that emits the CloudWatch event when a pipeline execution fails for the pipeline named "myPipeline."

    Copy
    aws events put-rule --name "MyPipelineStateChanges" --event-pattern "{\"source\":[\"aws.codepipeline\"],\"detail-type\":[\"CodePipeline Pipeline Execution State Change\"],\"detail\":{\"pipeline\":[\"myPipeline\"],\"state\":[\"FAILED\"]}}"
  2. Call the put-targets command to add a target to your new rule, as shown in this example for an Amazon SNS topic:

    Copy
    aws events put-targets --rule MyPipelineStateChanges --targets Id=1,Arn=arn:aws:sns:us-west-2:11111EXAMPLE:MyNotificationTopic
  3. Add permissions for Amazon CloudWatch Events to use the designated target service to invoke the notification. For more information, see Using Resource-Based Policies for Amazon CloudWatch Events.