Getting started with CodeBuild

1. In an empty directory on your local computer or instance, create this directory structure.

   (root directory name)
       `-- src
            |-- main
            |     `-- java
            `-- test
                  `-- java

2. Using a text editor of your choice, create this file, name it MessageUtil.java, and then save it in the src/main/java directory.

   public class MessageUtil {
     private String message;
   
     public MessageUtil(String message) {
       this.message = message;
     }
   
     public String printMessage() {
       System.out.println(message);
       return message;
     }
   
     public String salutationMessage() {
       message = "Hi!" + message;
       System.out.println(message);
       return message;
     }
   }

   This class file creates as output the string of characters passed into it. The MessageUtil constructor sets the string of characters. The printMessage method creates the output. The salutationMessage method outputs Hi! followed by the string of characters.

3. Create this file, name it TestMessageUtil.java, and then save it in the /src/test/java directory.

   import org.junit.Test;
   import org.junit.Ignore;
   import static org.junit.Assert.assertEquals;
   
   public class TestMessageUtil {
   
     String message = "Robert";    
     MessageUtil messageUtil = new MessageUtil(message);
      
     @Test
     public void testPrintMessage() {      
       System.out.println("Inside testPrintMessage()");     
       assertEquals(message,messageUtil.printMessage());
     }
   
     @Test
     public void testSalutationMessage() {
       System.out.println("Inside testSalutationMessage()");
       message = "Hi!" + "Robert";
       assertEquals(message,messageUtil.salutationMessage());
     }
   }

   This class file sets the message variable in the MessageUtil class to Robert. It then tests to see if the message variable was successfully set by checking whether the strings Robert and Hi!Robert appear in the output.

4. Create this file, name it pom.xml, and then save it in the root (top level) directory.

   <project xmlns="http://maven.apache.org/POM/4.0.0" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>org.example</groupId>
     <artifactId>messageUtil</artifactId>
     <version>1.0</version>
     <packaging>jar</packaging>
     <name>Message Utility Java Sample App</name>
     <dependencies>
       <dependency>
         <groupId>junit</groupId>
         <artifactId>junit</artifactId>
         <version>4.11</version>
         <scope>test</scope>
       </dependency>	
     </dependencies>
     <build>
       <plugins>
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-compiler-plugin</artifactId>
           <version>3.8.0</version>
         </plugin>
       </plugins>
     </build>
   </project>

   Apache Maven uses the instructions in this file to convert the MessageUtil.java and TestMessageUtil.java files into a file named messageUtil-1.0.jar and then run the specified tests.

To create the build project

1. Sign in to the AWS Management Console and open the AWS CodeBuild console at https://console.aws.amazon.com/codesuite/codebuild/home.

2. Use the AWS region selector to choose an AWS Region where CodeBuild is supported. For more information, see AWS CodeBuild endpoints and quotas in the Amazon Web Services General Reference.

3. If a CodeBuild information page is displayed, choose Create build project. Otherwise, on the navigation pane, expand Build, choose Build projects, and then choose Create build project.

4. On the Create build project page, in Project configuration, for Project name, enter a name for this build project (in this example, codebuild-demo-project). Build project names must be unique across each AWS account. If you use a different name, be sure to use it throughout this tutorial.

   Note

   On the Create build project page, you might see an error message similar to the following: You are not authorized to perform this operation.. This is most likely because you signed in to the AWS Management Console as an user who does not have permissions to create a build project.. To fix this, sign out of the AWS Management Console, and then sign back in with credentials belonging to one of the following IAM entities:

   • An administrator user in your AWS account. For more information, see Creating your first AWS account root user and group in the user Guide.

   • An user in your AWS account with the AWSCodeBuildAdminAccess, AmazonS3ReadOnlyAccess, and IAMFullAccess managed policies attached to that user or to an IAM group that the user belongs to. If you do not have an user or group in your AWS account with these permissions, and you cannot add these permissions to your user or group, contact your AWS account administrator for assistance. For more information, see AWS managed (predefined) policies for AWS CodeBuild.

   Both options include administrator permissions that allow you to create a build project so you can complete this tutorial. We recommend that you always use the minimum permissions required to accomplish your task. For more information, see AWS CodeBuild permissions reference.

5. In Source, for Source provider, choose Amazon S3.

6. For Bucket, choose codebuild-region-ID-account-ID-input-bucket.

7. For S3 object key, enter MessageUtil.zip.

8. In Environment, for Environment image, leave Managed image selected.

9. For Operating system, choose Amazon Linux 2.

10. For Runtime(s), choose Standard.

11. For Image, choose aws/codebuild/amazonlinux2-x86_64-standard:4.0.

12. In Service role, leave New service role selected, and leave Role name unchanged.

13. For Buildspec, leave Use a buildspec file selected.

14. In Artifacts, for Type, choose Amazon S3.

15. For Bucket name, choose codebuild-region-ID-account-ID-output-bucket.

16. Leave Name and Path blank.

17. Choose Create build project.

To run the build

1. Open the AWS CodeBuild console at https://console.aws.amazon.com/codesuite/codebuild/home.

2. In the navigation pane, choose Build projects.

3. In the list of build projects, choose codebuild-demo-project, and then choose Start build. The build starts immediately.

1. If the codebuild-demo-project:<build-ID> page is not displayed, in the navigation bar, choose Build history. Next, in the list of build projects, for Project, choose the Build run link for codebuild-demo-project. There should be only one matching link. (If you have completed this tutorial before, choose the link with the most recent value in the Completed column.)

2. On the Build status page, in Phase details, the following build phases should be displayed, with Succeeded in the Status column:

   • SUBMITTED

   • QUEUED

   • PROVISIONING

   • DOWNLOAD_SOURCE

   • INSTALL

   • PRE_BUILD

   • BUILD

   • POST_BUILD

   • UPLOAD_ARTIFACTS

   • FINALIZING

   • COMPLETED

   In Build Status, Succeeded should be displayed.

   If you see In Progress instead, choose the refresh button.

3. Next to each build phase, the Duration value indicates how long the build phase lasted. The End time value indicates when that build phase ended.

To view detailed build information

1. With the build details page still displayed from the previous step, the last 10,000 lines of the build log are displayed in Build logs. To see the entire build log in CloudWatch Logs, choose the View entire log link.

2. In the CloudWatch Logs log stream, you can browse the log events. By default, only the last set of log events is displayed. To see earlier log events, scroll to the beginning of the list.

3. In this tutorial, most of the log events contain verbose information about CodeBuild downloading and installing build dependency files into its build environment, which you probably don't care about. You can use the Filter events box to reduce the information displayed. For example, if you enter "[INFO]" in Filter events, only those events that contain [INFO] are displayed. For more information, see Filter and pattern syntax in the Amazon CloudWatch User Guide.

To get the build output artifact (AWS CodeBuild console)

1. With the CodeBuild console still open and the build details page still displayed from the previous step, choose the Build details tab and scroll down to the Artifacts section.

   Note

   If the build details page is not displayed, in the navigation bar, choose Build history, and then choose the Build run link.

2. The link to the Amazon S3 folder is under the Artifacts upload location. This link opens the folder in Amazon S3 where you find the messageUtil-1.0.jar build output artifact file.

To get the build output artifact (Amazon S3 console)

1. Open the Amazon S3 console at https://console.aws.amazon.com/s3/.

2. Open codebuild-region-ID-account-ID-output-bucket.

3. Open the codebuild-demo-project folder.

4. Open the target folder, where you find the messageUtil-1.0.jar build output artifact file.

1. In an empty directory on your local computer or instance, create this directory structure.

   (root directory name)
       `-- src
            |-- main
            |     `-- java
            `-- test
                  `-- java

2. Using a text editor of your choice, create this file, name it MessageUtil.java, and then save it in the src/main/java directory.

   public class MessageUtil {
     private String message;
   
     public MessageUtil(String message) {
       this.message = message;
     }
   
     public String printMessage() {
       System.out.println(message);
       return message;
     }
   
     public String salutationMessage() {
       message = "Hi!" + message;
       System.out.println(message);
       return message;
     }
   }

   This class file creates as output the string of characters passed into it. The MessageUtil constructor sets the string of characters. The printMessage method creates the output. The salutationMessage method outputs Hi! followed by the string of characters.

3. Create this file, name it TestMessageUtil.java, and then save it in the /src/test/java directory.

   import org.junit.Test;
   import org.junit.Ignore;
   import static org.junit.Assert.assertEquals;
   
   public class TestMessageUtil {
   
     String message = "Robert";    
     MessageUtil messageUtil = new MessageUtil(message);
      
     @Test
     public void testPrintMessage() {      
       System.out.println("Inside testPrintMessage()");     
       assertEquals(message,messageUtil.printMessage());
     }
   
     @Test
     public void testSalutationMessage() {
       System.out.println("Inside testSalutationMessage()");
       message = "Hi!" + "Robert";
       assertEquals(message,messageUtil.salutationMessage());
     }
   }

   This class file sets the message variable in the MessageUtil class to Robert. It then tests to see if the message variable was successfully set by checking whether the strings Robert and Hi!Robert appear in the output.

4. Create this file, name it pom.xml, and then save it in the root (top level) directory.

   <project xmlns="http://maven.apache.org/POM/4.0.0" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>org.example</groupId>
     <artifactId>messageUtil</artifactId>
     <version>1.0</version>
     <packaging>jar</packaging>
     <name>Message Utility Java Sample App</name>
     <dependencies>
       <dependency>
         <groupId>junit</groupId>
         <artifactId>junit</artifactId>
         <version>4.11</version>
         <scope>test</scope>
       </dependency>	
     </dependencies>
     <build>
       <plugins>
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-compiler-plugin</artifactId>
           <version>3.8.0</version>
         </plugin>
       </plugins>
     </build>
   </project>

   Apache Maven uses the instructions in this file to convert the MessageUtil.java and TestMessageUtil.java files into a file named messageUtil-1.0.jar and then run the specified tests.

To create the build project

1. Use the AWS CLI to run the create-project command:

   aws codebuild create-project --generate-cli-skeleton

   JSON-formatted data appears in the output. Copy the data to a file named create-project.json in a location on the local computer or instance where the AWS CLI is installed. If you choose to use a different file name, be sure to use it throughout this tutorial.

   Modify the copied data to follow this format, and then save your results:

   {
     "name": "codebuild-demo-project",
     "source": {
       "type": "S3",
       "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip"
     },
     "artifacts": {
       "type": "S3",
       "location": "codebuild-region-ID-account-ID-output-bucket"
     },
     "environment": {
       "type": "LINUX_CONTAINER",
       "image": "aws/codebuild/standard:5.0",
       "computeType": "BUILD_GENERAL1_SMALL"
     },
     "serviceRole": "serviceIAMRole"
   }

   Replace serviceIAMRole with the Amazon Resource Name (ARN) of a CodeBuild service role (for example, arn:aws:iam::account-ID:role/role-name). To create one, see Allow CodeBuild to interact with other AWS services.

   In this data:

   • name represents a required identifier for this build project (in this example, codebuild-demo-project). Build project names must be unique across all build projects in your account.

   • For source, type is a required value that represents the source code's repository type (in this example, S3 for an Amazon S3 bucket).

   • For source, location represents the path to the source code (in this example, the input bucket name followed by the ZIP file name).

   • For artifacts, type is a required value that represents the build output artifact's repository type (in this example, S3 for an Amazon S3 bucket).

   • For artifacts, location represents the name of the output bucket you created or identified earlier (in this example, codebuild-region-ID-account-ID-output-bucket).

   • For environment, type is a required value that represents the type of build environment (in this example, LINUX_CONTAINER).

   • For environment, image is a required value that represents the Docker image name and tag combination this build project uses, as specified by the Docker image repository type (in this example, aws/codebuild/standard:5.0 for a Docker image in the CodeBuild Docker images repository). aws/codebuild/standard is the name of the Docker image. 5.0 is the tag of the Docker image.

     To find more Docker images you can use in your scenarios, see the Build environment reference.

   • For environment, computeType is a required value that represents the computing resources CodeBuild uses (in this example, BUILD_GENERAL1_SMALL).

   Note

   Other available values in the original JSON-formatted data, such as description, buildspec, auth (including type and resource), path, namespaceType, name (for artifacts), packaging, environmentVariables (including name and value), timeoutInMinutes, encryptionKey, and tags (including key and value) are optional. They are not used in this tutorial, so they are not shown here. For more information, see Create a build project (AWS CLI).

2. Switch to the directory that contains the file you just saved, and then run the create-project command again.

   aws codebuild create-project --cli-input-json file://create-project.json

   If successful, data similar to this appears in the output.

   {
     "project": {
       "name": "codebuild-demo-project",
       "serviceRole": "serviceIAMRole",
       "tags": [],
       "artifacts": {
         "packaging": "NONE",
         "type": "S3",
         "location": "codebuild-region-ID-account-ID-output-bucket",
         "name": "message-util.zip"
       },
       "lastModified": 1472661575.244,
       "timeoutInMinutes": 60,
       "created": 1472661575.244,
       "environment": {
         "computeType": "BUILD_GENERAL1_SMALL",
         "image": "aws/codebuild/standard:5.0",
         "type": "LINUX_CONTAINER",
         "environmentVariables": []
       },
       "source": {
         "type": "S3",
         "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip"
       },
       "encryptionKey": "arn:aws:kms:region-ID:account-ID:alias/aws/s3",
       "arn": "arn:aws:codebuild:region-ID:account-ID:project/codebuild-demo-project"
     }
   }

   • project represents information about this build project.

     • tags represents any tags that were declared.

     • packaging represents how the build output artifact is stored in the output bucket. NONE means that a folder is created in the output bucket. The build output artifact is stored in that folder.

     • lastModified represents the time, in Unix time format, when information about the build project was last changed.

     • timeoutInMinutes represents the number of minutes after which CodeBuild stops the build if the build has not been completed. (The default is 60 minutes.)

     • created represents the time, in Unix time format, when the build project was created.

     • environmentVariables represents any environment variables that were declared and are available for CodeBuild to use during the build.

     • encryptionKey represents the ARN of the customer managed key that CodeBuild used to encrypt the build output artifact.

     • arn represents the ARN of the build project.

To run the build

1. Use the AWS CLI to run the start-build command:

   aws codebuild start-build --project-name project-name

   Replace project-name with your build project name from the previous step (for example, codebuild-demo-project).

2. If successful, data similar to the following appears in the output:

   {
     "build": { 
       "buildComplete": false,
       "initiator": "user-name",   
       "artifacts": { 
         "location": "arn:aws:s3:::codebuild-region-ID-account-ID-output-bucket/message-util.zip"
       },
       "projectName": "codebuild-demo-project",
       "timeoutInMinutes": 60, 
       "buildStatus": "IN_PROGRESS",
       "environment": {
         "computeType": "BUILD_GENERAL1_SMALL",
         "image": "aws/codebuild/standard:5.0",
         "type": "LINUX_CONTAINER",
         "environmentVariables": []
       },
       "source": {
         "type": "S3",
         "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip"
       },
       "currentPhase": "SUBMITTED",
       "startTime": 1472848787.882,
       "id": "codebuild-demo-project:0cfbb6ec-3db9-4e8c-992b-1ab28EXAMPLE",
       "arn": "arn:aws:codebuild:region-ID:account-ID:build/codebuild-demo-project:0cfbb6ec-3db9-4e8c-992b-1ab28EXAMPLE"    
     }
   }

   • build represents information about this build.

     • buildComplete represents whether the build was completed (true). Otherwise, false.

     • initiator represents the entity that started the build.

     • artifacts represents information about the build output, including its location.

     • projectName represents the name of the build project.

     • buildStatus represents the current build status when the start-build command was run.

     • currentPhase represents the current build phase when the start-build command was run.

     • startTime represents the time, in Unix time format, when the build process started.

     • id represents the ID of the build.

     • arn represents the ARN of the build.

   Make a note of the id value. You need it in the next step.

To view summarized build information

• Use the AWS CLI to run the batch-get-builds command.

  aws codebuild batch-get-builds --ids id

  Replace id with the id value that appeared in the output of the previous step.

  If successful, data similar to this appears in the output.

  {
    "buildsNotFound": [],
    "builds": [
      {
        "buildComplete": true,
        "phases": [
          {
            "phaseStatus": "SUCCEEDED",
            "endTime": 1472848788.525,
            "phaseType": "SUBMITTED",
            "durationInSeconds": 0,
            "startTime": 1472848787.882
          },
          ... The full list of build phases has been omitted for brevity ...
          {
            "phaseType": "COMPLETED",
            "startTime": 1472848878.079
          }
        ],
        "logs": {
          "groupName": "/aws/codebuild/codebuild-demo-project",
          "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=region-ID#logEvent:group=/aws/codebuild/codebuild-demo-project;stream=38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE",
          "streamName": "38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE"
        },
        "artifacts": {
          "md5sum": "MD5-hash",
          "location": "arn:aws:s3:::codebuild-region-ID-account-ID-output-bucket/message-util.zip",
          "sha256sum": "SHA-256-hash"
        },
        "projectName": "codebuild-demo-project",
        "timeoutInMinutes": 60,
        "initiator": "user-name",
        "buildStatus": "SUCCEEDED",
        "environment": {
          "computeType": "BUILD_GENERAL1_SMALL",
          "image": "aws/codebuild/standard:5.0",
          "type": "LINUX_CONTAINER",
          "environmentVariables": []
        },
        "source": {
          "type": "S3",
          "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip"
        },
        "currentPhase": "COMPLETED",
        "startTime": 1472848787.882,
        "endTime": 1472848878.079,
        "id": "codebuild-demo-project:38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE",
        "arn": "arn:aws:codebuild:region-ID:account-ID:build/codebuild-demo-project:38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE"      
      }
    ]
  }

  • buildsNotFound represents the build IDs for any builds where information is not available. In this example, it should be empty.

  • builds represents information about each build where information is available. In this example, information about only one build appears in the output.

    • phases represents the set of build phases CodeBuild runs during the build process. Information about each build phase is listed separately as startTime, endTime, and durationInSeconds (when the build phase started and ended, expressed in Unix time format, and how long it lasted, in seconds), and phaseType such as (SUBMITTED, PROVISIONING, DOWNLOAD_SOURCE, INSTALL, PRE_BUILD, BUILD, POST_BUILD, UPLOAD_ARTIFACTS, FINALIZING, or COMPLETED) and phaseStatus (such as SUCCEEDED, FAILED, FAULT, TIMED_OUT, IN_PROGRESS, or STOPPED). The first time you run the batch-get-builds command, there might not be many (or any) phases. After subsequent runs of the batch-get-builds command with the same build ID, more build phases should appear in the output.

    • logs represents information in Amazon CloudWatch Logs about the build's logs.

    • md5sum and sha256sum represent MD5 and SHA-256 hashes of the build's output artifact. These appear in the output only if the build project's packaging value is set to ZIP. (You did not set this value in this tutorial.) You can use these hashes along with a checksum tool to confirm file integrity and authenticity.

      Note

      You can also use the Amazon S3 console to view these hashes. Select the box next to the build output artifact, choose Actions, and then choose Properties. In the Properties pane, expand Metadata, and view the values for x-amz-meta-codebuild-content-md5 and x-amz-meta-codebuild-content-sha256. (In the Amazon S3 console, the build output artifact's ETag value should not be interpreted to be either the MD5 or SHA-256 hash.)

      If you use the AWS SDKs to get these hashes, the values are named codebuild-content-md5 and codebuild-content-sha256.

    • endTime represents the time, in Unix time format, when the build process ended.

  Note

  Amazon S3 metadata has a CodeBuild header named x-amz-meta-codebuild-buildarn which contains the buildArn of the CodeBuild build that publishes artifacts to Amazon S3. The buildArn is added to allow source tracking for notifications and to reference which build the artifact is generated from.

To view detailed build information

1. Use your web browser to go to the deepLink location that appeared in the output in the previous step (for example, https://console.aws.amazon.com/cloudwatch/home?region=region-ID#logEvent:group=/aws/codebuild/codebuild-demo-project;stream=38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE).

2. In the CloudWatch Logs log stream, you can browse the log events. By default, only the last set of log events is displayed. To see earlier log events, scroll to the beginning of the list.

3. In this tutorial, most of the log events contain verbose information about CodeBuild downloading and installing build dependency files into its build environment, which you probably don't care about. You can use the Filter events box to reduce the information displayed. For example, if you enter "[INFO]" in Filter events, only those events that contain [INFO] are displayed. For more information, see Filter and pattern syntax in the Amazon CloudWatch User Guide.

To get the build output artifact (AWS CodeBuild console)

1. With the CodeBuild console still open and the build details page still displayed from the previous step, choose the Build details tab and scroll down to the Artifacts section.

   Note

   If the build details page is not displayed, in the navigation bar, choose Build history, and then choose the Build run link.

2. The link to the Amazon S3 folder is under the Artifacts upload location. This link opens the folder in Amazon S3 where you find the messageUtil-1.0.jar build output artifact file.

To get the build output artifact (Amazon S3 console)

1. Open the Amazon S3 console at https://console.aws.amazon.com/s3/.

2. Open codebuild-region-ID-account-ID-output-bucket.

3. Open the codebuild-demo-project folder.

4. Open the target folder, where you find the messageUtil-1.0.jar build output artifact file.