The Buildspec File
Start course

In this course, we explain the basics of AWS CodeBuild and how it can be used to compile, build, and test your source code. 

Learning Objectives

By the end of this course, you will have a greater understanding of the AWS CodeBuild service, including 

  • What the service is and the benefit it provides 
  • What a buildspec file is 
  • How to use AWS CodeBuild to create a deployable artifact 

Intended Audience

  • Those who are implementing and managing software builds on AWS
  • Those who are looking to take a certification, such as the AWS Certified Developer - Associate certification



Let’s look at the buildspec file in a bit more detail. For CodeBuild to properly use your buildspec file, you need to first name the file buildspec.yml and then place it in the root directory of your source code. This enables the CodeBuild service to find your instructions. However, you can override the name of the file and the location of the file if you choose. 

The buildspec is made up of nine different sections: 

The first section is where you specify the version of the buildspec. AWS recommends that you currently use 0.2 - the latest version.  This is a required section, meaning you must specify the current version. 

The second section is “Run-as”, which is only available for Linux users. This is where you specify a Linux user that CodeBuild uses to run all the commands in the file. You can optionally choose to specify this information later for each build phase. 

Next is the environment section, which enables you to define custom environment variables. In this section, you can also choose to retrieve values from the Systems Manager Parameter Store and Secrets Manager. 

Then there’s the proxy section, which provides additional settings if you choose to run your build in a proxy server. For example, a setting you can select is if you’d like the server to create CloudWatch logs or not. 

The batch section. With this section, you can specify instructions on batching your builds. For example, you can specify the behavior of your batch build if one or more build tasks fail. 

Then there’s arguably the most important section: phases. This is another required section. Here you specify the commands for your build. There are four main build phases in this section: install, pre-build, build, and post-build. You can specify commands for each of these phases. Additionally, if you’re using Linux, you can also specify run-as, and provide a user with appropriate permissions to execute these commands. 

The next section is reports. If you run functional or integration tests in CodeBuild, you can generate test reports and see information like number of passes, pass rate percentage, and duration of tests. In the buildspec, you can optionally choose to create a report group, and specify where CodeBuild can find the raw test data. 

Artifacts is the section where you specify where CodeBuild can find the output artifact, and how it can prepare to store that in Amazon S3

Last but not least, is cache. CodeBuild enables you to cache your content. This is helpful for files, such as dependencies that won’t often change from build to build. It enables you to reduce your build time by pulling this content from the cache, instead of redownloading it every time your build environment might need it. You can choose a local cache that’s available locally on the build host or Amazon S3. In the buildspec, you specify the paths to the files that will be cached. 

Let’s take a look at an example of a buildspec file that instructs CodeBuild to compile a Docker image. In this example, the buildspec file starts with the version 0.2. Then it has three build phases: pre-build, build, and post-build. Notice that it includes none of the optional sections of the buildspec - it only uses the two required sections: version and phases. 

In the pre-build phase, it runs two commands: an echo statement which is helpful for debugging and then it runs the command aws ecr get-login-password. This logs into ECR so that it can access the ECR repository. 

In the build phase, it runs two echo commands, then runs the docker build command on the image, which builds the image from the Dockerfile. Last, it runs the docker tag command, which helps label the image with descriptive information.  

In the post-build phase, it again runs two echo commands, then uses the docker push command to push the newly created image into the ECR repository. 

Assuming that a Docker file existed in the same directory as this buildspec file, CodeBuild will go ahead and build the required Docker image as per the instructions contained within the Docker file. That’s it for this one - see you next time. 

About the Author
Learning Paths

Alana Layton is an experienced technical trainer, technical content developer, and cloud engineer living out of Seattle, Washington. Her career has included teaching about AWS all over the world, creating AWS content that is fun, and working in consulting. She currently holds six AWS certifications. Outside of Cloud Academy, you can find her testing her knowledge in bar trivia, reading, or training for a marathon.