codepipeline 0.1.0 → 0.2.0

data/docs/_config.yml

@@ -0,0 +1,73 @@
+# Site settings
+title: codepipeline
+email: tongueroo@gmail.com
+url: https://codepipeline.org
+description: "CodePipeline DSL"
+keywords: "codepipeline boltops dsl ruby aws"
+skills: ""
+meta_author: Tung Nguyen
+
+# Google webmaster tools
+google_verify:
+google_analytics: "UA-98684555-12"
+
+# https://ssl.bing.com/webmaster/configure/verify/ownership Option 2 content= goes here
+bing_verify:
+
+# Contact form:
+# - static : pass through formspree.io to validate email sending
+# - disqus : replace contact form by disqus thread
+# - comment the line below if you want to stick with the default PHP contact form
+contact: static
+
+# If you use disqus you need disqus shortname
+# https://help.disqus.com/customer/portal/articles/466208
+disqus_shortname:
+
+# Color settings (hex-codes without the leading hash-tag)
+color:
+  primary: 3972c7
+  primary-rgb: "24,288,156" #"128,179,255"
+  secondary: 2c3e50 #FD6E8A
+  secondary-dark: 233140 #A2122F
+  links: a3c8ff
+
+# Footer settings
+footer:
+  copyright: BoltOps, LLC
+  location: San Francisco, CA
+  social: BoltOps
+  credits:
+  contact: contact@boltops.com
+  phone:
+
+# Social networks usernames (many more available: google-plus, flickr, dribbble, pinterest, instagram, tumblr, linkedin, etc.)
+social:
+  - title: twitter
+    url: http://twitter.com/tongueroo
+  - title: github
+    url: https://github.com/tongueroo/codepipeline
+
+# Credits content
+credits:
+
+# Build settings
+markdown: kramdown
+permalink: pretty
+
+gh_url: https://github.com/tongueroo/codepipeline
+
+collections:
+  docs:
+    name: "Documentation"
+    output: true
+  reference:
+    name: "Reference"
+    output: true
+
+defaults:
+  - values:
+      layout: default
+
+plugins_dir:
+ - jekyll-coffeescript

data/docs/_docs/contributing.md

@@ -0,0 +1,99 @@
+---
+title: Contributing
+---
+
+Hi there! Interested in contributing to CodePipeline? We'd love your help. CodePipeline is an open source project, built one contribution at a time by users like you.
+
+## Where to get help or report a problem
+
+See [the support guidelines]({% link support.md %})
+
+## Ways to contribute
+
+Whether you're a developer, an infrastructure engineer, or just an enthusiast, there are lots of ways to contribute. Here are a few ideas:
+
+* [Install CodePipeline on your computer](https://https://codepipeline.org.com/docs/install/) and kick the tires. Does it work? Does it do what you'd expect? If not, [open an issue](https://github.com/tongueroo/codepipeline/issues/new/choose) and let us know.
+* Comment on some of the project's [open issues](https://github.com/tongueroo/codepipeline/issues). Have you experienced the same problem? Know a workaround? Do you have a suggestion for how the feature could be better?
+* Read through [the documentation](https://https://codepipeline.org.com/docs/), and click the "improve this page" button, any time you see something confusing or have a suggestion for something that could be improved.
+* Browse through the [CodePipeline Community forum](https://community.https://codepipeline.org.com), and lend a hand answering questions. There's a good chance you've already experienced what another user is experiencing.
+* Find [an open issue](https://github.com/tongueroo/codepipeline/issues) (especially [those labeled `help wanted`](https://github.com/tongueroo/codepipeline/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)), and submit a proposed fix. If it's your first pull request, we promise we won't bite and are glad to answer any questions.
+* Help evaluate [open pull requests](https://github.com/tongueroo/codepipeline/pulls), by testing the changes locally and reviewing what's proposed.
+
+## Submitting a pull request
+
+### Pull requests generally
+
+* The smaller the proposed change, the better. If you'd like to propose two unrelated changes, submit two pull requests.
+
+* The more information, the better. Make judicious use of the pull request body. Describe what changes were made, why you made them, and what impact they will have for users.
+
+* If this is your first pull request, it may help to [understand GitHub Flow](https://guides.github.com/introduction/flow/).
+
+* If you're submitting a code contribution, be sure to read the [code contributions](#code-contributions) section below.
+
+### Submitting a pull request via github.com
+
+Many small changes can be made entirely through the github.com web interface.
+
+1. Navigate to the file within [tongueroo/codepipeline](https://github.com/tongueroo/codepipeline) that you'd like to edit.
+2. Click the pencil icon in the top right corner to edit the file.
+3. Make your proposed changes.
+4. Click "Propose file change."
+5. Click "Create pull request."
+6. Add a descriptive title and detailed description for your proposed change. The more information, the better.
+7. Click "Create pull request."
+
+That's it! You'll be automatically subscribed to receive updates as others review your proposed change and provide feedback.
+
+### Submitting a pull request via Git command line
+
+1. Fork the project by clicking "Fork" in the top right corner of [tongueroo/codepipeline](https://github.com/tongueroo/codepipeline).
+2. Clone the repository locally `git clone https://github.com/<your-username>/codepipeline`.
+3. Fetch submodules `git submodule init && git submodule update`.
+4. Create a new, descriptively named branch to contain your change ( `git checkout -b my-awesome-feature` ).
+5. Hack away, add tests. Not necessarily in that order.
+6. Make sure everything still passes by running `bundle exec rspec` (see [the tests section](#running-tests-locally) below)
+7. Push the branch up ( `git push origin my-awesome-feature` ).
+8. Create a pull request by visiting `https://github.com/<your-username>/codepipeline` and following the instructions at the top of the screen.
+
+## Proposing updates to the documentation
+
+We want the CodePipeline documentation to be the best it can be. We've open-sourced our docs and we welcome any pull requests if you find it lacking.
+
+### How to submit changes
+
+You can find the documentation for [https://codepipeline.org.com](http://https://codepipeline.org.com) in the [docs](https://github.com/tongueroo/codepipeline/tree/master/docs) directory. See the section above, [submitting a pull request](#submitting-a-pull-request) for information on how to propose a change.
+
+One gotcha, all pull requests should be directed at the `master` branch (the default branch).
+
+## Code Contributions
+
+Interesting in submitting a pull request? Awesome. Read on. There are a few common gotchas that we'd love to help you avoid.
+
+### Tests and documentation
+
+Any time you propose a code change, you should also include updates to the documentation and tests within the same pull request.
+
+#### Documentation
+
+If your contribution changes any CodePipeline behavior, make sure to update the documentation. Documentation lives in the `docs` folder.  It's a Jekyll site and can be started with `cd docs && bin/web`. If the docs are missing information, please feel free to add it in. Great docs make a great project. Include changes to the documentation within your pull request, and once merged, `https://codepipeline.org.com` will be updated.
+
+#### Tests
+
+* If you're creating a small fix or patch to an existing feature, a simple test is more than enough. You can usually copy/paste from an existing example in the `specs` folder.
+
+### Code contributions generally
+
+* Don't bump the Gem version in your pull request (if you don't know what that means, you probably didn't).
+
+## Running tests
+
+### Test Dependencies
+
+To run the test suite by running the following command:
+
+    bundle exec rspec
+
+## Thank You
+
+Thanks! Hacking on CodePipeline should be fun. If you find any of this hard to figure out, let us know so we can improve our process or documentation!

data/docs/_docs/conventions.md

@@ -0,0 +1,43 @@
+---
+title: Naming Conventions
+nav_order: 7
+---
+
+The codepipeline tool follows a few naming conventions.
+
+## Pipeline Name
+
+It will set the pipeline name by inferring the name of the parent folder.  For example, if the parent folder is `demo`.
+
+    cd demo
+    pipe deploy
+
+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
+
+The pipeline is named `my-pipeline`
+
+## PIPE_ENV_EXTRA
+
+The `PIPE_ENV_EXTRA` also affects the name of the pipeline.  It gets appended at the end of the pipeline name.
+
+    PIPE_ENV_EXTRA=2 pipe deploy my-pipeline
+
+The pipeline is named `my-pipeline-2`.
+
+## Settings append_env option
+
+If the append_env is configured in the [Settings]({% link _docs/settings.md %}).
+
+## 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:
+
+Pipeline Name | Stack Name
+--- | ---
+demo | demo-cb
+demo-unit | demo-unit-cb
+demo-web-unit | demo-web-unit-cb
+
+{% include prev_next.md %}

data/docs/_docs/deploy.md

@@ -0,0 +1,72 @@
+---
+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:
+
+    .codepipeline/pipeline.rb
+    .codepipeline/role.rb
+    .codepipeline/schedule.rb
+    .codepipeline/webhook.rb
+
+To create the CodePipeline pipeline, you run:
+
+    codepipeline 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. In the `.codepipeline/pipeline.rb` use the DSL method `branch` to reference it.  Example:
+
+    pipe deploy my-pipeline --branch my-branch
+
+.codepipeline/pipeline.rb
+
+```ruby
+stage "Source" do
+  github(
+    source: "tongueroo/demo-test",
+    branch: branch, # branch method defaults to "master" or the `pipe deploy --branch` option
+    auth_token: ssm("/codebuild/github/tongueroo/oauth_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.
+
+
+## CLI Reference
+
+Also, for help info you can check the [pipe deploy]({% link _reference/pipe-deploy.md %}) CLI reference.
+
+{% include prev_next.md %}

data/docs/_docs/dsl.md

@@ -0,0 +1,13 @@
+---
+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:
+
+* [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.
+
+{% include prev_next.md %}

data/docs/_docs/dsl/approve.md

@@ -0,0 +1,62 @@
+---
+title: Approval Action DSL
+nav_text: Approve
+categories: dsl
+nav_order: 9
+---
+
+You can add an approve action to a stage with the simple `approve` method.  There are various helpful forms. Let's start with the simplest form.
+
+## String
+
+The approve method take can take a simple String. In this form, it sets the message for the approval action.  Essentially, it sets the `configuration.CustomData` property of the Approval action.  See [Add an Action to a Pipeline in CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/approvals-action-add.html) docs for the full structure.
+
+```ruby
+stage "Approve" do
+  approve("Approve this deployment")
+end
+```
+
+In this case, the codepipeline tool creates and manages the SNS topic for you.
+
+## 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:
+
+```ruby
+stage "Approve" do
+  approve(
+    notification_arn: "arn:aws:sns:us-west-2:536766270177:hello-topic",
+    custom_data: "Approve deployment",
+  )
+end
+```
+
+In this case, the codepipeline will *not* create an SNS Topic as we're using an existing SNS topic.
+
+## Full Config
+
+The convenience methods merely wrap a CodePipeline Approval Action.  An example of the Approval Action structure is provided in the [Add an Action to a Pipeline in CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/approvals-action-add.html) docs.
+
+If you need to set the properties more directly, here's an example of using the "Full" Config.
+
+```ruby
+stage "Approve" do
+  approve(
+    name: "approve",
+    action_type_id: {
+      category: "Approval",
+      owner: "AWS",
+      provider: "Manual",
+      version: "1",
+    },
+    run_order: 1,
+    configuration: {
+      custom_data: "my message",
+      notification_arn: {ref: "SnsTopic"}, # defaults to generated SNS topic
+    },
+  )
+end
+```
+
+{% include prev_next.md %}

data/docs/_docs/dsl/pipeline.md

@@ -0,0 +1,56 @@
+---
+title: Pipeline DSL
+nav_text: Pipeline
+categories: dsl
+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.
+
+```
+stage "Source" do
+  github(
+    source: "tongueroo/demo-test",
+    branch: branch, # branch method defaults to "master" or the `pipe deploy --branch` option
+    auth_token: ssm("/codebuild/github/tongueroo/oauth_token")
+  )
+end
+
+stage "Build" do
+  codebuild "demo1", "demo2"
+  codebuild "demo3"
+end
+
+stage "Approve" do
+  approve
+end
+
+stage "Deploy" do
+  codebuild "deploy"
+end
+```
+
+This pipeline has 3 stages:
+
+1. downloads the source code from Gitub and uploads it to S3 as an output artifact
+2. starts some codebuild project with output artifact from the previous step
+3. waits for a manual approval stage
+4. uses another codebuild to kick off a deploy.
+
+## Build Stage
+
+Within the build stage, there are multiple actions. Some of them run in parallel and some in serial.
+
+* The demo1 and demo2 codebuild projects run on the same `RunOrder=1`.  They run in parallel.
+* The demo3 codebuild project run with `RunOrder=2`.  It starts after both demo1 and demo2 finishes.
+
+The Pipeline DSL allows to you connect the stages together how you want them with very little code.
+
+## Pipeline Specific DSL Docs
+
+{% assign docs = site.docs | where: "categories","dsl-pipeline" %}
+{% for doc in docs -%}
+* [{{doc.nav_text}}]({{doc.url}})
+{% endfor %}
+
+{% include prev_next.md %}

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

@@ -0,0 +1,28 @@
+---
+title: Action General Method
+nav_text: Action
+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.
+
+```ruby
+stage "Build" do
+  action(
+    name: "action1",
+    action_type_id: {
+      category: "Build",
+      owner: "AWS",
+      provider: "CodeBuild",
+      version: "1",
+    },
+    run_order: 1,
+    configuration: { project_name: 'demo1' },
+    # output_artifacts: [name: "BuildArtifact#{name}"], # optional
+    input_artifacts: [name: "SourceArtifact"], # default
+  )
+end
+```
+
+{% include prev_next.md %}