Integrating AWS CodeCommit with Review Board

Today we have a guest post from Jeff Nunn, a Solutions Architect at AWS, specializing in DevOps and Big Data solutions.

By now you’ve probably heard of AWS CodeCommit–a secure, highly scalable, managed source control service that hosts private Git repositories. AWS CodeCommit supports the standard functionality of Git, allowing it to work seamlessly with your existing Git-based tools. In addition, CodeCommit works with Git-based code review tools, allowing you and your team to better collaborate on projects. By the end of this post, you will have launched an EC2 instance, configured the AWS CLI, and integrated CodeCommit with a code review tool.

What is Code Review?

Code review (sometimes called “peer review”) is the process of making source code available for other collaborators to review. The intention of code review is to catch bugs and errors and improve the quality of code before it becomes part of the product. Most code review systems provide contributors the ability to capture notes and comments about the changes to enable discussion of the change, which is useful when working with distributed teams.

We’ll show you how to integrate AWS CodeCommit into development workflow using the Review Board code review system.

Getting Started

If you’re reading this, you most likely are familiar with Git and have it installed. To work with files or code in AWS CodeCommit repositories, you must install Git on your local machine, if you haven’t installed it already. AWS CodeCommit supports Git versions 1.7 and later.

In addition, you’ll need to have an AWS Identity and Access Management (IAM) user with an appropriate AWS CodeCommit permissions policy attached. Follow the instructions at Set Up Your IAM User Credentials for Git and AWS CodeCommit to give your user(s) access.

While this post covers integration with Review Board, you can take what you learn here and integrate with your favorite code review tools. We’ll soon publish integration methods for other tools, like Gerrit, Phabricator, and Crucible. When you have completed the above prerequisites, you are ready to continue.

Review Board

Review Board is a web-based collaborative code review tool for reviewing source code, documentation, and other text-based files. Let’s integrate Review Board with a CodeCommit repo. You can integrate CodeCommit with an existing Review Board server, or setup a new one. If you already have Review Board setup, you can skip down to Step 2: Setting up the Review Board Server.

Step 1: Creating a Review Board Server

To setup a Review Board server, we turn to the AWS Marketplace. The AWS Marketplace has a rich ecosystem of Independent Software Vendors (ISVs) and partners that AWS works with, and there you will find many pre-built Amazon Machine Images (AMIs) to help save you time and effort when setting up software or application stacks.

We launch an EC2 instance based off a public Review Board AMI from Bitnami. From the EC2 console, click the Launch Instance button. From Choose an Amazon Machine Image (AMI), click the “AWS Marketplace” link, and then search for “review board hvm”.

In the search results returned, select “Review Board powered by Bitnami (HVM)”. While some products in the AWS Marketplace do have an additional cost to use them, you’ll notice that there is no additional cost to run Review Board from Bitnami. Click the Select button to choose this image, and you are taken to the “Choose Instance Type” step. By default, the Review Board AMI selects an m3.medium instance to launch into, but you can choose any instance type that fits your needs. Click the Review and Launch button to review the settings for your instance. Scroll to the bottom of the screen, click the Edit Tags link, and create a “Name” tag with a descriptive value:

Click the Review and Launch button again, and then click the Launch button. Verify that you have a key pair that will connect to your instance, and then click the Launch Instance button.

After a short time, your instance should successfully launch, and be in a “running” state:

Because we used Bitnami’s prebuilt-AMI to do our install, the majority of the configuration is done for us, including the creation of an administrative user and password. To retrieve the password, select the instance, click the Actions button, and then click “Get System Log.” You can find more information on this process at Bitnami’s website for retrieving AWS Marketplace credentials.

Scroll until you’re near the bottom of the log, and find the “Bitnami application password.” You’ll need this to login to your Review Board server in Step 2.

Step 2: Setting Up The Review Board Server

SSH into your EC2 instance. If you’ve installed Review Board with the Bitnami AMI, you’ll need to login as the “bitnami” user rather than the “ubuntu” user. Download and install the AWS CLI, if you haven’t done so already. This is a prerequisite to enabling you to interact with AWS CodeCommit from the command line. For more information, see Getting Set Up with the AWS Command Line Interface.

Note: Although the Review Board AMI comes with Python and pip (“pip” is a package manager for Python), you’ll need to re-install pip before installing the AWS CLI. From the command line, type:

> curl -O https://bootstrap.pypa.io/get-pip.py

and then:

> sudo python get-pip.py

Follow the instructions from the “Install the AWS CLI using pip” section, and then configure the command line to work with your AWS account. Be sure to specify “us-east-1” as your default region, as CodeCommit currently only works from this region.

Configure the AWS CodeCommit Credential Helper

The approach that you take to set up your IAM user credentials for Git and AWS CodeCommit on your local machine depends on the connection protocol (HTTPS) and operating system (Windows, or Linux, OS X, or Unix) that you intend to use.

For HTTPS, you allow Git to use a cryptographically-signed version of your IAM user credentials whenever Git needs to authenticate with AWS in order to interact with repositories in AWS CodeCommit. To do this, you install and configure on your local machine what we call a credential helper for Git. (Without this credential helper, you would need to manually sign and resubmit a cryptographic version of your IAM user credentials frequently whenever you need Git to authenticate with AWS. The credential helper automatically manages this process for you.)

Follow the steps in Set up the AWS CodeCommit credential helper for Git depending on your desired connection protocol and operating system.

Create or Clone a CodeCommit Repository

Now that you have your Review Board server setup, you’ll need to add an AWS CodeCommit repository to connect to. If you have not yet created an AWS CodeCommit repository, follow the instructions here to create a new repository, and note the new AWS CodeCommit repository’s name.

If you have an existing AWS CodeCommit repository but you do not know its name, you get the name by following the instructions in View Repository Details.

Once you have your AWS CodeCommit repository name, you will create a local repo on the Review Board server. Change to a directory in which you will store the repository, and clone the repository. Cloning to your home directory is shown in the following example:

> cd ~
> git clone https://git-codecommit.us-east-1.amazonaws.com/v1/repos/MyDemoRepo my-demo-repo

Setting up a Repository in Review Board

Now that you have cloned your repo to your Review Board server, we need to configure Review Board to watch your repo. Visit the Public DNS address of your EC2 instance, and login to the Review Board administration panel, which will look like http://ec2-dns-address-of-your-instance.amazonaws.com/admin/.  The username is “user,” and the password is the password you saved from the log file in Step 1.

After logging in, you are taken the admin dashboard. Create a new repository from the Manage section of the admin menu. Fill in the name, keep the “Hosting service” at “None”, and select “Git” as the “Repository type.” For the path, enter the path to your cloned repository, including the “.git” hidden folder, as seen in the example below:

Finally, click the Save button. Back on the Manage section of the admin menu click the Repositories link to be taken to a dashboard of the repositories on your Review Board system. Next to your repository, click the RBTools Setup link. Follow the instructions to create a .reviewboardrc file in your repository:

Commit the file to your repository and push it to AWS CodeCommit with a “git push” command. RBTools will then be able to find the correct server and repository when any developer posts changes for review.

Step 3: Setting up Your Client(s)

Now that you have a Review Board server setup, you’ll need to install AWS CodeCommit and RBTools. For each client machine, configure the AWS CLI and AWS CodeCommit similar to the way you did on the Review Board server. Then install RBTools, which will allow you to post your changes to the Review Board server, and let other collaborators comment on those changes. You may also want to create user accounts in the Review Board dashboard for each developer that will submit reviews. For the purposes of this demo, create at least one additional user to serve as a reviewer for your code review requests.

Step 4: Using Review Board in your AWS CodeCommit Workflow

You now have a Review Board server integrated with AWS CodeCommit, a client from which to send review requests, and an additional Review Board user to assign review requests to. Let’s take a look at a typical Git workflow with Review Board.

In many projects, feature work or bug fixes are first done in a Git branch, then moved into the main branch (sometimes called master or mainline) after a testing or review process.

Let’s go through a simple example to demonstrate branching, merging, and reviewing in an AWS CodeCommit and Review Board workflow. We’ll take a fictitious cookbook project and add recipes to it, and have a reviewer accept your changes before you merge them into your AWS CodeCommit project’s master branch.

Creating a Review Request

Create a branch in your project from which to add a new file:

> git checkout -b pies
Switched to a new branch pies

Now, add a new file to this branch (you could also modify an existing file, but for the sake of this demo, we will create a new one).

> echo "6 cups of sliced, peeled apples." > applepie.txt

You’ve now added the beginning of a new pie recipe to your cookbook. Ideally, you would now run unit tests to verify the validity of your work, or similarly validate that your code was functional and did not break other parts of your code base.

Add this recipe to your repo, and give it a meaningful commit message:

> git add .
> git commit -m "beginning apple pie recipe"
[pies 5d2a678] beginning apple pie recipe
1 file changed, 1 insertion(+)
create mode 100644 applepie.txt

You have added a new file to a branch in your project–let’s share it with your reviewers. We use rbt post, along with our branch name, to post it to the Review Board server for review. On your first post to Review Board, you will be asked a username and password, and upon successful post to the Review Board server, you are given a review request URL.

> rbt post pies
Review request #1 posted.

http://ec2-dns-address-of-your-instance.amazonaws.com:80/r/1/
http://ec2-dns-address-of-your-instance.amazonaws.com:80/r/1/diff/

We specified our branch name, “pies” in the “rbt post” command, which automatically chooses the latest commit in our commit history to send to the Review Board server. You are able to post any commit in your history however, by specifying the commit ID–which you can retrieve by issuing a “git log” command. For example, if you add additional pie recipes across several commits, you could choose a specific commit to send to the Review Board server.

> git log

commit 1d1bfc579bac494ae656eae9ce6ee23cae3f146b
Author: username <user@email.com>
Date: Mon May 11 10:37:12 2015 -0500

  Blueberry pie 

commit 468f20fc4272691a409ef21dc0d6eaab27c1ab35
Author: username <user@email.com>
Date: Mon May 11 10:35:22 2015 -0500 

  Cherry and chocolate pie recipes 

> rbt post 468f20
Review request #2 posted.

http://ec2-dns-address-of-your-instance.amazonaws.com:80/r/2/
http://ec2-dns-address-of-your-instance.amazonaws.com:80/r/2/diff/

Now that we have sent our apple pie recipe (and any additional recipes you may have created) to the Review Board server for review, let’s log in to walk through the process of assigning them to be reviewed.

Log in to your Review Board account and visit your dashboard. Under the Outgoing menu on the left-hand side, you’ll see a count of “All” and “Open” requests. Click “All,” and then click the “[Draft] beginning apple pie recipe” request.

Edit your description or add comments to any testing you have done, and then assign a reviewer by clicking the pencil icon next to “People” under the Reviewers section:

Finally, click the Publish button to publish your review request and assign it to one or more reviewers.

Reviewing a Change Request

Now that we have at least one review request assigned to a user, log in as that user on the Review Board server. On your dashboard under the Incoming section, click the “To Me” link. Find the “beginning apple pie recipe” request and click it to be taken to the review request details page. Click the View Diff button in the summary toolbar to view the changes made to this file. Since this was a new file, you will only see one change. Click the Review button in the summary toolbar to add your review comments to this request. When you are finished with your comments, click the Publish Review button.

As a reviewer, we are satisfied with the modifications to the file. We could check the “Ship It” box, or click the Ship It button in the summary toolbar after we publish the review. We have now indicated that the code is ready to be merged into the master branch.

Log in again as the user who submitted the request, and notice two new icons next to your request. The speech bubble indicates you have comments available to view, and the green check oval indicates that your code is ready to be merged into your master AWS CodeCommit branch.

View the comments from your reviewer, and notice that your code is ready to be shipped.

Merging Your Commit

There are several viable ways to merge a branch into a master branch, like cherry-picking a single commit from a branch, or bringing in all commits. We keep things simple here, and simply merge the commit(s) from the pies branch into the master. Now, push the updated code up to the AWS CodeCommit Git repo.

> git checkout master
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.

> git merge pies
Updating 304d704..9ab13cf
Fast-forward
 applepie.txt | 1 +
 1 files changed, 11 insertions(+)
 create mode 100644 applepie.txt

> git push

Counting objects: 2, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (2/2), 226 bytes | 0 bytes/s, done.
Total 2 (delta 1), reused 0 (delta 0)

remote:
To https://git-codecommit.us-east-1.amazonaws.com/v1/repos/MyDemoRepo

   9ab13cf..a0e3119 master -> master

Conclusion

Congratulations! You integrated Review Board with AWS CodeCommit, and created a feature development branch, created code, submitted it for review, and merged it into your master branch after acceptance. You seamlessly combined a secure, highly scalable and managed service for your Git repositories with a code review tool, and now you can ship your code faster, cleaner, and with more confidence. In future posts, we’ll show you how to integrate AWS CodeCommit with other common Git tools.