refactor(codepipeline): API cleanup. (#2982)

BREAKING CHANGE: rename CodeCommitAction.pollForSourceChanges to trigger,
and make it an enum.
* Rename S3SourceAction.pollForSourceChanges to trigger,
and make it an enum.
* Rename StageAddToPipelineProps interface to StageOptions.
* Remove the classes CloudFormationAction and CloudFormationDeployAction.

Author: skinny85

packages/@aws-cdk/aws-codepipeline-actions/README.md

@@ -65,7 +65,7 @@ const sourceAction = new codepipeline_actions.GitHubSourceAction({
   oauthToken: token.value,
   output: sourceOutput,
   branch: 'develop', // default: 'master'
-  trigger: codepipeline_actions.GitHubTrigger.Poll // default: 'WebHook', 'None' is also possible for no Source trigger
+  trigger: codepipeline_actions.GitHubTrigger.POLL // default: 'WEBHOOK', 'NONE' is also possible for no Source trigger
 });
 pipeline.addStage({
   stageName: 'Source',
@@ -99,8 +99,8 @@ pipeline.addStage({
 ```
 
 By default, the Pipeline will poll the Bucket to detect changes.
-You can change that behavior to use CloudWatch Events by setting the `pollForSourceChanges`
-property to `false` (it's `true` by default).
+You can change that behavior to use CloudWatch Events by setting the `trigger`
+property to `S3Trigger.EVENTS` (it's `S3Trigger.POLL` by default).
 If you do that, make sure the source Bucket is part of an AWS CloudTrail Trail -
 otherwise, the CloudWatch Events will not be emitted,
 and your Pipeline will not react to changes in the Bucket.
@@ -119,7 +119,7 @@ const sourceAction = new codepipeline_actions.S3SourceAction({
   bucketKey: key,
   bucket: sourceBucket,
   output: sourceOutput,
-  pollForSourceChanges: false, // default: true
+  trigger: codepipeline_actions.S3Trigger.EVENTS, // default: S3Trigger.POLL
 });
 ```
 

packages/@aws-cdk/aws-codepipeline-actions/lib/cloudformation/pipeline-actions.ts

@@ -8,7 +8,7 @@ import { Stack } from '@aws-cdk/cdk';
 /**
  * Properties common to all CloudFormation actions
  */
-export interface CloudFormationActionProps extends codepipeline.CommonActionProps {
+interface CloudFormationActionProps extends codepipeline.CommonActionProps {
   /**
    * The name of the stack to apply this action to
    */
@@ -60,7 +60,7 @@ export interface CloudFormationActionProps extends codepipeline.CommonActionProp
 /**
  * Base class for Actions that execute CloudFormation
  */
-export abstract class CloudFormationAction extends codepipeline.Action {
+abstract class CloudFormationAction extends codepipeline.Action {
   constructor(props: CloudFormationActionProps, configuration?: any) {
     super({
       ...props,
@@ -119,7 +119,7 @@ export class CloudFormationExecuteChangeSetAction extends CloudFormationAction {
 /**
  * Properties common to CloudFormation actions that stage deployments
  */
-export interface CloudFormationDeployActionProps extends CloudFormationActionProps {
+interface CloudFormationDeployActionProps extends CloudFormationActionProps {
   /**
    * IAM role to assume when deploying changes.
    *
@@ -216,7 +216,7 @@ export interface CloudFormationDeployActionProps extends CloudFormationActionPro
 /**
  * Base class for all CloudFormation actions that execute or stage deployments.
  */
-export abstract class CloudFormationDeployAction extends CloudFormationAction {
+abstract class CloudFormationDeployAction extends CloudFormationAction {
   private _deploymentRole?: iam.IRole;
   private readonly props: CloudFormationDeployActionProps;
 

packages/@aws-cdk/aws-codepipeline-actions/lib/codecommit/source-action.ts

@@ -4,6 +4,29 @@ import targets = require('@aws-cdk/aws-events-targets');
 import iam = require('@aws-cdk/aws-iam');
 import { sourceArtifactBounds } from '../common';
 
+/**
+ * How should the CodeCommit Action detect changes.
+ * This is the type of the {@link CodeCommitSourceAction.trigger} property.
+ */
+export enum CodeCommitTrigger {
+  /**
+   * The Action will never detect changes -
+   * the Pipeline it's part of will only begin a run when explicitly started.
+   */
+  NONE = 'None',
+
+  /**
+   * CodePipeline will poll the repository to detect changes.
+   */
+  POLL = 'Poll',
+
+  /**
+   * CodePipeline will use CloudWatch Events to be notified of changes.
+   * This is the default method of detecting changes.
+   */
+  EVENTS = 'Events',
+}
+
 /**
  * Construction properties of the {@link CodeCommitSourceAction CodeCommit source CodePipeline Action}.
  */
@@ -19,12 +42,11 @@ export interface CodeCommitSourceActionProps extends codepipeline.CommonActionPr
   readonly branch?: string;
 
   /**
-   * Whether AWS CodePipeline should poll for source changes.
-   * If this is `false`, the Pipeline will use CloudWatch Events to detect source changes instead.
+   * How should CodePipeline detect source changes for this Action.
    *
-   * @default false
+   * @default CodeCommitTrigger.EVENTS
    */
-  readonly pollForSourceChanges?: boolean;
+  readonly trigger?: CodeCommitTrigger;
 
   /**
    * The CodeCommit repository.
@@ -36,9 +58,13 @@ export interface CodeCommitSourceActionProps extends codepipeline.CommonActionPr
  * CodePipeline Source that is provided by an AWS CodeCommit repository.
  */
 export class CodeCommitSourceAction extends codepipeline.Action {
-  private readonly props: CodeCommitSourceActionProps;
+  private readonly repository: codecommit.IRepository;
+  private readonly branch: string;
+  private readonly createEvent: boolean;
 
   constructor(props: CodeCommitSourceActionProps) {
+    const branch = props.branch || 'master';
+
     super({
       ...props,
       category: codepipeline.ActionCategory.SOURCE,
@@ -47,34 +73,35 @@ export class CodeCommitSourceAction extends codepipeline.Action {
       outputs: [props.output],
       configuration: {
         RepositoryName: props.repository.repositoryName,
-        BranchName: props.branch || 'master',
-        PollForSourceChanges: props.pollForSourceChanges || false,
+        BranchName: branch,
+        PollForSourceChanges: props.trigger === CodeCommitTrigger.POLL,
       },
     });
 
-    this.props = props;
+    this.repository = props.repository;
+    this.branch = branch;
+    this.createEvent = props.trigger === undefined ||
+      props.trigger === CodeCommitTrigger.EVENTS;
   }
 
   protected bind(info: codepipeline.ActionBind): void {
-    if (!this.props.pollForSourceChanges) {
-      this.props.repository.onCommit(info.pipeline.node.uniqueId + 'EventRule', {
+    if (this.createEvent) {
+      this.repository.onCommit(info.pipeline.node.uniqueId + 'EventRule', {
         target: new targets.CodePipeline(info.pipeline),
-        branches: [this.props.branch || 'master']
+        branches: [this.branch],
       });
     }
 
     // https://docs.aws.amazon.com/codecommit/latest/userguide/auth-and-access-control-permissions-reference.html#aa-acp
-    const actions = [
-      'codecommit:GetBranch',
-      'codecommit:GetCommit',
-      'codecommit:UploadArchive',
-      'codecommit:GetUploadArchiveStatus',
-      'codecommit:CancelUploadArchive',
-    ];
-
     info.role.addToPolicy(new iam.PolicyStatement({
-      resources: [this.props.repository.repositoryArn],
-      actions
+      resources: [this.repository.repositoryArn],
+      actions: [
+        'codecommit:GetBranch',
+        'codecommit:GetCommit',
+        'codecommit:UploadArchive',
+        'codecommit:GetUploadArchiveStatus',
+        'codecommit:CancelUploadArchive',
+      ],
     }));
   }
 }

packages/@aws-cdk/aws-codepipeline-actions/lib/github/source-action.ts

@@ -50,11 +50,11 @@ export interface GitHubSourceActionProps extends codepipeline.CommonActionProps
   /**
    * How AWS CodePipeline should be triggered
    *
-   * With the default value "WebHook", a webhook is created in GitHub that triggers the action
-   * With "Poll", CodePipeline periodically checks the source for changes
+   * With the default value "WEBHOOK", a webhook is created in GitHub that triggers the action
+   * With "POLL", CodePipeline periodically checks the source for changes
    * With "None", the action is not triggered through changes in the source
    *
-   * @default GitHubTrigger.WebHook
+   * @default GitHubTrigger.WEBHOOK
    */
   readonly trigger?: GitHubTrigger;
 }

packages/@aws-cdk/aws-codepipeline-actions/lib/s3/source-action.ts

@@ -3,6 +3,31 @@ import targets = require('@aws-cdk/aws-events-targets');
 import s3 = require('@aws-cdk/aws-s3');
 import { sourceArtifactBounds } from '../common';
 
+/**
+ * How should the S3 Action detect changes.
+ * This is the type of the {@link S3SourceAction.trigger} property.
+ */
+export enum S3Trigger {
+  /**
+   * The Action will never detect changes -
+   * the Pipeline it's part of will only begin a run when explicitly started.
+   */
+  NONE = 'None',
+
+  /**
+   * CodePipeline will poll S3 to detect changes.
+   * This is the default method of detecting changes.
+   */
+  POLL = 'Poll',
+
+  /**
+   * CodePipeline will use CloudWatch Events to be notified of changes.
+   * Note that the Bucket that the Action uses needs to be part of a CloudTrail Trail
+   * for the events to be delivered.
+   */
+  EVENTS = 'Events',
+}
+
 /**
  * Construction properties of the {@link S3SourceAction S3 source Action}.
  */
@@ -20,15 +45,14 @@ export interface S3SourceActionProps extends codepipeline.CommonActionProps {
   readonly bucketKey: string;
 
   /**
-   * Whether AWS CodePipeline should poll for source changes.
-   * If this is `false`, the Pipeline will use CloudWatch Events to detect source changes instead.
-   * Note that if this is `false`, you need to make sure to include the source Bucket in a CloudTrail Trail,
+   * How should CodePipeline detect source changes for this Action.
+   * Note that if this is S3Trigger.EVENTS, you need to make sure to include the source Bucket in a CloudTrail Trail,
    * as otherwise the CloudWatch Events will not be emitted.
    *
-   * @default true
+   * @default S3Trigger.POLL
    * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/log-s3-data-events.html
    */
-  readonly pollForSourceChanges?: boolean;
+  readonly trigger?: S3Trigger;
 
   /**
    * The Amazon S3 bucket that stores the source code
@@ -46,6 +70,8 @@ export class S3SourceAction extends codepipeline.Action {
   private readonly props: S3SourceActionProps;
 
   constructor(props: S3SourceActionProps) {
+    const pollForSourceChanges = props.trigger && props.trigger === S3Trigger.POLL;
+
     super({
       ...props,
       category: codepipeline.ActionCategory.SOURCE,
@@ -55,15 +81,15 @@ export class S3SourceAction extends codepipeline.Action {
       configuration: {
         S3Bucket: props.bucket.bucketName,
         S3ObjectKey: props.bucketKey,
-        PollForSourceChanges: props.pollForSourceChanges,
+        PollForSourceChanges: pollForSourceChanges,
       },
     });
 
     this.props = props;
   }
 
   protected bind(info: codepipeline.ActionBind): void {
-    if (this.props.pollForSourceChanges === false) {
+    if (this.props.trigger === S3Trigger.EVENTS) {
       this.props.bucket.onCloudTrailPutObject(info.pipeline.node.uniqueId + 'SourceEventRule', {
         target: new targets.CodePipeline(info.pipeline),
         paths: [this.props.bucketKey]

packages/@aws-cdk/aws-codepipeline-actions/test/cloudformation/test.cloudformation-pipeline-actions.ts

@@ -31,7 +31,7 @@ export = {
     actionName: 'source',
     output: sourceOutput,
     repository: repo,
-    pollForSourceChanges: true,
+    trigger: cpactions.CodeCommitTrigger.POLL,
   });
   pipeline.addStage({
     stageName: 'source',