Add CodeBuild access permissions to an IAM group or user Create a CodeBuild service role Creating a customer managed key Install and configure the Amazon CLI

Advanced setup

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

We assume you already have an Amazon account. However, if you do not already have one, go to http://www.amazonaws.cn, choose Sign In to the Console, and follow the online instructions.

Topics

Add CodeBuild access permissions to an IAM group or user
Create a CodeBuild service role
Create and configure a customer managed key for CodeBuild
Install and configure the Amazon CLI

Add CodeBuild access permissions to an IAM group or user

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

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

For information about Amazon root accounts and administrator users, see The Amazon Web Services account root user and Creating Your First Amazon Web Services account root user and Group in the user Guide.

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

Open the IAM console at https://console.amazonaws.cn/iam/.

You should have already signed in to the Amazon Web Services Management Console by using one of the following:
- Your Amazon root account. This is not recommended. For more information, see The Amazon Web Services account root user in the user Guide.
- An administrator user in your Amazon account. For more information, see Creating Your First Amazon Web Services account root user and Group in the user Guide.
- An user in your Amazon account with permission to perform the following minimum set of actions:
```
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 user Guide.
In the navigation pane, choose Policies.
To add a custom set of Amazon CodeBuild access permissions to an IAM group or IAM user, skip ahead to step 4 in this procedure.

To add a default set of CodeBuild access permissions to an IAM group or IAM user, choose Policy Type, Amazon Managed, and then do the following:
- To add full access permissions to CodeBuild, select the box named AWSCodeBuildAdminAccess, choose Policy Actions, and then choose Attach. Select the box next to the target IAM group or user, and then choose Attach Policy. Repeat this for the policies named AmazonS3ReadOnlyAccess and IAMFullAccess.
- To add access permissions to CodeBuild for everything except build project administration, select the box named AWSCodeBuildDeveloperAccess, choose Policy Actions, and then choose Attach. Select the box next to the target IAM group or user, and then choose Attach Policy. Repeat this for the policy named AmazonS3ReadOnlyAccess.
- To add read-only access permissions to CodeBuild, select the boxes named AWSCodeBuildReadOnlyAccess. Select the box next to the target IAM group or user, and then choose Attach Policy. Repeat this for the policy named AmazonS3ReadOnlyAccess.
You have now added a default set of CodeBuild access permissions to an IAM group or user. Skip the rest of the steps in this procedure.
Choose Create Policy.
On the Create Policy page, next to Create Your Own Policy, choose Select.
On the Review Policy page, for Policy Name, enter a name for the policy (for example, CodeBuildAccessPolicy). If you use a different name, be sure to use it throughout this procedure.

For Policy Document, enter the following, and then choose Create Policy.


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CodeBuildAccessPolicy",
      "Effect": "Allow",
      "Action": [
        "codebuild:*"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CodeBuildRolePolicy",
      "Effect": "Allow",
      "Action": [
        "iam:PassRole"
      ],
      "Resource": "arn:aws:iam::account-ID:role/role-name"
    },
    {
      "Sid": "CloudWatchLogsAccessPolicy",
      "Effect": "Allow",
      "Action": [
        "logs:FilterLogEvents",
        "logs:GetLogEvents"
      ],
      "Resource": "*"
    },
    {
      "Sid": "S3AccessPolicy",
      "Effect": "Allow",
      "Action": [
        "s3:CreateBucket",
        "s3:GetObject",
        "s3:List*",
        "s3:PutObject"
      ],
      "Resource": "*"
    },
    {
      "Sid": "S3BucketIdentity",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketAcl",
        "s3:GetBucketLocation"
      ],
      "Resource": "*"
    }
  ]
}

Note

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

The CodeBuildRolePolicy statement is required to allow a build project to be created or modified.

In the navigation pane, choose Groups or Users.
In the list of groups or users, choose the name of the IAM group or IAM user to which you want to add CodeBuild access permissions.
For a group, on the group settings page, on the Permissions tab, expand Managed Policies, and then choose Attach Policy.

For a user, on the user settings page, on the Permissions tab, choose Add permissions.
For a group, on the Attach Policy page, select CodeBuildAccessPolicy, and then choose Attach Policy.

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

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

Make sure you have configured the Amazon CLI with the Amazon access key and Amazon 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 Amazon Command Line Interface in the Amazon Command Line Interface User Guide.
To add a custom set of Amazon CodeBuild access permissions to an IAM group or IAM user, skip to step 3 in this procedure.

To add a default set of 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 user:
```
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 user name, and replacing policy-arn once for each of the following policy Amazon Resource Names (ARNs):
- To add full access permissions to 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 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 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 CodeBuild access permissions to an IAM group or user. Skip the rest of the steps in this procedure.

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


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CodeBuildAccessPolicy",
      "Effect": "Allow",
      "Action": [
        "codebuild:*"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CodeBuildRolePolicy",
      "Effect": "Allow",
      "Action": [
        "iam:PassRole"
      ],
      "Resource": "arn:aws:iam::account-ID:role/role-name"
    },
    {
      "Sid": "CloudWatchLogsAccessPolicy",
      "Effect": "Allow",
      "Action": [
        "logs:FilterLogEvents",
        "logs:GetLogEvents"
      ],
      "Resource": "*"
    },
    {
      "Sid": "S3AccessPolicy",
      "Effect": "Allow",
      "Action": [
        "s3:CreateBucket",
        "s3:GetObject",
        "s3:List*",
        "s3:PutObject"
      ],
      "Resource": "*"
    },
    {
      "Sid": "S3BucketIdentity",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketAcl",
        "s3:GetBucketLocation"
      ],
      "Resource": "*"
    }
  ]
}

Note

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

The CodeBuildRolePolicy statement is required to allow a build project to be created or modified.

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, be sure to use them here.

For an IAM group:
```
aws iam put-group-policy --group-name group-name --policy-name CodeBuildGroupAccessPolicy --policy-document file://put-group-policy.json
```
For an user:
```
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 user.

Create a CodeBuild service role

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

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

Important

CodeBuild uses the service role for all operations that are performed on your behalf. If the role includes permissions that the user shouldn't have, you can unintentionally escalate a user's permissions. Ensure that the role grants least privilege.

The service role described on this page contains a policy that grants the minimum permissions required to use CodeBuild. You may need to add additional permissions, depending on your use case.

To create a CodeBuild service role (console)

Open the IAM console at https://console.amazonaws.cn/iam/.

You should have already signed in to the console by using one of the following:
- Your Amazon root account. This is not recommended. For more information, see The Amazon Web Services account root user in the user Guide.
- An administrator user in your Amazon account. For more information, see Creating Your First Amazon Web Services account root user and Group in the user Guide.
- An user in your Amazon account with permission to perform the following minimum set of actions:
```
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 user Guide.
In the navigation pane, choose Policies.
Choose Create Policy.
On the Create Policy page, choose JSON.

For the JSON policy, enter the following, and then choose Review Policy:


{
  "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": "*"
    },
    {
      "Sid": "ECRPullPolicy",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ECRAuthPolicy",
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken"
      ],
      "Resource": "*"
    },
    {
      "Sid": "S3BucketIdentity",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketAcl",
        "s3:GetBucketLocation"
      ],
      "Resource": "*"
    }
  ]
}

Note

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

On the Review Policy page, for Policy Name, enter a name for the policy (for example, CodeBuildServiceRolePolicy), and then choose Create policy.

Note
If you use a different name, be sure to use it throughout this procedure.
In the navigation pane, choose Roles.
Choose Create role.
On the Create role page, with Amazon Service already selected, choose CodeBuild, and then choose Next:Permissions.
On the Attach permissions policies page, select CodeBuildServiceRolePolicy, and then choose Next: Review.
On the Create role and review page, for Role name, enter a name for the role (for example, CodeBuildServiceRole), and then choose Create role.

To create a CodeBuild service role (Amazon CLI)

Make sure you have configured the Amazon CLI with the Amazon access key and Amazon 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 Amazon Command Line Interface in the Amazon Command Line Interface User Guide.

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

create-role.json:


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

Note

We recommend that you use the aws:SourceAccount and aws:SourceArn condition keys to protect yourself against the confused deputy problem. For example, you can edit the previous trust policy with the following condition blocks. The aws:SourceAccount is the owner of the CodeBuild project and the aws:SourceArn is the CodeBuild project ARN.

If you would like to restrict your service role to an Amazon account, create-role.json might look similar to this:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "codebuild.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": [
                        "account-ID"
                    ]
                }
            }
        }
    ]
}

If you would like to restrict your service role to a specific CodeBuild project, create-role.json might look similar to this:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "codebuild.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceArn": "arn:aws:codebuild:region-ID:account-ID:project/project-name"
                }
            }
        }
    ]
}

Note

If you don't know or haven't decided on a name for your CodeBuild project and want a trust policy restriction on a particular ARN pattern, you can replace that portion of the ARN with a wildcard (*). After you create your project, you can then update the trust policy.

put-role-policy.json:


{
  "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": "*"
    },
    {
      "Sid": "S3BucketIdentity",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketAcl",
        "s3:GetBucketLocation"
      ],
      "Resource": "*"
    }
  ]
}

Note

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 use them here.
```
aws iam create-role --role-name CodeBuildServiceRole --assume-role-policy-document file://create-role.json
```
```
aws iam put-role-policy --role-name CodeBuildServiceRole --policy-name CodeBuildServiceRolePolicy --policy-document file://put-role-policy.json
```

Create and configure a customer managed key for CodeBuild

For Amazon CodeBuild to encrypt its build output artifacts, it needs access to a KMS key. By default, CodeBuild uses the Amazon managed key for Amazon S3 in your Amazon account.

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

For information about customer managed keys, see Amazon Key Management Service Concepts and Creating Keys in the Amazon KMS Developer Guide.

To configure a customer managed key for use by CodeBuild, follow the instructions in the "How to Modify a Key Policy" section of Modifying a Key Policy in the Amazon 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.


{
  "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 Amazon region where the Amazon S3 buckets associated with CodeBuild are located (for example, us-east-1).
account-ID represents the ID of the of the Amazon account that owns the customer managed key.
CodeBuild-service-role represents the name of the CodeBuild service role you created or identified earlier in this topic.

Note

To create or configure a customer managed key through the IAM console, you must first sign in to the Amazon Web Services Management Console by using one of the following:

Your Amazon root account. This is not recommended. For more information, see The Account Root User in the user Guide.
An administrator user in your Amazon account. For more information, see Creating Your First Amazon Web Services account root user and Group in the user Guide.
An user in your Amazon account with permission to create or modify the customer managed key. For more information, see Permissions Required to Use the Amazon KMS Console in the Amazon KMS Developer Guide.

Install and configure the Amazon CLI

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

Run the following command to confirm whether your installation of the Amazon CLI supports CodeBuild:
```
aws codebuild list-builds
```
If successful, information similar to the following will appear in the output:
```
{
  "ids": []
}
```
The empty square brackets indicate that you have not yet run any builds.
If an error is output, you must uninstall your current version of the Amazon CLI and then install the latest version. For more information, see Uninstalling the Amazon CLI and Installing the Amazon Command Line Interface in the Amazon Command Line Interface User Guide.

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Advanced topics

Command line reference