Menu
AWS CodeBuild
User Guide (API Version 2016-10-06)

Advanced Setup

If you follow the steps in Getting Started to access AWS CodeBuild for the first time, most likely you will not need to reference the information in this topic. However, as you continue using AWS CodeBuild, you will want to do things such as give IAM groups and users in your organization access to AWS CodeBuild, modify existing service roles in IAM or customer master keys in AWS KMS to access AWS CodeBuild, or set up the AWS CLI across your organization's workstations to access AWS CodeBuild. This topic describes how to complete the related setup steps.

We assume you already have an AWS account. However, if you do not already have one, go to http://aws.amazon.com, choose Sign In to the Console, and follow the online instructions.

Add AWS CodeBuild Access Permissions to an IAM Group or IAM User

To access AWS CodeBuild with an IAM group or IAM user, you must add access permissions. This section describes how to do this with the IAM console or the AWS CLI.

If you will access AWS CodeBuild with your AWS root account (not recommended) or an administrator IAM user in your AWS account, then you do not need to follow these instructions.

For information about AWS root accounts and administrator IAM users, see The Account Root User and Creating Your First IAM Admin User and Group in the IAM User Guide.

To add AWS CodeBuild access permissions to an IAM group or IAM user (console)

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

    You should have already signed in to the AWS Management Console by using one of the following:

    • Your AWS root account. This is not recommended. For more information, see The Account Root User in the IAM User Guide.

    • An administrator IAM user in your AWS account. For more information, see Creating Your First IAM Admin User and Group in the IAM User Guide.

    • An IAM user in your AWS account with permission to perform the following minimum set of actions:

      Copy
      iam:AttachGroupPolicy iam:AttachUserPolicy iam:CreatePolicy iam:ListAttachedGroupPolicies iam:ListAttachedUserPolicies iam:ListGroups iam:ListPolicies iam:ListUsers

      For more information, see Overview of IAM Policies in the IAM User Guide.

  2. In the navigation pane, choose Policies.

  3. To add a custom set of AWS CodeBuild access permissions to an IAM group or IAM user, skip ahead to step 4 in this procedure.

    To add a default set of AWS CodeBuild access permissions to an IAM group or IAM user, choose Policy Type, AWS Managed, and then do the following:

    • To add full access permissions to AWS CodeBuild, select the box named AWSCodeBuildAdminAccess. Then choose Policy Actions, Attach. Select the box next to the target IAM group or IAM user, and then choose Attach Policy. Repeat this for the policies named AmazonS3ReadOnlyAccess and IAMFullAccess.

    • To add access permissions to AWS CodeBuild for everything except build project administration, select the box named AWSCodeBuildDeveloperAccess. Then choose Policy Actions, Attach. Select the box next to the target IAM group or IAM user, and then choose Attach Policy. Repeat this for the policy named AmazonS3ReadOnlyAccess.

    • To add read-only access permissions to AWS CodeBuild, select the boxes named AWSCodeBuildReadOnlyAccess. Select the box next to the target IAM group or IAM user, and then choose Attach Policy. Repeat this for the policy named AmazonS3ReadOnlyAccess.

    You have now added a default set of AWS CodeBuild access permissions to an IAM group or IAM user. Skip the rest of the steps in this procedure.

  4. Choose Create Policy.

  5. On the Create Policy page, next to Create Your Own Policy, choose Select.

  6. On the Review Policy page, for Policy Name, type a name for the policy (for example, CodeBuildAccessPolicy). If you use a different name, substitute it throughout this procedure.

  7. For Policy Document, type the following, and then choose Create Policy.

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Sid": "CodeBuildDefaultPolicy", "Effect": "Allow", "Action": [ "codebuild:*", "iam:PassRole" ], "Resource": "*" }, { "Sid": "CloudWatchLogsAccessPolicy", "Effect": "Allow", "Action": [ "logs:FilterLogEvents", "logs:GetLogEvents" ], "Resource": "*" }, { "Sid": "S3AccessPolicy", "Effect": "Allow", "Action": [ "s3:CreateBucket", "s3:GetObject", "s3:List*", "s3:PutObject" ], "Resource": "*" } ] }

    Note

    This policy allows access to all AWS CodeBuild actions and to a potentially large number of AWS resources. To restrict permissions to specific AWS CodeBuild actions, change the value of codebuild:* in the AWS CodeBuild policy statement. For more information, see Authentication and Access Control. To restrict access to specific AWS resources, change the value of the Resource object. For more information, see Authentication and Access Control.

  8. In the navigation pane, choose Groups or Users.

  9. In the list of groups or users, choose the name of the IAM group or IAM user to which you want to add AWS CodeBuild access permissions.

  10. For a group, on the group settings page, on the Permissions tab, expand Managed Policies, and choose Attach Policy.

    For a user, on the user settings page, on the Permissions tab, choose Add permissions.

  11. For a group, on the Attach Policy page, select CodeBuildAccessPolicy, and then choose Attach Policy.

    For a user, on the Add permisions page, choose Attach existing policies directly. Select CodeBuildAccessPolicy, choose Next: Reivew, and then choose Add permissions.

To add AWS CodeBuild access permissions to an IAM group or IAM user (AWS CLI)

  1. Make sure you have configured the AWS CLI with the AWS access key and AWS secret access key that correspond to one of the IAM entities, as described in the previous procedure. For more information, see Getting Set Up with the AWS Command Line Interface in the AWS Command Line Interface User Guide.

  2. To add a custom set of AWS CodeBuild access permissions to an IAM group or IAM user, skip ahead to step 3 in this procedure.

    To add a default set of AWS CodeBuild access permissions to an IAM group or IAM user, do the following:

    Run one of the following commands, depending on whether you want to add permissions to an IAM group or IAM user:

    Copy
    aws iam attach-group-policy --group-name group-name --policy-arn policy-arn aws iam attach-user-policy --user-name user-name --policy-arn policy-arn

    You must run the command three times, replacing group-name or user-name with the IAM group name or IAM user name, and replacing policy-arn once for each of the following policy Amazon Resource Names (ARNs):

    • To add full access permissions to AWS CodeBuild, use the following policy ARNs:

      • arn:aws:iam::aws:policy/AWSCodeBuildAdminAccess

      • arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess

      • arn:aws:iam::aws:policy/IAMFullAccess

    • To add access permissions to AWS CodeBuild for everything except build project administration, use the following policy ARNs:

      • arn:aws:iam::aws:policy/AWSCodeBuildDeveloperAccess

      • arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess

    • To add read-only access permissions to AWS CodeBuild, use the following policy ARNs:

      • arn:aws:iam::aws:policy/AWSCodeBuildReadOnlyAccess

      • arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess

    You have now added a default set of AWS CodeBuild access permissions to an IAM group or IAM user. Skip the rest of the steps in this procedure.

  3. In an empty directory on the local workstation or instance where the AWS CLI is installed, create a file named put-group-policy.json or put-user-policy.json. If you use a different file name, substitute it throughout this procedure.

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Sid": "CodeBuildAccessPolicy", "Effect": "Allow", "Action": [ "codebuild:*", "iam:PassRole" ], "Resource": "*" }, { "Sid": "CloudWatchLogsAccessPolicy", "Effect": "Allow", "Action": [ "logs:FilterLogEvents", "logs:GetLogEvents" ], "Resource": "*" }, { "Sid": "S3AccessPolicy", "Effect": "Allow", "Action": [ "s3:CreateBucket", "s3:GetObject", "s3:List*", "s3:PutObject" ], "Resource": "*" } ] }

    Note

    This policy allows access to all AWS CodeBuild actions and to a potentially large number of AWS resources. To restrict permissions to specific AWS CodeBuild actions, change the value of codebuild:* in the AWS CodeBuild policy statement. For more information, see Authentication and Access Control. To restrict access to specific AWS resources, change the value of the related Resource object. For more information, see Authentication and Access Control or the specific AWS service's security documentation.

  4. Switch to the directory where you saved the file, and then run one of the following commands. You can use different values for CodeBuildGroupAccessPolicy and CodeBuildUserAccessPolicy. If you use different values, substitute them here.

    For an IAM group:

    Copy
    aws iam put-group-policy --group-name group-name --policy-name CodeBuildGroupAccessPolicy --policy-document file://put-group-policy.json

    For an IAM user:

    Copy
    aws iam put-user-policy --user-name user-name --policy-name CodeBuildUserAccessPolicy --policy-document file://put-user-policy.json

    In the preceding commands, replace group-name or user-name with the name of the target IAM group or IAM user.

Create an AWS CodeBuild Service Role

You need an AWS CodeBuild service role so that AWS CodeBuild can interact with dependent AWS services on your behalf. You can create an AWS CodeBuild service role by using the AWS CodeBuild or AWS CodePipeline consoles. For information, see:

If you do not plan to use these consoles, this section describes how to create an AWS CodeBuild service role with the IAM console or the AWS CLI.

To create an AWS CodeBuild service role (console)

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

    You should have already signed in to the console by using one of the following:

    • Your AWS root account. This is not recommended. For more information, see The Account Root User in the IAM User Guide.

    • An administrator IAM user in your AWS account. For more information, see Creating Your First IAM Admin User and Group in the IAM User Guide.

    • An IAM user in your AWS account with permission to perform the following minimum set of actions:

      Copy
      iam:AddRoleToInstanceProfile iam:AttachRolePolicy iam:CreateInstanceProfile iam:CreatePolicy iam:CreateRole iam:GetRole iam:ListAttachedRolePolicies iam:ListPolicies iam:ListRoles iam:PassRole iam:PutRolePolicy iam:UpdateAssumeRolePolicy

      For more information, see Overview of IAM Policies in the IAM User Guide.

  2. In the navigation pane, choose Policies.

  3. Choose Create Policy.

  4. On the Create Policy page, next to Create Your Own Policy, choose Select.

  5. On the Review Policy page, for Policy Name, type a name for the policy (for example, CodeBuildServiceRolePolicy). If you use a different name, substitute it throughout this procedure.

  6. For Policy Document, type the following, and then choose Create Policy:

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Sid": "CloudWatchLogsPolicy", "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents" ], "Resource": [ "*" ] }, { "Sid": "CodeCommitPolicy", "Effect": "Allow", "Action": [ "codecommit:GitPull" ], "Resource": [ "*" ] }, { "Sid": "S3GetObjectPolicy", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectVersion" ], "Resource": [ "*" ] }, { "Sid": "S3PutObjectPolicy", "Effect": "Allow", "Action": [ "s3:PutObject" ], "Resource": [ "*" ] } ] }

    Note

    This policy contains statements that allow access to a potentially large number of AWS resources. To restrict AWS CodeBuild to access specific AWS resources, change the value of the Resource array. For more information, see the security documentation for the AWS service.

  7. In the navigation pane, choose Roles.

  8. Choose Create new role.

  9. On the Select role type page, with AWS Service Role already selected, next to AWS CodeBuild, choose Select.

  10. On the Attach Policy page, select CodeBuildServiceRolePolicy, and then choose Next Step.

  11. On the Set role name and review page, for Role name, type a name for the role (for example, CodeBuildServiceRole), and then choose Create role.

To create an AWS CodeBuild service role (AWS CLI)

  1. Make sure you have configured the AWS CLI with the AWS access key and AWS secret access key that correspond to one of the IAM entities, as described in the previous procedure. For more information, see Getting Set Up with the AWS Command Line Interface in the AWS Command Line Interface User Guide.

  2. In an empty directory on the local workstation or instance where the AWS CLI is installed, create two files named create-role.json and put-role-policy.json. If you choose different file names, substitute them throughout this procedure.

    create-role.json:

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "codebuild.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

    put-role-policy.json:

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Sid": "CloudWatchLogsPolicy", "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents" ], "Resource": [ "*" ] }, { "Sid": "CodeCommitPolicy", "Effect": "Allow", "Action": [ "codecommit:GitPull" ], "Resource": [ "*" ] }, { "Sid": "S3GetObjectPolicy", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectVersion" ], "Resource": [ "*" ] }, { "Sid": "S3PutObjectPolicy", "Effect": "Allow", "Action": [ "s3:PutObject" ], "Resource": [ "*" ] } ] }

    Note

    This policy contains statements that allow access to a potentially large number of AWS resources. To restrict AWS CodeBuild to access specific AWS resources, change the value of the Resource array. For more information, see the security documentation for the AWS service.

  3. Switch to the directory where you saved the preceding files, and then run the following two commands, one at a time, in this order. You can use different values for CodeBuildServiceRole and CodeBuildServiceRolePolicy, but be sure to substitute them here.

    Copy
    aws iam create-role --role-name CodeBuildServiceRole --assume-role-policy-document file://create-role.json
    Copy
    aws iam put-role-policy --role-name CodeBuildServiceRole --policy-name CodeBuildServiceRolePolicy --policy-document file://put-role-policy.json

Create and Configure an AWS KMS CMK for AWS CodeBuild

For AWS CodeBuild to encrypt its build output artifacts, it needs access to an AWS KMS customer master key (CMK). By default, AWS CodeBuild uses the AWS-managed CMK for Amazon S3 in your AWS account.

If you do not want to use this CMK, you must create and configure a customer-managed CMK yourself. This section describes how to do this with the IAM console.

For information about CMKs, see AWS Key Management Service Concepts and Creating Keys in the AWS KMS Developer Guide.

To configure a CMK for use by AWS CodeBuild, follow the instructions in the "How to Modify a Key Policy" section of Modifying a Key Policy in the AWS KMS Developer Guide. Then add the following statements (between ### BEGIN ADDING STATEMENTS HERE ### and ### END ADDING STATEMENTS HERE ###) to the key policy. Ellipses (...) are used for brevity and to help you locate where to add the statements. Do not remove any statements, and do not type these ellipses into the key policy.

Copy
{ "Version": "2012-10-17", "Id": "...", "Statement": [ ### BEGIN ADDING STATEMENTS HERE ### { "Sid": "Allow access through Amazon S3 for all principals in the account that are authorized to use Amazon S3", "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*", "Condition": { "StringEquals": { "kms:ViaService": "s3.region-ID.amazonaws.com", "kms:CallerAccount": "account-ID" } } }, { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::account-ID:role/CodeBuild-service-role" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*" }, ### END ADDING STATEMENTS HERE ### { "Sid": "Enable IAM User Permissions", ... }, { "Sid": "Allow access for Key Administrators", ... }, { "Sid": "Allow use of the key", ... }, { "Sid": "Allow attachment of persistent resources", ... } ] }
  • region-ID represents the ID of the AWS region where the Amazon S3 buckets associated with AWS CodeBuild are located (for example, us-east-1).

  • account-ID represents the ID of the of the AWS account that owns the CMK.

  • CodeBuild-service-role represents the name of the AWS CodeBuild service role you created or identified earlier in this topic.

Note

To create or configure a CMK through the IAM console, you must first sign in to the AWS Management Console by using one of the following:

Install and Configure the AWS CLI

To access AWS CodeBuild, you can use the AWS CLI with—or instead of—the AWS CodeBuild console, the AWS CodePipeline console, or the AWS SDKs. To install and configure the AWS CLI, see Getting Set Up with the AWS Command Line Interface in the AWS Command Line Interface User Guide.

  1. Run the following command to confirm whether your installation of the AWS CLI supports AWS CodeBuild:

    Copy
    aws codebuild list-builds

    If successful, information similar to the following will appear in the output:

    Copy
    { "ids": [] }

    The empty square brackets indicate that you have not yet run any builds.

  2. If an error is output, you must uninstall your current version of the AWS CLI and then install the latest version. For more information, see Uninstalling the AWS CLI and Installing the AWS Command Line Interface in the AWS Command Line Interface User Guide.