Run builds locally with the AWS CodeBuild agent - AWS CodeBuild

Run builds locally with the AWS CodeBuild agent

You can use the AWS CodeBuild agent to run CodeBuild builds on a local machine. There are agents available for x86_64 and ARM platforms.

You can also subscribe to receive notifications when new versions of the agent are published.

Prerequisites

Before you begin, you need to do the following:

  • Install Git on your local machine.

  • Install and set up Docker on your local machine.

Set up the build image

You only need to set up the build image the first time you run the agent, or when the image has changed.

To set up the build image

  1. Clone the CodeBuild image repo:

    $ git clone https://github.com/aws/aws-codebuild-docker-images.git
  2. Change to the image directory. For this example, use the aws/codebuild/standard:5.0 image:

    $ cd aws-codebuild-docker-images/ubuntu/standard/5.0
  3. Build the image. This will take several minutes.

    $ docker build -t aws/codebuild/standard:5.0 .
  4. Download the agent.

    To download the x86_64 version of the agent, run the following command:

    $ docker pull amazon/aws-codebuild-local:latest --disable-content-trust=false

    To download the ARM version of the agent, run the following command:

    $ docker pull amazon/aws-codebuild-local:aarch64 --disable-content-trust=false
  5. The CodeBuild agent is available from https://hub.docker.com/r/amazon/aws-codebuild-local/.

    The Secure Hash Algorithm (SHA) signature for the x86_64 version of the agent is:

    sha256:fdfff9470520c53dcd522606a3cc2b5df195ae8a5546697b08249b48175f45ed

    The SHA signature for the ARM version of the agent is:

    sha256:5480b70cf48435e276c21789c61280cfada24e17701ede6386e5d82088bc41ca

    You can use the SHA to identify the version of the agent. To see the agent's SHA signature, run the following command:

    $ docker inspect amazon/aws-codebuild-local

Run the CodeBuild agent

To run the CodeBuild agent

  1. Change to the directory that contains your build project source.

  2. Download the codebuild_build.sh script:

    $ wget https://raw.githubusercontent.com/aws/aws-codebuild-docker-images/master/local_builds/codebuild_build.sh $ chmod +x codebuild_build.sh
  3. Run the codebuild_build.sh script and specify your container image and the output directory.

    To run an x86_64 build, run the following command:

    $ ./codebuild_build.sh -i aws/codebuild/standard:5.0 -a <output directory>

    To run an ARM build, run the following command:

    $ ./codebuild_build.sh -i aws/codebuild/standard:5.0 -a <output directory> -l amazon/aws-codebuild-local:aarch64

    The script launches the build image and runs the build on the project in the current directory. To specify the location of the build project, add the -s <build project directory> option to the script command.

Receive notifications for new CodeBuild agent versions

You can subscribe to Amazon SNS notifications so you will be notified when new versions of the AWS CodeBuild agent are released.

To subscribe to CodeBuild agent notifications

  1. Open the Amazon SNS console at https://console.aws.amazon.com/sns/v3/home.

  2. In the navigation bar, if it's not already selected, change the AWS Region to US East (N. Virginia). You must select this AWS Region because the Amazon SNS notifications that you are subscribing to are created in this Region.

  3. In the navigation pane, choose Subscriptions.

  4. Choose Create subscription.

  5. In Create subscription, do the following:

    1. For Topic ARN, use the following Amazon Resource Name (ARN):

      arn:aws:sns:us-east-1:850632864840:AWS-CodeBuild-Local-Agent-Updates
    2. For Protocol, choose Email or SMS.

    3. For Endpoint, choose where (email or SMS) to receive the notifications. Enter an email or address or phone number, including area code.

    4. Choose Create subscription.

    5. Choose Email to receive an email asking you to confirm your subscription. Follow the directions in the email to complete your subscription.

      If you no longer want to receive these notifications, use the following procedure to unsubscribe.

To unsubscribe from CodeBuild agent notifications

  1. Open the Amazon SNS console at https://console.aws.amazon.com/sns/v3/home.

  2. In the navigation pane, choose Subscriptions.

  3. Select the subscription and from Actions, choose Delete subscriptions. When you are prompted to confirm, choose Delete.