How to improve build performance and save time using local caching in AWS CodeBuild?

How to improve build performance and save time using local caching in AWS CodeBuild?

In this post, we will show you how to improve build performance and save time using local caching in AWS CodeBuild. This way to help you speed up deployment steps when using AWS Codebuild.
Local caching stores a cache on a build host. The cache is available to that build host only for a limited time and until another build is complete. For example, when you are dealing with large Java projects, compilation might take a long time. You can speed up subsequent builds by using local caching. This is a good option for large intermediate build artifacts because the cache is immediately available on the build host.

Local caching increases build performance for:

Projects with a large, monolithic source code repository.
Projects that generate and reuse many intermediate build artifacts.
Projects that build large Docker images.
Projects with many source dependencies.

Local caching supports the following caching modes:

Source cache mode caches Git metadata for primary and secondary sources. After the cache is created, subsequent builds pull only the change between commits. This mode is a good choice for projects with a clean working directory and a source that is a large Git repository. If you choose this option and your project does not use a Git repository (GitHub, GitHub Enterprise, or Bitbucket), the option is ignored. No changes are required in the buildspec file.

Docker layer cache mode caches existing Docker layers. This mode is a good choice for projects that build or pull large Docker images. It can prevent the performance issues caused by pulling large Docker images down from the network.


  • You can use a Docker layer cache in the Linux environment only.
  • The privileged flag must be set so that your project has the required Docker permissions
  • You should consider the security implications before you use a Docker layer cache.

Custom cache mode caches directories you specify in the buildspec file. This mode is a good choice if your build scenario is not suited to one of the other two local cache modes. If you use a custom cache:

  • Only directories can be specified for caching. You cannot specify individual files.
  • Symlinks are used to reference cached directories.
  • Cached directories are linked to your build before it downloads its project sources. Cached items are overridden if a source item has the same name. Directories are specified using cache paths in the buildspec file.

Create a sample build project:

1. Open the AWS CodeBuild console at
2. If a welcome page is displayed, choose Get started.
If a welcome page is not displayed, on the navigation pane, choose Build projects, and then choose Create project.
3. On the Configure your project page, for Project name, type a name for this build project. Build project names must be unique across each AWS account. to improve build performance for awscodebuild

4. In Source: What to build, for Source provider, choose GitHub.

  • For Repository, select Use a public repository
  • For Repository URL, type to improve build performance for aws codebuild

5. In Environment: How to build, for Environment image, select Use an image managed by AWS CodeBuild.

  • For Operating system, choose Ubuntu.
  • For Runtime, choose Java.
  • For Version, choose aws/codebuild/java:openjdk-8.
  • For Build specification, select Insert build commands.

Note: The build specification file (buildspec.yml) can be configured in two ways. You can package it along with your source root directory, or you can override it by using a project environment configuration. In this example, I will use the override option and will use the console editor to specify the build specification. to improve build performance for aws codebuild

6. Under Build commands, click Switch to editor to enter the build specification.
Copy the following text.

version: 0.2
- echo "Enter pre_build commands"
- echo "Enter build commands"cache:
- '/root/.m2/**/*'
- '/root/.npm/**/*'
- 'build/**/*'

7. In Artifacts: Where to put the artifacts from this build project:

For Type, choose No artifacts. to improve build performance for aws codebuild

8. In Cache:
Choose Custom cache to improve build performance for aws codebuild

Then review build and cache behavior

In the first run, where no cache exists, overall build time would look something like below (notice the time for DOWNLOAD_SOURCE, BUILD and POST_BUILD): to improve build performance for aws codebuild

Let’s try another build with the same CodeBuild project. This time the build should pick up the dependencies from the cache.
In the second run, there was a cache hit (cache was generated from the first run): to improve build performance for aws codebuild

When build done you’ll notice a few things:

  • DOWNLOAD_SOURCE took slightly longer. Because, in addition to the source code, this time the build also downloaded the cache from user’s s3 bucket.
  • BUILD time was faster. As the dependencies didn’t need to get downloaded, but were reused from cache.
  • POST_BUILD took slightly longer, but was relatively the same.
    Overall, build duration was improved with cache.

Enable AWS Codebuild local caching by using AWS Cloudformation

    Type: AWS::CodeBuild::Project
      Name: MyProject
      ServiceRole: service-role
        Type: S3
        Location: myBucket
        Name: myArtifact
        EncryptionDisabled: true
        OverrideArtifactName: true
        ComputeType: BUILD_GENERAL1_SMALL
        Image: aws/codebuild/standard:2.0
        Certificate: bucket/
        # PrivilegedMode must be true if you specify LOCAL_DOCKER_LAYER_CACHE
        PrivilegedMode: true
        Type: GITHUB
        Location: github-location
        InsecureSsl: true
        GitCloneDepth: 1
        ReportBuildStatus: false
      TimeoutInMinutes: 10
        Type: LOCAL
        Modes: # You can specify one or more cache mode, 


Share this post

Leave a Reply

Your email address will not be published. Required fields are marked *