feat(aws-s3): New method addToPipeline on Bucket.

See #265 for the discussion about this feature.

packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-code-deploy.ts

@@ -33,9 +33,7 @@ const pipeline = new codepipeline.Pipeline(stack, 'Pipeline', {
 });
 
 const sourceStage = new codepipeline.Stage(stack, 'Source', { pipeline });
-const sourceAction = new s3.PipelineSource(stack, 'S3Source', {
-    stage: sourceStage,
-    bucket,
+const sourceAction = bucket.addToPipeline(sourceStage, 'S3Source', {
     bucketKey: 'application.zip',
     artifactName: 'SourceOutput',
 });

packages/@aws-cdk/aws-s3/README.md

@@ -99,6 +99,16 @@ const sourceAction = new s3.PipelineSource(this, 'S3Source', {
 // use sourceAction.artifact as the inputArtifact to later Actions...
 ```
 
+You can also add the Bucket to the Pipeline directly:
+
+```ts
+// equivalent to the code above:
+const sourceAction = sourceBucket.addToPipeline(sourceStage, 'CodeCommit', {
+    bucketKey: 'path/to/file.zip',
+    artifactName: 'SourceOutput',
+});
+```
+
 ### Importing and Exporting Buckets
 
 You can create a `Bucket` construct that represents an external/existing/unowned bucket by using the `Bucket.import` factory method.

packages/@aws-cdk/aws-s3/lib/bucket.ts

@@ -1,10 +1,12 @@
+import actions = require('@aws-cdk/aws-codepipeline-api');
 import iam = require('@aws-cdk/aws-iam');
 import kms = require('@aws-cdk/aws-kms');
 import { IBucketNotificationDestination } from '@aws-cdk/aws-s3-notifications';
 import cdk = require('@aws-cdk/cdk');
 import { BucketPolicy } from './bucket-policy';
 import { BucketNotifications } from './notifications-resource';
 import perms = require('./perms');
+import { CommonPipelineSourceProps, PipelineSource } from './pipeline-action';
 import { LifecycleRule } from './rule';
 import { BucketArn, BucketDomainName, BucketDualStackDomainName, BucketName, cloudformation } from './s3.generated';
 import { parseBucketArn, parseBucketName, validateBucketName } from './util';
@@ -99,6 +101,23 @@ export abstract class BucketRef extends cdk.Construct {
         };
     }
 
+    /**
+     * Convenience method for creating a new {@link PipelineSource} Action,
+     * and adding it to the given Stage.
+     *
+     * @param stage the Pipeline Stage to add the new Action to
+     * @param name the name of the newly created Action
+     * @param props the properties of the new Action
+     * @returns the newly created {@link PipelineSource} Action
+     */
+    public addToPipeline(stage: actions.IStage, name: string, props: CommonPipelineSourceProps): PipelineSource {
+        return new PipelineSource(this.parent!, name, {
+            stage,
+            bucket: this,
+            ...props,
+        });
+    }
+
     /**
      * Adds a statement to the resource policy for a principal (i.e.
      * account/role/service) to perform actions on this bucket and/or it's

packages/@aws-cdk/aws-s3/lib/pipeline-action.ts

@@ -3,22 +3,21 @@ import cdk = require('@aws-cdk/cdk');
 import { BucketRef } from './bucket';
 
 /**
- * Construction properties of the {@link PipelineSource S3 source Action}.
+ * Common properties for creating {@link PipelineSource} -
+ * either directly, through its constructor,
+ * or through {@link BucketRef#addToPipeline}.
  */
-export interface PipelineSourceProps extends actions.CommonActionProps {
+export interface CommonPipelineSourceProps {
     /**
      * The name of the source's output artifact. Output artifacts are used by CodePipeline as
      * inputs into other actions.
      */
     artifactName: string;
 
     /**
-     * The Amazon S3 bucket that stores the source code
-     */
-    bucket: BucketRef;
-
-    /**
-     * The key within the S3 bucket that stores the source code
+     * The key within the S3 bucket that stores the source code.
+     *
+     * @example 'path/to/file.zip'
      */
     bucketKey: string;
 
@@ -31,6 +30,16 @@ export interface PipelineSourceProps extends actions.CommonActionProps {
     pollForSourceChanges?: boolean;
 }
 
+/**
+ * Construction properties of the {@link PipelineSource S3 source Action}.
+ */
+export interface PipelineSourceProps extends CommonPipelineSourceProps, actions.CommonActionProps {
+    /**
+     * The Amazon S3 bucket that stores the source code
+     */
+    bucket: BucketRef;
+}
+
 /**
  * Source that is provided by a specific Amazon S3 object.
  */