codepipeline-event-notifier 0.2.7 → 0.3.0

package/.editorconfig

@@ -0,0 +1,12 @@
+# ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen".
+
+root=true
+
+[*]
+end_of_line=lf
+charset=utf-8
+
+[*\.{js,ts}]
+indent_style=space
+indent_size=2
+max_line_length=120

package/.jsii

@@ -8440,7 +8440,7 @@
     "stability": "stable"
   },
   "homepage": "https://github.com/gammarers-aws-cdk-constructs/codepipeline-event-notifier.git",
-  "jsiiVersion": "6.0.13 (build 5c05d06)",
+  "jsiiVersion": "6.0.14 (build 44649f3)",
   "keywords": [
     "cdk"
   ],
@@ -8456,7 +8456,7 @@
   },
   "name": "codepipeline-event-notifier",
   "readme": {
-    "markdown": "# CodePipeline Event Notifier\n\n[![npm version](https://img.shields.io/npm/v/codepipeline-event-notifier.svg)](https://www.npmjs.com/package/codepipeline-event-notifier)\n[![license](https://img.shields.io/npm/l/codepipeline-event-notifier.svg)](LICENSE)\n\nCDK construct that listens to **AWS CodePipeline execution STARTED** events via EventBridge, invokes a Lambda notifier, and publishes execution state changes to an SNS topic.\n\n## Features\n\n- **EventBridge integration**: triggers on `CodePipeline Pipeline Execution State Change` with `state=STARTED` (customizable via `eventPattern`)\n- **SNS notifications**: publishes execution status transitions as JSON messages (`phase`: `eventbridge` / `wait`)\n- **Execution waiting**: calls `GetPipelineExecution` until a terminal state (`SUCCEEDED` / `FAILED` / `STOPPED` / `SUPERSEDED`) or timeout\n- **Configurable props**: reuse an existing SNS topic, adjust wait interval / max wait duration / Lambda timeout, and filter events\n- **No subscriptions by default**: the SNS topic is created (or reused), but subscriptions (email/HTTP/etc.) are intentionally not configured\n\n## Installation\n\n### npm\n\n```bash\nnpm install codepipeline-event-notifier\n```\n\n### yarn\n\n```bash\nyarn add codepipeline-event-notifier\n```\n\n## Usage\n\nInstantiate `CodePipelineEventNotifier` in your CDK stack:\n\n```ts\nimport { Stack } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\nimport { CodePipelineEventNotifier } from 'codepipeline-event-notifier';\n\nexport class MyStack extends Stack {\n  constructor(scope: Construct, id: string) {\n    super(scope, id);\n\n    const notifier = new CodePipelineEventNotifier(this, 'CodePipelineEventNotifier');\n\n    // Optionally subscribe to the topic created by the construct\n    // notifier.topic.addSubscription(...);\n  }\n}\n```\n\n### Customize with props\n\n```ts\nimport { Duration, Stack, aws_sns as sns } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\nimport { CodePipelineEventNotifier } from 'codepipeline-event-notifier';\n\nexport class MyStack extends Stack {\n  constructor(scope: Construct, id: string) {\n    super(scope, id);\n\n    const topic = sns.Topic.fromTopicArn(this, 'ExistingTopic', 'arn:aws:sns:...');\n\n    new CodePipelineEventNotifier(this, 'CodePipelineEventNotifier', {\n      topic,\n      waitInterval: Duration.seconds(30),\n      maxWaitDuration: Duration.minutes(10),\n      timeout: Duration.minutes(12),\n      eventPattern: {\n        source: ['aws.codepipeline'],\n        detailType: ['CodePipeline Pipeline Execution State Change'],\n        detail: {\n          state: ['STARTED'],\n          pipeline: ['my-pipeline'],\n        },\n      },\n    });\n  }\n}\n```\n\n## Options\n\n| Prop | Type | Default | Description |\n| --- | --- | --- | --- |\n| `topic` | `sns.ITopic` | new topic | SNS topic to publish notifications to (also exposed as `notifier.topic`) |\n| `waitInterval` | `Duration` | `10 seconds` | Interval between `GetPipelineExecution` calls |\n| `maxWaitDuration` | `Duration` | `14 minutes` | Maximum wait duration before giving up |\n| `timeout` | `Duration` | `15 minutes` | Notifier Lambda timeout (should exceed `maxWaitDuration`) |\n| `eventPattern` | `events.EventPattern` | CodePipeline `STARTED` | EventBridge rule filter |\n\nThe notifier Lambda uses these environment variables (set by the construct from props):\n\n- `SNS_TOPIC_ARN` (**required**): SNS topic ARN to publish notifications to\n- `WAIT_INTERVAL_SECONDS` (default: `10`): wait interval in seconds\n- `MAX_WAIT_MINUTES` (default: `14`): maximum wait duration in minutes\n\n## Requirements\n\n- Node.js `>= 20`\n- AWS CDK `v2` (`aws-cdk-lib` `^2.232.0`)\n- `constructs` `^10.5.1`\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n"
+    "markdown": "# CodePipeline Event Notifier (CDK v2)\n\n[![npm version](https://img.shields.io/npm/v/codepipeline-event-notifier?style=flat-square)](https://www.npmjs.com/package/codepipeline-event-notifier)\n[![license](https://img.shields.io/npm/l/codepipeline-event-notifier?style=flat-square)](https://www.npmjs.com/package/codepipeline-event-notifier)\n[![Node.js](https://img.shields.io/node/v/codepipeline-event-notifier?style=flat-square)](https://www.npmjs.com/package/codepipeline-event-notifier)\n[![build](https://img.shields.io/github/actions/workflow/status/gammarers-aws-cdk-constructs/codepipeline-event-notifier/build.yml?branch=main&label=build&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/codepipeline-event-notifier/actions/workflows/build.yml)\n\n[![View on Construct Hub](https://constructs.dev/badge?package=codepipeline-event-notifier)](https://constructs.dev/packages/codepipeline-event-notifier)\n\nCDK construct that listens to **AWS CodePipeline execution STARTED** events via EventBridge, invokes a Lambda notifier, and publishes execution state changes to an SNS topic.\n\n## Features\n\n- **EventBridge integration**: triggers on `CodePipeline Pipeline Execution State Change` with `state=STARTED` (customizable via `eventPattern`)\n- **Tag-based pipeline selection**: required `targetPipeline.tags` filters which pipelines are notified (`ListTagsForResource`; keys are AND, values are OR)\n- **Least-privilege IAM**: CodePipeline API access is scoped to this account and region, or to `targetPipeline.arns` when set\n- **SNS notifications**: publishes execution status transitions as JSON messages (`phase`: `eventbridge` / `wait`)\n- **Execution waiting**: calls `GetPipelineExecution` until a terminal state (`SUCCEEDED` / `FAILED` / `STOPPED` / `SUPERSEDED`) or timeout\n- **Configurable props**: reuse an existing SNS topic, adjust wait interval / max wait duration / Lambda timeout, and optionally refine the EventBridge pattern\n- **No subscriptions by default**: the SNS topic is created (or reused), but subscriptions (email/HTTP/etc.) are intentionally not configured\n\n## How it works\n\n1. EventBridge matches a CodePipeline execution state-change event (default: `state=STARTED`) and invokes the notifier Lambda.\n2. The Lambda resolves the pipeline ARN, then keeps the event only when `targetPipeline.tags` match (`ListTagsForResource`; keys are AND, values are OR) and, if set, `targetPipeline.arns` includes the pipeline.\n3. It publishes an SNS message with `phase: eventbridge`, then calls `GetPipelineExecution` until a terminal status (`SUCCEEDED` / `FAILED` / `STOPPED` / `SUPERSEDED`) or `maxWaitDuration`.\n4. Each status change (and timeout) is published with `phase: wait`. Subscribe to `notifier.topic`; this construct does not add subscriptions.\n\n## Installation\n\n### npm\n\n```bash\nnpm install codepipeline-event-notifier\n```\n\n### yarn\n\n```bash\nyarn add codepipeline-event-notifier\n```\n\n### pnpm\n\n```bash\npnpm add codepipeline-event-notifier\n```\n\n## Usage\n\nInstantiate `CodePipelineEventNotifier` in your CDK stack:\n\n```ts\nimport { Stack } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\nimport { CodePipelineEventNotifier } from 'codepipeline-event-notifier';\n\nexport class MyStack extends Stack {\n  constructor(scope: Construct, id: string) {\n    super(scope, id);\n\n    const notifier = new CodePipelineEventNotifier(this, 'CodePipelineEventNotifier', {\n      targetPipeline: {\n        tags: [\n          {\n            key: 'Notify',\n            values: ['true'],\n          },\n        ],\n      },\n    });\n\n    // Optionally subscribe to the topic created by the construct\n    // notifier.topic.addSubscription(...);\n  }\n}\n```\n\n### Customize with props\n\n```ts\nimport { Duration, Stack, aws_sns as sns } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\nimport { CodePipelineEventNotifier } from 'codepipeline-event-notifier';\n\nexport class MyStack extends Stack {\n  constructor(scope: Construct, id: string) {\n    super(scope, id);\n\n    const topic = sns.Topic.fromTopicArn(this, 'ExistingTopic', 'arn:aws:sns:...');\n\n    new CodePipelineEventNotifier(this, 'CodePipelineEventNotifier', {\n      topic,\n      waitInterval: Duration.seconds(30),\n      maxWaitDuration: Duration.minutes(10),\n      timeout: Duration.minutes(12),\n      targetPipeline: {\n        tags: [\n          {\n            key: 'Team',\n            values: ['platform', 'infra'],\n          },\n        ],\n        arns: [\n          'arn:aws:codepipeline:us-east-1:123456789012:my-pipeline',\n        ],\n      },\n      eventPattern: {\n        source: ['aws.codepipeline'],\n        detailType: ['CodePipeline Pipeline Execution State Change'],\n        detail: {\n          state: ['STARTED'],\n        },\n      },\n    });\n  }\n}\n```\n\n## Options\n\n| Prop | Type | Default | Description |\n| --- | --- | --- | --- |\n| `targetPipeline` | `TargetPipeline` | *(required)* | Tag filters (`tags`) for pipelines that should notify. Optional `arns` restrict IAM and skip other pipelines. Default IAM is this account and region |\n| `topic` | `sns.ITopic` | new topic | SNS topic to publish notifications to (also exposed as `notifier.topic`) |\n| `waitInterval` | `Duration` | `10 seconds` | Interval between `GetPipelineExecution` calls |\n| `maxWaitDuration` | `Duration` | `14 minutes` | Maximum wait duration before giving up |\n| `timeout` | `Duration` | `15 minutes` | Notifier Lambda timeout (should exceed `maxWaitDuration`) |\n| `eventPattern` | `events.EventPattern` | CodePipeline `STARTED` | EventBridge rule filter |\n\nThe notifier Lambda uses these environment variables (set by the construct from props):\n\n- `SNS_TOPIC_ARN` (**required**): SNS topic ARN to publish notifications to\n- `TARGET_PIPELINE_TAGS` (**required**): JSON array of `{ key, values }` tag filters\n- `TARGET_PIPELINE_ARNS` (optional): JSON array of pipeline ARNs used as an allowlist when `targetPipeline.arns` is set\n- `WAIT_INTERVAL_SECONDS` (default: `10`): wait interval in seconds\n- `MAX_WAIT_MINUTES` (default: `14`): maximum wait duration in minutes\n\n## API\n\nSee the [API reference](./API.md).\n\n## Requirements\n\n- Node.js `>= 20`\n- AWS CDK `v2` (`aws-cdk-lib` `^2.232.0`)\n- `constructs` `^10.5.1`\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n"
   },
   "repository": {
     "type": "git",
@@ -8483,7 +8483,7 @@
         },
         "locationInModule": {
           "filename": "src/constructs/codepipeline-event-notifier.ts",
-          "line": 63
+          "line": 177
         },
         "parameters": [
           {
@@ -8509,7 +8509,6 @@
               "summary": "construct properties."
             },
             "name": "props",
-            "optional": true,
             "type": {
               "fqn": "codepipeline-event-notifier.CodePipelineEventNotifierProps"
             }
@@ -8519,7 +8518,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/constructs/codepipeline-event-notifier.ts",
-        "line": 52
+        "line": 166
       },
       "name": "CodePipelineEventNotifier",
       "properties": [
@@ -8531,7 +8530,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/codepipeline-event-notifier.ts",
-            "line": 56
+            "line": 170
           },
           "name": "topic",
           "type": {
@@ -8552,10 +8551,26 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/constructs/codepipeline-event-notifier.ts",
-        "line": 8
+        "line": 42
       },
       "name": "CodePipelineEventNotifierProps",
       "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Pipelines that should produce notifications, selected by resource tags."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/codepipeline-event-notifier.ts",
+            "line": 46
+          },
+          "name": "targetPipeline",
+          "type": {
+            "fqn": "codepipeline-event-notifier.TargetPipeline"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -8566,7 +8581,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/codepipeline-event-notifier.ts",
-            "line": 45
+            "line": 84
           },
           "name": "eventPattern",
           "optional": true,
@@ -8585,7 +8600,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/codepipeline-event-notifier.ts",
-            "line": 30
+            "line": 69
           },
           "name": "maxWaitDuration",
           "optional": true,
@@ -8604,7 +8619,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/codepipeline-event-notifier.ts",
-            "line": 38
+            "line": 77
           },
           "name": "timeout",
           "optional": true,
@@ -8623,7 +8638,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/codepipeline-event-notifier.ts",
-            "line": 15
+            "line": 54
           },
           "name": "topic",
           "optional": true,
@@ -8641,7 +8656,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/codepipeline-event-notifier.ts",
-            "line": 22
+            "line": 61
           },
           "name": "waitInterval",
           "optional": true,
@@ -8651,8 +8666,127 @@
         }
       ],
       "symbolId": "src/constructs/codepipeline-event-notifier:CodePipelineEventNotifierProps"
+    },
+    "codepipeline-event-notifier.TargetPipeline": {
+      "assembly": "codepipeline-event-notifier",
+      "datatype": true,
+      "docs": {
+        "stability": "stable",
+        "summary": "Selection criteria for pipelines that should trigger notifications."
+      },
+      "fqn": "codepipeline-event-notifier.TargetPipeline",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/constructs/codepipeline-event-notifier.ts",
+        "line": 24
+      },
+      "name": "TargetPipeline",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Tag filters applied to CodePipeline resources."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/codepipeline-event-notifier.ts",
+            "line": 28
+          },
+          "name": "tags",
+          "type": {
+            "collection": {
+              "elementtype": {
+                "fqn": "codepipeline-event-notifier.TargetPipelineTag"
+              },
+              "kind": "array"
+            }
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "all CodePipeline resources in this account and region",
+            "remarks": "When set, the notifier also ignores STARTED events whose pipeline ARN is not in this list.",
+            "stability": "stable",
+            "summary": "Pipeline ARNs used as IAM resources for `GetPipelineExecution` and `ListTagsForResource`."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/codepipeline-event-notifier.ts",
+            "line": 36
+          },
+          "name": "arns",
+          "optional": true,
+          "type": {
+            "collection": {
+              "elementtype": {
+                "primitive": "string"
+              },
+              "kind": "array"
+            }
+          }
+        }
+      ],
+      "symbolId": "src/constructs/codepipeline-event-notifier:TargetPipeline"
+    },
+    "codepipeline-event-notifier.TargetPipelineTag": {
+      "assembly": "codepipeline-event-notifier",
+      "datatype": true,
+      "docs": {
+        "remarks": "Keys across entries are AND; values within an entry are OR.",
+        "stability": "stable",
+        "summary": "Tag filter for selecting CodePipeline pipelines."
+      },
+      "fqn": "codepipeline-event-notifier.TargetPipelineTag",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/constructs/codepipeline-event-notifier.ts",
+        "line": 9
+      },
+      "name": "TargetPipelineTag",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Tag key that must be present on the pipeline."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/codepipeline-event-notifier.ts",
+            "line": 13
+          },
+          "name": "key",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Accepted values for {@link key}."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/codepipeline-event-notifier.ts",
+            "line": 18
+          },
+          "name": "values",
+          "type": {
+            "collection": {
+              "elementtype": {
+                "primitive": "string"
+              },
+              "kind": "array"
+            }
+          }
+        }
+      ],
+      "symbolId": "src/constructs/codepipeline-event-notifier:TargetPipelineTag"
     }
   },
-  "version": "0.2.7",
-  "fingerprint": "y54/CjTZc5/U0G0edVc1uldzU6rZkhzbjpkz8SymIKM="
+  "version": "0.3.0",
+  "fingerprint": "86gKdiBIuLlaQSHsQEbGErh5OLIFIlSh2M5r4a6i2eg="
 }

package/API.md

@@ -11,7 +11,7 @@ Provisions an EventBridge rule that listens for CodePipeline execution STARTED e
 ```typescript
 import { CodePipelineEventNotifier } from 'codepipeline-event-notifier'
 
-new CodePipelineEventNotifier(scope: Construct, id: string, props?: CodePipelineEventNotifierProps)
+new CodePipelineEventNotifier(scope: Construct, id: string, props: CodePipelineEventNotifierProps)
 ```
 
 | **Name** | **Type** | **Description** |
@@ -38,7 +38,7 @@ the construct id.
 
 ---
 
-##### `props`<sup>Optional</sup> <a name="props" id="codepipeline-event-notifier.CodePipelineEventNotifier.Initializer.parameter.props"></a>
+##### `props`<sup>Required</sup> <a name="props" id="codepipeline-event-notifier.CodePipelineEventNotifier.Initializer.parameter.props"></a>
 
 - *Type:* <a href="#codepipeline-event-notifier.CodePipelineEventNotifierProps">CodePipelineEventNotifierProps</a>
 
@@ -176,6 +176,7 @@ const codePipelineEventNotifierProps: CodePipelineEventNotifierProps = { ... }
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifierProps.property.targetPipeline">targetPipeline</a></code> | <code><a href="#codepipeline-event-notifier.TargetPipeline">TargetPipeline</a></code> | Pipelines that should produce notifications, selected by resource tags. |
 | <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifierProps.property.eventPattern">eventPattern</a></code> | <code>aws-cdk-lib.aws_events.EventPattern</code> | EventBridge event pattern that triggers the notifier. |
 | <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifierProps.property.maxWaitDuration">maxWaitDuration</a></code> | <code>aws-cdk-lib.Duration</code> | Maximum duration to wait for execution state changes. |
 | <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifierProps.property.timeout">timeout</a></code> | <code>aws-cdk-lib.Duration</code> | Timeout for the notifier Lambda function. |
@@ -184,6 +185,18 @@ const codePipelineEventNotifierProps: CodePipelineEventNotifierProps = { ... }
 
 ---
 
+##### `targetPipeline`<sup>Required</sup> <a name="targetPipeline" id="codepipeline-event-notifier.CodePipelineEventNotifierProps.property.targetPipeline"></a>
+
+```typescript
+public readonly targetPipeline: TargetPipeline;
+```
+
+- *Type:* <a href="#codepipeline-event-notifier.TargetPipeline">TargetPipeline</a>
+
+Pipelines that should produce notifications, selected by resource tags.
+
+---
+
 ##### `eventPattern`<sup>Optional</sup> <a name="eventPattern" id="codepipeline-event-notifier.CodePipelineEventNotifierProps.property.eventPattern"></a>
 
 ```typescript
@@ -255,5 +268,100 @@ Interval between `GetPipelineExecution` waits.
 
 ---
 
+### TargetPipeline <a name="TargetPipeline" id="codepipeline-event-notifier.TargetPipeline"></a>
+
+Selection criteria for pipelines that should trigger notifications.
+
+#### Initializer <a name="Initializer" id="codepipeline-event-notifier.TargetPipeline.Initializer"></a>
+
+```typescript
+import { TargetPipeline } from 'codepipeline-event-notifier'
+
+const targetPipeline: TargetPipeline = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#codepipeline-event-notifier.TargetPipeline.property.tags">tags</a></code> | <code><a href="#codepipeline-event-notifier.TargetPipelineTag">TargetPipelineTag</a>[]</code> | Tag filters applied to CodePipeline resources. |
+| <code><a href="#codepipeline-event-notifier.TargetPipeline.property.arns">arns</a></code> | <code>string[]</code> | Pipeline ARNs used as IAM resources for `GetPipelineExecution` and `ListTagsForResource`. |
+
+---
+
+##### `tags`<sup>Required</sup> <a name="tags" id="codepipeline-event-notifier.TargetPipeline.property.tags"></a>
+
+```typescript
+public readonly tags: TargetPipelineTag[];
+```
+
+- *Type:* <a href="#codepipeline-event-notifier.TargetPipelineTag">TargetPipelineTag</a>[]
+
+Tag filters applied to CodePipeline resources.
+
+---
+
+##### `arns`<sup>Optional</sup> <a name="arns" id="codepipeline-event-notifier.TargetPipeline.property.arns"></a>
+
+```typescript
+public readonly arns: string[];
+```
+
+- *Type:* string[]
+- *Default:* all CodePipeline resources in this account and region
+
+Pipeline ARNs used as IAM resources for `GetPipelineExecution` and `ListTagsForResource`.
+
+When set, the notifier also ignores STARTED events whose pipeline ARN is not in this list.
+
+---
+
+### TargetPipelineTag <a name="TargetPipelineTag" id="codepipeline-event-notifier.TargetPipelineTag"></a>
+
+Tag filter for selecting CodePipeline pipelines.
+
+Keys across entries are AND; values within an entry are OR.
+
+#### Initializer <a name="Initializer" id="codepipeline-event-notifier.TargetPipelineTag.Initializer"></a>
+
+```typescript
+import { TargetPipelineTag } from 'codepipeline-event-notifier'
+
+const targetPipelineTag: TargetPipelineTag = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#codepipeline-event-notifier.TargetPipelineTag.property.key">key</a></code> | <code>string</code> | Tag key that must be present on the pipeline. |
+| <code><a href="#codepipeline-event-notifier.TargetPipelineTag.property.values">values</a></code> | <code>string[]</code> | Accepted values for {@link key}. |
+
+---
+
+##### `key`<sup>Required</sup> <a name="key" id="codepipeline-event-notifier.TargetPipelineTag.property.key"></a>
+
+```typescript
+public readonly key: string;
+```
+
+- *Type:* string
+
+Tag key that must be present on the pipeline.
+
+---
+
+##### `values`<sup>Required</sup> <a name="values" id="codepipeline-event-notifier.TargetPipelineTag.property.values"></a>
+
+```typescript
+public readonly values: string[];
+```
+
+- *Type:* string[]
+
+Accepted values for {@link key}.
+
+---
+
 
 

package/README.md

@@ -1,18 +1,31 @@
-# CodePipeline Event Notifier
+# CodePipeline Event Notifier (CDK v2)
 
-[![npm version](https://img.shields.io/npm/v/codepipeline-event-notifier.svg)](https://www.npmjs.com/package/codepipeline-event-notifier)
-[![license](https://img.shields.io/npm/l/codepipeline-event-notifier.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/codepipeline-event-notifier?style=flat-square)](https://www.npmjs.com/package/codepipeline-event-notifier)
+[![license](https://img.shields.io/npm/l/codepipeline-event-notifier?style=flat-square)](https://www.npmjs.com/package/codepipeline-event-notifier)
+[![Node.js](https://img.shields.io/node/v/codepipeline-event-notifier?style=flat-square)](https://www.npmjs.com/package/codepipeline-event-notifier)
+[![build](https://img.shields.io/github/actions/workflow/status/gammarers-aws-cdk-constructs/codepipeline-event-notifier/build.yml?branch=main&label=build&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/codepipeline-event-notifier/actions/workflows/build.yml)
+
+[![View on Construct Hub](https://constructs.dev/badge?package=codepipeline-event-notifier)](https://constructs.dev/packages/codepipeline-event-notifier)
 
 CDK construct that listens to **AWS CodePipeline execution STARTED** events via EventBridge, invokes a Lambda notifier, and publishes execution state changes to an SNS topic.
 
 ## Features
 
 - **EventBridge integration**: triggers on `CodePipeline Pipeline Execution State Change` with `state=STARTED` (customizable via `eventPattern`)
+- **Tag-based pipeline selection**: required `targetPipeline.tags` filters which pipelines are notified (`ListTagsForResource`; keys are AND, values are OR)
+- **Least-privilege IAM**: CodePipeline API access is scoped to this account and region, or to `targetPipeline.arns` when set
 - **SNS notifications**: publishes execution status transitions as JSON messages (`phase`: `eventbridge` / `wait`)
 - **Execution waiting**: calls `GetPipelineExecution` until a terminal state (`SUCCEEDED` / `FAILED` / `STOPPED` / `SUPERSEDED`) or timeout
-- **Configurable props**: reuse an existing SNS topic, adjust wait interval / max wait duration / Lambda timeout, and filter events
+- **Configurable props**: reuse an existing SNS topic, adjust wait interval / max wait duration / Lambda timeout, and optionally refine the EventBridge pattern
 - **No subscriptions by default**: the SNS topic is created (or reused), but subscriptions (email/HTTP/etc.) are intentionally not configured
 
+## How it works
+
+1. EventBridge matches a CodePipeline execution state-change event (default: `state=STARTED`) and invokes the notifier Lambda.
+2. The Lambda resolves the pipeline ARN, then keeps the event only when `targetPipeline.tags` match (`ListTagsForResource`; keys are AND, values are OR) and, if set, `targetPipeline.arns` includes the pipeline.
+3. It publishes an SNS message with `phase: eventbridge`, then calls `GetPipelineExecution` until a terminal status (`SUCCEEDED` / `FAILED` / `STOPPED` / `SUPERSEDED`) or `maxWaitDuration`.
+4. Each status change (and timeout) is published with `phase: wait`. Subscribe to `notifier.topic`; this construct does not add subscriptions.
+
 ## Installation
 
 ### npm
@@ -27,6 +40,12 @@ npm install codepipeline-event-notifier
 yarn add codepipeline-event-notifier
 ```
 
+### pnpm
+
+```bash
+pnpm add codepipeline-event-notifier
+```
+
 ## Usage
 
 Instantiate `CodePipelineEventNotifier` in your CDK stack:
@@ -40,7 +59,16 @@ export class MyStack extends Stack {
   constructor(scope: Construct, id: string) {
     super(scope, id);
 
-    const notifier = new CodePipelineEventNotifier(this, 'CodePipelineEventNotifier');
+    const notifier = new CodePipelineEventNotifier(this, 'CodePipelineEventNotifier', {
+      targetPipeline: {
+        tags: [
+          {
+            key: 'Notify',
+            values: ['true'],
+          },
+        ],
+      },
+    });
 
     // Optionally subscribe to the topic created by the construct
     // notifier.topic.addSubscription(...);
@@ -66,12 +94,22 @@ export class MyStack extends Stack {
       waitInterval: Duration.seconds(30),
       maxWaitDuration: Duration.minutes(10),
       timeout: Duration.minutes(12),
+      targetPipeline: {
+        tags: [
+          {
+            key: 'Team',
+            values: ['platform', 'infra'],
+          },
+        ],
+        arns: [
+          'arn:aws:codepipeline:us-east-1:123456789012:my-pipeline',
+        ],
+      },
       eventPattern: {
         source: ['aws.codepipeline'],
         detailType: ['CodePipeline Pipeline Execution State Change'],
         detail: {
           state: ['STARTED'],
-          pipeline: ['my-pipeline'],
         },
       },
     });
@@ -83,6 +121,7 @@ export class MyStack extends Stack {
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
+| `targetPipeline` | `TargetPipeline` | *(required)* | Tag filters (`tags`) for pipelines that should notify. Optional `arns` restrict IAM and skip other pipelines. Default IAM is this account and region |
 | `topic` | `sns.ITopic` | new topic | SNS topic to publish notifications to (also exposed as `notifier.topic`) |
 | `waitInterval` | `Duration` | `10 seconds` | Interval between `GetPipelineExecution` calls |
 | `maxWaitDuration` | `Duration` | `14 minutes` | Maximum wait duration before giving up |
@@ -92,9 +131,15 @@ export class MyStack extends Stack {
 The notifier Lambda uses these environment variables (set by the construct from props):
 
 - `SNS_TOPIC_ARN` (**required**): SNS topic ARN to publish notifications to
+- `TARGET_PIPELINE_TAGS` (**required**): JSON array of `{ key, values }` tag filters
+- `TARGET_PIPELINE_ARNS` (optional): JSON array of pipeline ARNs used as an allowlist when `targetPipeline.arns` is set
 - `WAIT_INTERVAL_SECONDS` (default: `10`): wait interval in seconds
 - `MAX_WAIT_MINUTES` (default: `14`): maximum wait duration in minutes
 
+## API
+
+See the [API reference](./API.md).
+
 ## Requirements
 
 - Node.js `>= 20`