codepipeline 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c512eabee2e9506733bde41ee89c2b83f03c5a45ea4e5abb31a96cee369cbe89
-  data.tar.gz: 1920d0720610d8388ac4502a24a794ead85eec0ecbde04100f9e9bc7265c99e1
+  metadata.gz: d01768e8b5b7fd0c0df102e9722aa1142465dc4cb558b1ba8b89729f22d5b190
+  data.tar.gz: de37faf1c520534e98c098985b9c8aea780c19c31caa969b80c9b1da2861dc13
 SHA512:
-  metadata.gz: 626e1e6bede33a5b1fec8b774b015334b9f8d996f335f778f92eef8a538395266c4a205eedd033ccd0cefcb15b59f3a30ecd2c8b7d5ee4cd43c3397d295d77e2
-  data.tar.gz: f6f14e543a7275a3deb546031bd65444d1f3191fae20f3c1e395ef3aadfd6005406d5840dfb26214ad8bca5b20dcab34d0fe679add107fabab72be09c3229601
+  metadata.gz: 7bb42521c93b928e9454c2cf9d261bf2a3c0de7c2bbcd4c5514a91be7175f26051a3fdde0c3f8c120c3d92dc1d4aa8d3ff28f11da080b944214b6fa8e8222a68
+  data.tar.gz: 10ae3dd56585edc11cd76adbaef808afdcdfdf28eb9a2935a1fa1e158b9a187bb238b8a6c058984ce91bf9cd25dc830617353fba99fcee20f800e42d6e65952c

data/.codebuild/buildspec.yml

@@ -0,0 +1,9 @@
+version: 0.2
+
+phases:
+  build:
+    commands:
+      - echo Build started on `date`
+      - sed -i '/BUNDLED WITH/Q' Gemfile.lock # hack to fix bundler issue: allow different versions of bundler to work
+      - bundle
+      - bundle exec rspec

data/.codebuild/project.rb

@@ -0,0 +1,4 @@
+github_url("https://github.com/tongueroo/codepipeline")
+linux_image("aws/codebuild/ruby:2.5.3-1.7.0")
+triggers(webhook: true)
+local_cache(false)

data/.codebuild/settings.yml

@@ -0,0 +1,9 @@
+base:
+  # stack_naming:
+  #   append_env: true # default false
+
+development:
+  # aws_profile: dev_profile
+
+production:
+  # aws_profile: prod_profile

data/CHANGELOG.md

@@ -3,6 +3,9 @@
 All notable changes to this project will be documented in this file.
 This project *tries* to adhere to [Semantic Versioning](http://semver.org/), even before v1.0.
 
+## [0.3.0]
+- update docs and cli help
+
 ## [0.2.1]
 - fix different branch check
 

data/README.md

@@ -1,5 +1,6 @@
 # Codepipeline
 
+![Build Status](https://codebuild.us-west-2.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiM3hGMlViMUtRRS9maitXVnhPNUp2ZFE3eUkzV0doNG5OR0lRRGtNOVBiWDVsb0tjY2dTVnhHamJOSzZRYU5aaW9FOS9peEUwVHBVUzk3cXVjd2FqcHFNPSIsIml2UGFyYW1ldGVyU3BlYyI6InNDdzUzVmRCd0FHSjBrTnQiLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=master)
 [![Gem Version](https://badge.fury.io/rb/codepipeline.png)](http://badge.fury.io/rb/codepipeline)
 
 The codepipeline tool provides a DSL to create a CodePipeline project with some reasonable defaults.
@@ -26,9 +27,8 @@ The CLI tool also detects and tasks in the current folder's Rakefile and delegat
 ```ruby
 stage "Source" do
   github(
-    source: "tongueroo/demo-cb",
-    branch: "master",
-    auth_token: ssm("/codebuild/github/tongueroo/oauth_token")
+    source: "tongueroo/demo-ufo",
+    auth_token: ssm("/github/user/token")
   )
 end
 stage "DeployStacks" do
@@ -38,7 +38,7 @@ stage "DeployStacks" do
 end
 ```
 
-More [DSL docs](docs/dsl)
+More [DSL docs](https://codepipeline.org/docs/dsl/)
 
 ## Installation
 

data/docs/_docs/conventions.md

@@ -14,7 +14,7 @@ It will set the pipeline name by inferring the name of the parent folder.  For e
 
 The pipeline is named `demo`. You can override this easily by providing a pipeline name.
 
-    cd deploy my-pipeline # explicitly use my-pipeline as pipeline name
+    pipe deploy my-pipeline # explicitly use my-pipeline as pipeline name
 
 The pipeline is named `my-pipeline`
 
@@ -28,16 +28,15 @@ The pipeline is named `my-pipeline-2`.
 
 ## Settings append_env option
 
-If the append_env is configured in the [Settings]({% link _docs/settings.md %}).
+If the append_env is configured in the [Settings]({% link _docs/settings.md %}), then the `PIPE_ENV` is added to the pipeline name. For example: `demo-development` instead of `demo`.
 
 ## Stack Name
 
-The CloudFormation stack name which creates the CodePipeline related resources is named the same as the pipeline name with `-cb` appended to the stack name. Examples:
+The CloudFormation stack name which creates the CodePipeline related resources is named the same as the pipeline name with `-pipe` appended to the stack name. Examples:
 
 Pipeline Name | Stack Name
 --- | ---
-demo | demo-cb
-demo-unit | demo-unit-cb
-demo-web-unit | demo-web-unit-cb
+demo | demo-pipe
+my-app | my-app-pipe
 
 {% include prev_next.md %}

data/docs/_docs/deploy.md

@@ -3,7 +3,7 @@ title: Deploy
 nav_order: 4
 ---
 
-The pipeline is generated from the DSL and created with CloudFormation. By default, the files that the DSL evaluates are:
+The pipeline is generated from the DSL and created with CloudFormation. The files that the DSL evaluates are in the `.codepipeline` folder:
 
     .codepipeline/pipeline.rb
     .codepipeline/role.rb
@@ -12,7 +12,7 @@ The pipeline is generated from the DSL and created with CloudFormation. By defau
 
 To create the CodePipeline pipeline, you run:
 
-    codepipeline deploy
+    pipe deploy
 
 You'll see output that looks something like this:
 
@@ -46,23 +46,11 @@ By default, the pipeline name is inferred and is the parent folder that you are
 
 ## Specify Git Branch
 
-It is useful to build pipelines with different source git branches. You can pass a `--branch` option to the `pipe deploy` command. In the `.codepipeline/pipeline.rb` use the DSL method `branch` to reference it.  Example:
+It is useful to build pipelines with different source git branches. You can pass a `--branch` option to the `pipe deploy` command. The cli `—-branch` option always takes the highest precedence. Example:
 
     pipe deploy my-pipeline --branch my-branch
 
-.codepipeline/pipeline.rb
-
-```ruby
-stage "Source" do
-  github(
-    source: "tongueroo/demo-test",
-    auth_token: ssm("/github/user/token")
-  )
-end
-```
-
-Note: Currently CodePipeline does not support specifying a source git branch at runtime. We can only specific it as part of the pipeline definition.
-
+Note: When you specify a branch the codepipeline tool actually first updates the pipeline before starting the pipeline execution. This is done because CodePipeline does not natively support specifying the branch. It is discussed more here: [Using Different Branches]({% link _docs/examples/different-branches.md %}).
 
 ## CLI Reference
 

data/docs/_docs/dsl/approve.md

@@ -17,11 +17,11 @@ stage "Approve" do
 end
 ```
 
-In this case, the codepipeline tool creates and manages the SNS topic for you.
+With CodePipeline, an SNS topic is required to be associated with the Approval Action. In the case of a String form, the codepipeline tool will automatically create and manage the SNS topic associated with the `approve` declaration.
 
 ## Simplified Configuration Hash
 
-If the approve method provided a Hash with the `notification_arn` and `custom_data` then the codepipeline tool will set the `configuration` directly. Example:
+If the `approve` method is provided a Hash with the `notification_arn` and `custom_data`, then the codepipeline tool will set the `configuration` directly. Example:
 
 ```ruby
 stage "Approve" do
@@ -32,7 +32,7 @@ stage "Approve" do
 end
 ```
 
-In this case, the codepipeline will *not* create an SNS Topic as we're using an existing SNS topic.
+In this case, the codepipeline will *not* create an SNS Topic as we're have specified an existing SNS topic.
 
 ## Full Config
 

data/docs/_docs/dsl/pipeline/action.md

@@ -5,7 +5,7 @@ categories: dsl-pipeline
 nav_order: 11
 ---
 
-The `action` method is a general way to add Actions to your pipeline Stages. Generally, it is recommended to use the helper methods like [codebuild]({% link _docs/dsl/pipeline/codebuild.md %}) and [approve]({% link _docs/dsl/approve.md %}) when possible as it makes the code concise.  Here's an example of a pipeline using the general `action` method.
+The `action` method is a general way to add Actions to pipeline Stages. Generally, it is recommended to use the helper methods like [codebuild]({% link _docs/dsl/pipeline/codebuild.md %}) and [approve]({% link _docs/dsl/approve.md %}) when possible as it makes the code concise.  Here's an example of a pipeline using the general `action` method.
 
 ```ruby
 stage "Build" do

data/docs/_docs/dsl/pipeline/prefix-and-suffix.md

@@ -26,7 +26,7 @@ stage "Deploy" do
 end
 ```
 
-The Action names in the Stage would be a little lengthy and look like this: DemoWebDeploy, DemoClockDeploy, DemoWorkerDeploy. If you wanted to use shorter names, you'd need to use the [Simpified Hash Form]({% link _docs/dsl/pipeline/codebuild.md %}).
+The resulting Action names in the Stage would be a little lengthy and look like this: `DemoWebDeploy`, `DemoClockDeploy`, `DemoWorkerDeploy`. If you wanted to use shorter names like `Web`, `Clock`, and `Worker`, you'd need to use the [Simpified Hash Form]({% link _docs/dsl/pipeline/codebuild.md %}).
 
 ```ruby
 # Example 2

data/docs/_docs/dsl/pipeline.md

@@ -7,7 +7,7 @@ nav_order: 10
 
 The pipeline DSL allows you to define the stages and actions within that stage with only a few lines of code. In the Quick Start, we define a very short pipeline for as a simple example.  Here we'll show more of the DSL power.
 
-```
+```ruby
 stage "Source" do
   github(
     source: "tongueroo/demo-test",
@@ -21,7 +21,7 @@ stage "Build" do
 end
 
 stage "Approve" do
-  approve
+  approve("Approve this deploy")
 end
 
 stage "Deploy" do

data/docs/_docs/dsl/sns.md

@@ -13,10 +13,10 @@ For most cases, the default SNS topic should suffice. However, if you wish to co
 ```ruby
 display_name "my display_name"
 kms_master_key_id "String"
-# subscription([{
-#   endpoint: '',
-#   protocol: ','
-# }])
+subscription([{
+  endpoint: 'my@email.com',
+  protocol: 'email', # protocol values: https://docs.aws.amazon.com/sns/latest/api/API_Subscribe.html
+}])
 topic_name "string", # Recommend not setting because update requires: Replacement. Allow CloudFormation to set it so 2 pipelines dont have same SNS Topic name that collides
 ```
 

data/docs/_docs/dsl.md

@@ -3,11 +3,37 @@ title: CodePipeline DSL
 nav_order: 8
 ---
 
-CodePipeline provides a simple yet powerful DSL to create CodePipeline related resources.  Here are some examples of resources it can create:
+CodePipeline provides a simple yet powerful DSL to create CodePipeline related resources.  Here's an example:
+
+```ruby
+stage "Source" do
+  github(
+    source: "tongueroo/demo-test",
+    auth_token: ssm("/github/user/token")
+  )
+end
+
+stage "Build" do
+  codebuild "demo1", "demo2"
+  codebuild "demo3"
+end
+
+stage "Approve" do
+  approve("Approve this deploy")
+end
+
+stage "Deploy" do
+  codebuild "deploy"
+end
+```
+
+Here are some examples of resources it can create:
 
 * [pipeline]({% link _docs/dsl/pipeline.md %}): The CodePipeline pipeline. This is required.
 * [iam role]({% link _docs/dsl/role.md %}): The IAM role associated with the CodePipeline pipeline.
 * [webhook]({% link _docs/dsl/webhook.md %}): The webhook associated with the CodePipeline pipeline.
-* [schedule]({% link _docs/dsl/schedule.md %}): An CloudWatch Event rule. The rule triggers the pipeline to start on a scheduled basis.
+* [schedule]({% link _docs/dsl/schedule.md %}): An CloudWatch Event rule: triggers the pipeline to start on a scheduled basis.
+* [approve]({% link _docs/dsl/approve.md %}): An manual approval action step.
+* [sns topic]({% link _docs/dsl/sns.md %}): The SNS Topic associated with the approval step. This is optional and provides a way to customize the SNS topic if needed.
 
 {% include prev_next.md %}

data/docs/_docs/ecs-deploy.md

@@ -1,11 +1,9 @@
 ---
 title: 'ECS Deploy: Codebuild ufo ship vs CodePipeline ECS Deploy'
-nav_order: 20
+nav_order: 21
 ---
 
-CodePipeline comes with many [Action Type Integrations](https://docs.aws.amazon.com/codepipeline/latest/userguide/integrations-action-type.html).  One of the Integrations is [Amazon Elastic Container Service](https://docs.aws.amazon.com/codepipeline/latest/userguide/integrations-action-type.html#integrations-deploy) deployment.
-
-Currently, it is recommended to use [codebuild and ufo](https://codebuild.cloud/docs/examples/ecs/) to handle deployment to ECS though.  We discuss the main reasons below.
+CodePipeline comes with many [Action Type Integrations](https://docs.aws.amazon.com/codepipeline/latest/userguide/integrations-action-type.html).  One of the Integrations is [Amazon Elastic Container Service](https://docs.aws.amazon.com/codepipeline/latest/userguide/integrations-action-type.html#integrations-deploy) deployment. It is recommended to use [codebuild and ufo](https://codebuild.cloud/docs/examples/ecs/) to handle deployment to ECS though.  We discuss some reasons below.
 
 ## Timeout
 
@@ -19,6 +17,6 @@ By using a codebuild project, we have control over the timeout.
 
 The way the current CodePipeline ECS Deploy Action works is that it pulls down the current ECS task definition that ECS service is using. It then replaces the image property on it. Last, it then updates the ECS service with the newly built Docker image.
 
-The [ufo tool] is more powerful.  The `ufo ship` command also handles creating the [ELB Load Balancer]((https://ufoships.com/docs/extras/load-balancer/)) and a vanity [Route53 endpoint](https://ufoships.com/docs/extras/route53-support/) for us.  Also, it keeps task definition codified.
+The [ufo tool](https://ufoships.com) is more powerful.  The `ufo ship` command also handles creating the [ELB Load Balancer]((https://ufoships.com/docs/extras/load-balancer/)) and a vanity [Route53 endpoint](https://ufoships.com/docs/extras/route53-support/) for us.  Also, it keeps task definitions codified.
 
 {% include prev_next.md %}

data/docs/_docs/examples/codebuild-project.md

@@ -0,0 +1,21 @@
+---
+title: Create CodeBuild Project
+nav_text: Create CodeBuild
+categories: examples
+nav_order: 18
+---
+
+It is common to use codebuild as a Stage Action in the pipeline. Here's are instructions to quickly create a codebuild project.
+
+We'll use the [codebuild.cloud](https://codebuild.cloud) tool to help with this. Here are the commands.
+
+    cb init # generates starter .codebuild files including the buildspec.yml
+    # commit and yours the .codebuild files
+    git add .codebuild
+    git commit -m 'add .codebuild files'
+    git push
+    pipe deploy demo # creates a codebuild project
+
+There's also an example where we quickly create 4 test codebuild projects here: [Multiple CodeBuild Projects](https://codepipeline.org/docs/examples/multiple-codebuild-projects/).
+
+{% include prev_next.md %}

data/docs/_docs/examples/different-branches.md

@@ -2,7 +2,7 @@
 title: Using Different Branches
 nav_text: Different Branches
 categories: examples
-nav_order: 18
+nav_order: 19
 ---
 
 CodePipeline currently does not supports starting the pipeline execution with different branches natively. To get around this, we can:
@@ -28,7 +28,7 @@ You might normally set the branch option in your pipeline.rb. Example:
 ```ruby
 stage "Source" do
   github(
-    source: "tongueroo/demo-cb",
+    source: "user/repo",
     auth_token: ssm("/github/user/token")
   )
 end

data/docs/_docs/examples/multiple-codebuild-projects.md

@@ -1,8 +1,8 @@
 ---
 title: Multiple CodeBuild Projects
-nav_text: CodeBuild Projects
+nav_text: Multiple CodeBuild
 categories: examples
-nav_order: 19
+nav_order: 20
 ---
 
 In this example guide, we'll create a couple of test CodeBuild projects and quickly connect them up to a pipeline.
@@ -22,11 +22,11 @@ First, you can use `cb init` create some starter ``.codebuild` files.
 
 Then create the 4 CodeBuild projects for testing:
 
-    for i in 1 2 3 4 ; do cb deploy demo$i --no-wait ; done
+    for i in 1 2 3 4 ; do pipe deploy demo$i --no-wait ; done
 
 ## CodePipeline
 
-Let's define a pipeline now with the 4 CodeBuild test projects. First, use `pipe init` to create the starter ``.codepipeline` files. Update your `pipeline.rb` with the following:
+Let's define a pipeline now with the 4 CodeBuild test projects. First, use `pipe init` to create the starter `.codepipeline` files. Update your `pipeline.rb` with the following:
 
 codepipeline/pipeline.rb:
 
@@ -53,6 +53,8 @@ Last, start the pipeline execution:
 
     pipe start
 
-That's it!
+That's it!  The pipeline will look like this:
+
+![](/img/docs/multiple-codebuild-projects-pipeline.png)
 
 {% include prev_next.md %}

data/docs/_docs/next-steps.md

@@ -1,6 +1,6 @@
 ---
 title: Next Steps
-nav_order: 22
+nav_order: 23
 ---
 
 Hopefully, you have a good feel for how codepipeline works now. From here, there are a few resources that can help you continue along:

data/docs/_docs/settings.md

@@ -21,8 +21,8 @@ The base settings are common and used for all the environments. The other enviro
 
 ## Example
 
-    cb deploy # will use the development settings since development is the default
-    PIPE_ENV=production cb deploy # will use the production settings
+    pipe deploy # will use the development settings since development is the default
+    PIPE_ENV=production pipe deploy # will use the production settings
 
 ## Options
 

data/docs/_docs/structure.md

@@ -0,0 +1,25 @@
+---
+title: Structure
+nav_order: 9
+---
+
+The `pipe init` command generates the initial directory structure that looks like this:
+
+    .codepipeline
+    ├── pipeline.rb
+    ├── role.rb
+    ├── schedule.rb
+    ├── settings.yml
+    └── webhook.rb
+
+The table below states the purpose of each file:
+
+File / Directory  | Description
+------------- | -------------
+pipeline.rb  | The pipeline defintion. More info: [Pipeline DSL]({% link _docs/dsl/pipeline.md %})
+role.rb  | The IAM role defintion. More info: [Role DSL]({% link _docs/dsl/role.md %})
+schedule.rb  | The schedule defintion. More info: [Schedule DSL]({% link _docs/dsl/schedule.md %})
+settings.yml  | Settings for the codepipeline tool. More info: [Settings]({% link _docs/settings.md %})
+webhook.rb  | The webhook defintion. More info: [Webhook DSL]({% link _docs/dsl/webhook.md %})
+
+{% include prev_next.md %}

data/docs/_includes/commands.html

@@ -26,6 +26,7 @@ pipe delete
 {% highlight sh %}
 .codepipeline
 ├── pipeline.rb
+├── role.rb
 ├── schedule.rb
 ├── settings.yml
 └── webhook.rb
@@ -42,7 +43,7 @@ pipe deploy # infers the pipeline name from the parent folder
 pipe deploy pipeline-name # explicitly specify pipeline name
 
 pipe start # infers the pipeline name from the parent folder
-pipe start demo-project # explicitly specify pipeline name
+pipe start pipeline-name # explicitly specify pipeline name
 {% endhighlight %}
                                 </div>
                             </div>
@@ -52,8 +53,8 @@ pipe start demo-project # explicitly specify pipeline name
 {% highlight ruby %}
 stage "Source" do
   github(
-    source: "tongueroo/demo-cb",
-    auth_token: ssm("/codebuild/github/tongueroo/oauth_token")
+    source: "user/repo",
+    auth_token: ssm("/github/user/token")
   )
 end
 stage "DeployStacks" do

data/docs/_includes/example.html

@@ -0,0 +1,12 @@
+<section id="timeline">
+    <div class="container">
+        <div class="row">
+            <div class="col-lg-12 text-center">
+                <h2 class="section-heading">Demo Pipeline</h2>
+            </div>
+        </div>
+        <div class="row justify-content-center project-pipeline-splash">
+            <img src="/img/docs/multiple-codebuild-projects-pipeline.png" />
+        </div>
+    </div>
+</section>

data/docs/_includes/subnav.html

@@ -4,6 +4,7 @@
     <li><a href="{% link docs.md %}">Docs</a>
       <ul class="docs">
         <li><a href="{% link _docs/install.md %}">Install</a></li>
+        <li><a href="{% link _docs/structure.md %}">Structure</a></li>
         <li><a href="{% link _docs/deploy.md %}">Deploy</a></li>
         <li><a href="{% link _docs/start.md %}">Start</a></li>
         <li><a href="{% link _docs/settings.md %}">Settings</a></li>

data/docs/_sass/_main.scss

@@ -361,4 +361,10 @@ blockquote {
   padding: 12px 24px;
   margin: 0 0 24px;
   border-left: 5px solid #eee;
+}
+
+.project-pipeline-splash {
+  img {
+    max-width: 700px;
+  }
 }

data/docs/docs.md

@@ -5,20 +5,20 @@ nav_order: 2
 
 ## What is codepipeline?
 
-Codepipeline is a tool that simplifies creating and managing [AWS CodePipeline](https://aws.amazon.com/codepipeline/) resources. It provides a DSL to create a Pipeline, Scheduled Event, IAM Role, and Webhook.
+The codepipeline tool provides a DSL that simplifies creating and managing [AWS CodePipeline](https://aws.amazon.com/codepipeline/) resources. You create a Pipeline, Scheduled Event, IAM Role, and Webhook.
 
-The DSL is essentially a wrapper to the CloudFormation for resources like the [CodePipeline Project resource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codepipeline-pipeline.html). This means you can **fullly control** and customize of the CodePipeline resources.
+The [codepipeline DSL]({% link _docs/dsl.md %}) is essentially a wrapper to CloudFormation for resources like the [CodePipeline Project resource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codepipeline-pipeline.html). This means you can **fully control** and customize of the CodePipeline resources.
 
 ## Usage Scenarios
 
 Here are some ways to use CodePipeline:
 
-* continously integration and delivery
-* deploying code
-* building artifacts
+* continuous integration and delivery
+* visualizing the deploy flow
+* building artifacts: Docker images, AMIs, jars, s3 objects, etc
 
 ## CodePipeline vs CodeBuild
 
-CodePipeline is a higher level software than CodeBuild. CodeBuild is a managed build service and you can use it to automated tasks. CodePipeline helps you visualize the steps and puts it altogether.
+CodePipeline is higher-level software than CodeBuild. CodeBuild is a managed build service, and you can use it to automate tasks. CodePipeline helps you sequence the steps and puts it all together; providing you with a high-level visualization.
 
 {% include prev_next.md %}

data/docs/index.html

@@ -22,6 +22,8 @@ subnav: false
         </div>
     </header>
 
+    {% include example.html %}
+
     {% include commands.html %}
 
     <section class="cta">

data/docs/quick-start.md

@@ -33,13 +33,13 @@ Create the starter .codepipeline files in the project.
 
     pipe init # generates starter .codepipeline files
 
-An important generated file `.codepipeline/pipeline.rb`. The starter file looks something like this:
+An important generated file is `.codepipeline/pipeline.rb`. The starter file looks something like this:
 
 ```ruby
 stage "Source" do
   github(
-    source: "tongueroo/demo-test",
-    auth_token: ssm("/codebuild/github/tongueroo/oauth_token")
+    source: "user/repo", # replace with your repo
+    auth_token: ssm("/github/user/token")
   )
 end
 
@@ -48,14 +48,14 @@ stage "Build" do
 end
 ```
 
-This is a short pipeline that has 2 stages:
+The pipeline definition is much shorter than typical CloudFormation code. In this short pipeline, there are 2 stages:
 
-1. downloads the source code from Gitub and uploads it to S3 as a output artifact
-2. starts some codebuild project with the code that was previously uploaded to s3 as the output artifact
+1. Downloads the source code from Gitub and uploads it to S3 as an output artifact.
+2. Starts some codebuild project with the code that was previously uploaded to s3 as the input artifact.
 
-Note: you have to create the codebuild projects as a prequisite.  The [codebuild.cloud](https://codebuild.cloud) tool helps with this.
+Note, you need to have a codebuild project already created as a prerequisite. The example instructions for that are here: [Create CodeBuild Project]({% link _docs/examples/codebuild-project.md %}).
 
-To define a pipeline, it much shorter than typical CloudFormation code. You can then create the pipeline with a single command:
+You can then deploy or create the pipeline with a single command:
 
     pipe deploy
 

data/docs/support.md

@@ -1,6 +1,6 @@
 ---
 title: Support
-nav_order: 21
+nav_order: 22
 ---
 
 ## Getting Help

data/lib/codepipe/help/deploy.md

@@ -0,0 +1,54 @@
+Examples:
+
+    codepipe deploy
+    codepipe deploy demo # explicitly specify pipeline name
+    codepipe deploy demo -b mybranch # specify git branch
+
+The pipeline is generated from the DSL and created with CloudFormation. The files that the DSL evaluates are in the `.codepipeline` folder:
+
+    .codepipeline/pipeline.rb
+    .codepipeline/role.rb
+    .codepipeline/schedule.rb
+    .codepipeline/webhook.rb
+
+To create the CodePipeline pipeline, you run:
+
+    pipe deploy
+
+You'll see output that looks something like this:
+
+    $ pipe deploy
+    Generated CloudFormation template at /tmp/codepipeline.yml
+    Deploying stack demo-pipe with CodePipeline project demo
+    Creating stack demo-pipe. Check CloudFormation console for status.
+    Stack name demo-pipe status CREATE_IN_PROGRESS
+    Here's the CloudFormation url to check for more details https://console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks
+    Waiting for stack to complete
+    04:14:03AM CREATE_IN_PROGRESS AWS::CloudFormation::Stack demo-pipe User Initiated
+    04:14:06AM CREATE_IN_PROGRESS AWS::IAM::Role IamRole
+    04:14:07AM CREATE_IN_PROGRESS AWS::IAM::Role IamRole Resource creation Initiated
+    04:14:25AM CREATE_COMPLETE AWS::IAM::Role IamRole
+    04:14:28AM CREATE_IN_PROGRESS AWS::CodePipeline::Pipeline Pipeline
+    04:14:29AM CREATE_IN_PROGRESS AWS::CodePipeline::Pipeline Pipeline Resource creation Initiated
+    04:14:29AM CREATE_COMPLETE AWS::CodePipeline::Pipeline Pipeline
+    04:14:31AM CREATE_IN_PROGRESS AWS::CodePipeline::Webhook Webhook
+    04:14:33AM CREATE_IN_PROGRESS AWS::CodePipeline::Webhook Webhook Resource creation Initiated
+    04:14:33AM CREATE_COMPLETE AWS::CodePipeline::Webhook Webhook
+    04:14:35AM CREATE_COMPLETE AWS::CloudFormation::Stack demo-pipe
+    Stack success status: CREATE_COMPLETE
+    Time took for stack deployment: 35s.
+    $
+
+## Explicit Pipeline Name
+
+By default, the pipeline name is inferred and is the parent folder that you are within.  You can explicitly specify the pipeline name as the first CLI argument:
+
+    pipe deploy my-pipeline
+
+## Specify Git Branch
+
+It is useful to build pipelines with different source git branches. You can pass a `--branch` option to the `pipe deploy` command. The cli `—-branch` option always takes the highest precedence. Example:
+
+    pipe deploy my-pipeline --branch my-branch
+
+Note: When you specify a branch the codepipeline tool actually first updates the pipeline before starting the pipeline execution. This is done because CodePipeline does not natively support specifying the branch. It is discussed more here: [Using Different Branches]({% link _docs/examples/different-branches.md %}).

data/lib/codepipe/help/start.md

@@ -0,0 +1,20 @@
+You can start a pipeline with the `pipe start` command. Here's an example:
+
+    $ pipe start
+    Pipeline started: demo
+    Please check the CodePipeline console for the status.
+    CodePipeline Console: https://us-west-2.console.aws.amazon.com/codesuite/codepipeline/pipelines/demo/view
+    Pipeline cli: aws codepipeline get-pipeline-execution --pipeline-execution-id 02579d64-9271-4edc-aa45-bc9629d732bb --pipeline-name demo
+    $
+
+## Specifying Code Branch
+
+If you would like start a build using a specific code branch you can use the `--branch` or `-b` option.  Example:
+
+    pipe start -b feature-branch
+
+## AWS CLI Equivalent
+
+The `pipe start` command is a simple wrapper to the AWS API with the ruby sdk. You can also start pipelines with the `aws codepipeline` cli.  Here's the equivalent CLI command:
+
+    aws codepipeline start-pipeline-execution --name demo

data/lib/codepipe/version.rb

@@ -1,3 +1,3 @@
 module Codepipe
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: codepipeline
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Tung Nguyen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-30 00:00:00.000000000 Z
+date: 2019-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -243,6 +243,9 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".codebuild/buildspec.yml"
+- ".codebuild/project.rb"
+- ".codebuild/settings.yml"
 - ".gitignore"
 - ".gitmodules"
 - ".rspec"
@@ -274,15 +277,18 @@ files:
 - docs/_docs/dsl/sns.md
 - docs/_docs/dsl/webhook.md
 - docs/_docs/ecs-deploy.md
+- docs/_docs/examples/codebuild-project.md
 - docs/_docs/examples/different-branches.md
 - docs/_docs/examples/multiple-codebuild-projects.md
 - docs/_docs/install.md
 - docs/_docs/next-steps.md
 - docs/_docs/settings.md
 - docs/_docs/start.md
+- docs/_docs/structure.md
 - docs/_includes/commands.html
 - docs/_includes/content.html
 - docs/_includes/edit-on-github.html
+- docs/_includes/example.html
 - docs/_includes/footer.html
 - docs/_includes/google_analytics.html
 - docs/_includes/head.html
@@ -317,10 +323,8 @@ files:
 - docs/_sass/_variables.scss
 - docs/bin/web
 - docs/docs.md
-- docs/dsl/pipeline.md
-- docs/dsl/role.md
-- docs/dsl/schedule.md
 - docs/img/docs/codepipeline-output.png
+- docs/img/docs/multiple-codebuild-projects-pipeline.png
 - docs/img/logos/boltops-logo-full.png
 - docs/img/logos/boltops-logo.png
 - docs/img/logos/project-logo.png
@@ -426,7 +430,8 @@ files:
 - lib/codepipe/help.rb
 - lib/codepipe/help/completion.md
 - lib/codepipe/help/completion_script.md
-- lib/codepipe/help/hello.md
+- lib/codepipe/help/deploy.md
+- lib/codepipe/help/start.md
 - lib/codepipe/init.rb
 - lib/codepipe/pipeline.rb
 - lib/codepipe/pipeline/s3_bucket.rb

data/docs/dsl/pipeline.md

@@ -1,75 +0,0 @@
-# Pipeline DSL
-
-.codepipeline/pipeline.rb:
-
-```ruby
-stage "Source" do
-  github(
-    source: "tongueroo/demo-cb",
-    auth_token: ssm("/codebuild/github/tongueroo/oauth_token")
-  )
-end
-stage "DeployStacks" do
-  codebuild "demo1"           # action declaration
-  codebuild "demo2", "demo3"  # will run in parallel. run_order=2
-  codebuild "demo4"           # action declaration
-end
-```
-
-## Under the Hood
-
-The convenience methods are shorter and cleaner. However, you have access to a "Full" DSL if needed. The Full DSL are merely the properties of the [AWS::CodePipeline::Pipeline](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codepipeline-pipeline.html).  Here's an example.
-
-.codepipeline/pipeline.rb:
-
-```ruby
-stage "Source" do
-  action(
-    name: "Source",
-    action_type_id: {
-      category: "Source",
-      owner: "ThirdParty",
-      provider: "GitHub",
-      version: "1",
-    },
-    run_order: 1,
-    configuration: {
-      branch: "master",
-      o_auth_token: ssm("/codebuild/github/tongueroo/oauth_token"),
-      owner: "tongueroo",
-      poll_for_source_changes: "false",
-      repo: "demo-cb"
-    },
-    output_artifacts: [name: "SourceArtifact"]
-  )
-end
-
-stage "Deploy Stacks" do
-  # serial
-  action(
-    name: "Build1",
-    action_type_id: {
-      category: "Build",
-      owner: "AWS",
-      provider: "CodeBuild",
-      version: "1",
-    },
-    run_order: 2,
-    configuration: { project_name: "demo1" },
-    input_artifacts: [name: "SourceArtifact"],
-  )
-  action(
-    name: "Build2",
-    action_type_id: {
-      category: "Build",
-      owner: "AWS",
-      provider: "CodeBuild",
-      version: "1",
-    },
-    run_order: 2,
-    configuration: { project_name: "demo2" },
-    input_artifacts: [name: "SourceArtifact"],
-  )
-end
-```
-

data/docs/dsl/role.md

@@ -1,66 +0,0 @@
-# IAM Role DSL
-
-You can create the IAM service role associated with the pipeline. Here's an example:
-
-.codepipeline/role.rb:
-
-```ruby
-iam_policy("logs", "ssm")
-```
-
-For more control, here's a longer form:
-
-```ruby
-iam_policy(
-  action: [
-    "logs:CreateLogGroup",
-    "logs:CreateLogStream",
-    "logs:PutLogEvents",
-    "ssm:*",
-  ],
-  effect: "Allow",
-  resource: "*"
-)
-```
-
-You can also create managed iam policy.
-
-```ruby
-managed_iam_policy("AmazonS3ReadOnlyAccess")
-```
-
-## Under the Hood
-
-The convenience methods merely wrap properties of the [AWS::IAM::Role
- CloudFormation Resource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html).  If you wanted to set the CloudFormation properties more directly, here's an example of using the "Full" DSL.
-
-.codepipeline/role.rb:
-
-```ruby
-assume_role_policy_document(
-  statement: [{
-    action: ["sts:AssumeRole"],
-    effect: "Allow",
-    principal: {
-      service: ["codepipeline.amazonaws.com"]
-    }
-  }],
-  version: "2012-10-17"
-)
-path("/")
-policies([{
-  policy_name: "CodePipelineAccess",
-  policy_document: {
-    version: "2012-10-17",
-    statement: [{
-      action: [
-        "logs:CreateLogGroup",
-        "logs:CreateLogStream",
-        "logs:PutLogEvents",
-      ],
-      effect: "Allow",
-      resource: "*"
-    }]
-  }
-}])
-```

data/docs/dsl/schedule.md

@@ -1,20 +0,0 @@
-# Schedule DSL
-
-.codepipeline/schedule.rb:
-
-```ruby
-rate "1 day"
-# or
-cron("0 10 * * ? *") # Run at 10:00 am (UTC) every day
-```
-
-## Under the Hood
-
-The convenience methods merely wrap properties of the [AWS::Events::Rule](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-events-rule.html#cfn-events-rule-description).  If you wanted to set the CloudFormation properties more directly, here's an example of using the "Full" DSL.
-
-.codepipeline/schedule.rb:
-
-```ruby
-description "my description"
-schedule_expression "rate(1 day)"
-```

data/lib/codepipe/help/hello.md

@@ -1,5 +0,0 @@
-Examples:
-
-    codepipe hello
-    codepipe hello NAME
-    codepipe hello NAME --from me