Cody is a AWS CodeBuild management tool. It simplifies creating and managing AWS CodeBuild projects with a powerful DSL. It has quickly grown to one of my favorite tools since creating it.

Getting Started

It only takes a few commands to get started with Cody. First, install the tool.

gem install cody

Then use cody init to “codify” your project.

$ cd project
$ cody init
      create  .cody
      create  .cody/
       exist  .cody
      create  .cody/buildspec.yml
      create  .cody/project.rb

The init command generates starter .cody files that includes a .cody/buildspec.yml.

Let’s take a look at the buildspec.yml.

version: 0.2

      - uptime

The starter buildspec.yml just runs the uptime command as an example to help you get started with CodeBuild.

AWS CodeBuild will pull from a GitHub repo. So you must push your changes to a GitHub repo. Create a GitHub repo and push your changes to your repo.

git add .
git commit
git remote add origin # update with your info
git push -u origin master

You also have to import your GitHub token so that CodeBuild has access to clone your repo. Details here: GitHub Oauth Token


The cody init command also created a .cody/project.rb.

github_url("") # update with your info
  JETS_ENV: "test",

The project.rb defines the Code Build project with the Cody DSL. The DSL merely wraps CloudFormation AWS::CodeBuild::Project properties. Herein lays the power of cody.

Normally, defining a CodeBuild project requires a large CodeBuild JSON definition. IE: Check out this Gist or this CloudFormation template.

Cody gets it down to only a few lines! Yet at the same time, it still gives you the full power to customize the project. On top of that, you have the power of the Ruby programming language at your finger tips.

More info on the Cody DSL Docs.


We can use cody deploy to create CodeBuild project.

$ cody deploy
Generated CloudFormation template at /tmp/codebuild.yml
Deploying stack cody-demo-cody with CodeBuild project cody-demo
Creating stack cody-demo-cody. Check CloudFormation console for status.
Stack name cody-demo-cody status CREATE_IN_PROGRESS
Here's the CloudFormation url to check for more details
Waiting for stack to complete
02:58:41AM CREATE_IN_PROGRESS AWS::CloudFormation::Stack cody-demo-cody User Initiated
02:58:45AM CREATE_IN_PROGRESS AWS::IAM::Role IamRole Resource creation Initiated
02:59:02AM CREATE_IN_PROGRESS AWS::CodeBuild::Project CodeBuild
02:59:04AM CREATE_IN_PROGRESS AWS::CodeBuild::Project CodeBuild Resource creation Initiated
02:59:05AM CREATE_COMPLETE AWS::CodeBuild::Project CodeBuild
02:59:06AM CREATE_COMPLETE AWS::CloudFormation::Stack cody-demo-cody
Stack success status: CREATE_COMPLETE
Time took for stack deployment: 25s.

The deploy command launches a CloudFormation stack to create and manage the CodeBuild project. It looks like this:

On the CodeBuild console it looks like this:


We’re ready to start a build with cody start. It essentially wraps the aws codebuild start-build command.

$ cody start cody-demo
Build started for project: cody-demo
Please check the CodeBuild console for the status.
CodeBuild Log Url:

It’s essentially the same thing as:

aws codebuild start-build --project-name cody-demo

You can see the CodeBuild run in the console.

Check out the build logs. To get there, click on Projects > Select Project > Click on Build Logs. When the build finishes you’ll see something like this:

You can see the uptime output.


Cody provides a simple way to create CodeBuild projects. There’s a lot more power to the tool. For example, the type option allows you to create multiple CodeBuild projects associated with the same repo. You can fully control the IAM role permissions used. You can have the CodeBuild project execute on a scheduled basis. This article is meant to provide an introduction to the Cody tool.

The project source code for this blog post is available at: tongueroo/cody-demo.