Evaluate Weigh the pros and cons of technologies, products and projects you are considering.

Debug more quickly with AWS CodeBuild local support

AWS CodeBuild's local features serve as much-needed support for dev teams that can't afford lengthy wait times. Here's how to implement these features to ramp up development.

With CodeBuild, AWS aims to make developers' lives easier through the enablement of quick CI/CD pipelines. And...

while the service is a good fit for AWS-native developers, it has some shortcomings -- a few of which the cloud provider now addresses through AWS CodeBuild local support.

AWS CodeBuild integrates directly with CodePipeline for CI/CD, as well as with CloudFormation for automation. The service also uses Docker images for the build environment, which makes it easy to completely customize the underlying system used to complete the build process.

CodeBuild enables developers to configure a build with multiple steps: install, test, build and deploy. Typical build configurations include custom package updates or installation into the underlying OS, as well as application dependency installation and unit test implementation. Additionally, CodeBuild can compile and compress any code into the proper format and then bundle the package for deployment as a build artifact. Developers can then use CodePipeline to upload the build artifact or upload it directly to AWS Lambda with something like the sls deploy Serverless Framework command.

Although CodeBuild supports logs and developers can monitor build progress from AWS Management Console, it can be difficult to track down issues that might specifically relate to the CodeBuild environment. These issues might include missing permissions on the AWS Identity and Access Management (IAM) role associated with the environment or varying changes in the Docker configuration; both issues can make debugging difficult because you aren't able to quickly try minor changes since there's no direct console access.

To make matters worse, AWS CodeBuild isn't as fast as debugging issues locally, so it might slow down a dev team if it has to wait 15 minutes to see if a particular change fixed the issue. Slow local debugging plagues most CI/CD platforms, as it's difficult to replicate a developer's local environment during the build pipeline creation stage.

AWS CodeBuild fits in with culture shift

Amazon made an effort to address this issue -- and adapt to modern personnel challenges -- with AWS CodeBuild local build and test support.

When organizations migrate to AWS, many IT teams stray away from a traditional operations methodology. This, in turn, places build errors on the shoulders of developers, who don't generally like to wait 15 minutes just to get a new error message. But with AWS CodeBuild local support, a developer has the option to run the build on premises and stop it when it fails.

To get started with AWS CodeBuild local debugging and testing, developers can either use AWS Cloud9 as an integrated development environment (IDE), build directly on an EC2 instance or build the environment locally. It's recommended that developers use an EC2 instance or the Cloud9 IDE to make sure the environment is as similar to CodeBuild as possible, but they can run CodeBuild's local features anywhere they install Docker.

First, download the Docker image in which the CodeBuild environment runs. Developers can opt to download an image provided by the CodeBuild repository for managed Docker images. In addition to the specific build environment chosen for CodeBuild -- such as Java, Node.js or Go -- developers must also download the CodeBuild Agent, which is also available as a Docker image:

docker pull amazon/aws-codebuild-local:latest \


Developers can then run the CodeBuild Agent with the following environment variables, which emulate a local CodeBuild execution:

  • IMAGE_NAME, the Docker image name of the environment to run, for example: (aws/codebuild/java:openjdk-8);
  • SOURCE, the full path to the application source code to build; and
  • ARTIFACTS, the location to put any build artifacts produced by the build.

Note that the local build agent uses code that already exists somewhere on the local machine, instead of pulling down from a Git repository. This means developers don't need to commit and push code to test a minor change to something, such as the buildspec.yml file.

Additionally, developers can integrate this build step into their local development process, which means they can quickly iterate a change and build in the exact format that CodeBuild would produce output.

Here's the rub

Keep in mind that there are a few differences between CodeBuild local and CodeBuild on AWS -- specifically with access management. The CodeBuild service uses an IAM service role, which developers should configure to have a more limited set of permissions. It's often easier to just grant CodeBuild full administrative access to your AWS account when build steps fail due to permissions failures, but that decision can lead to security vulnerabilities; a typo in a build step could accidentally remove all of your S3 buckets.

It's important for developers to set up an IAM role for CodeBuild local use that's identical to CodeBuild's service role to check anything that needs AWS access. For example, if you use a developer IAM account for local tests that has administrator access to everything, you might not realize that the first step in your build, which downloads configuration files from S3, doesn't work on AWS CodeBuild because it lacks the permissions to accomplish that task.

Instead, developers should build shared policies and attach them to both the CodeBuild service role and the role they use to test builds locally. By using shared policies, developers can make sure that, when a change is made to the local IAM role, the same changes are made to the CodeBuild service role.

This was last published in July 2018

Dig Deeper on AWS application lifecycle management (ALM) tools

Join the conversation

1 comment

Send me notifications when other members comment.

Please create a username to comment.

How do you locally debug issues within your CI/CD pipeline?