CloudConsole

CodeBuild service role permissions

Updated 17 November 2026 · How we write and check guides

Short answer

A CodeBuild service role trusts codebuild.amazonaws.com and needs CloudWatch Logs for the project's log group, S3 access to the artifact bucket, and codebuild report permissions if you publish test reports. Add only what the buildspec itself calls, such as ECR push or a deploy to S3.

Policy diagram: 4 statement(s); first Allow logs:CreateLogGroup, logs:CreateLogStream… on logs…
The policy on this page drawn statement by statement: who it applies to, the actions, the resources and any condition.

The policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BuildLogs",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": [
        "arn:aws:logs:eu-west-2:123456789012:log-group:/aws/codebuild/my-app-build",
        "arn:aws:logs:eu-west-2:123456789012:log-group:/aws/codebuild/my-app-build:*"
      ]
    },
    {
      "Sid": "Artifacts",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:GetObjectVersion",
        "s3:PutObject"
      ],
      "Resource": "arn:aws:s3:::my-pipeline-artifacts/*"
    },
    {
      "Sid": "ArtifactBucketInfo",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketAcl",
        "s3:GetBucketLocation"
      ],
      "Resource": "arn:aws:s3:::my-pipeline-artifacts"
    },
    {
      "Sid": "TestReports",
      "Effect": "Allow",
      "Action": [
        "codebuild:CreateReportGroup",
        "codebuild:CreateReport",
        "codebuild:UpdateReport",
        "codebuild:BatchPutTestCases",
        "codebuild:BatchPutCodeCoverages"
      ],
      "Resource": "arn:aws:codebuild:eu-west-2:123456789012:report-group/my-app-build-*"
    }
  ]
}

Trust policy: "Principal": {"Service": "codebuild.amazonaws.com"} with sts:AssumeRole, as in trust policy examples.

What each statement is for

  • BuildLogs: CodeBuild streams build output to /aws/codebuild/<project> by default. Without it the build may run but the console shows no logs.
  • Artifacts / ArtifactBucketInfo: read the source zip CodePipeline put in the artifact bucket and write the output artifact back. The bucket-level reads are part of the console's default policy.
  • TestReports: only if the buildspec has a reports section. Report groups are named after the project by default.

This matches the shape of the policy the console generates for a new project, minus the wildcards it sometimes adds.

Add what the build does

Build stepExtra permissions
docker push to ECRSee ECR push policy
Read a secret in env.secrets-managersecretsmanager:GetSecretValue on that secret
env.parameter-storessm:GetParameters on those parameters
Build in a VPCThe EC2 network-interface actions in the CodeBuild VPC docs
CDK or CloudFormation deployUsually sts:AssumeRole on the CDK deploy roles, not broad permissions here

When CodePipeline starts the build

The pipeline's service role needs permission to start and watch the build:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RunBuildProject",
      "Effect": "Allow",
      "Action": [
        "codebuild:StartBuild",
        "codebuild:BatchGetBuilds"
      ],
      "Resource": "arn:aws:codebuild:eu-west-2:123456789012:project/my-app-build"
    }
  ]
}
aws iam put-role-policy --role-name codebuild-my-app-build \
  --policy-name build-basics --policy-document file://codebuild.json

Find the missing permission

When a build fails on permissions, the build log shows the AWS error from inside the container, including the action and resource. For failures before the build starts (downloading source, writing logs), the error is on the build's phase details instead.

aws codebuild batch-get-builds --ids my-app-build:0f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b \
  --query 'builds[0].phases[?phaseStatus==`FAILED`].[phaseType,contexts[0].message]' 

Common mistakes

  • Attaching AdministratorAccess to the build role. Anything in the repository, including a dependency's install script, can then do anything in the account.
  • KMS-encrypted artifact bucket: add kms:Decrypt and kms:GenerateDataKey on the pipeline's key.
  • Forgetting iam:PassRole for whoever creates the project; see PassRole.
  • Using the same role for every project: each project gets the union of all permissions.

Questions

What permissions does a CodeBuild service role need?

CloudWatch Logs for its log group, S3 for source and artifacts, report-group permissions if you publish test reports, and whatever AWS calls the buildspec makes.

What permissions does CodePipeline need to run CodeBuild?

The pipeline service role needs codebuild:StartBuild and codebuild:BatchGetBuilds on the build project.

When this happens away from your desk

A failed build at the end of the day is often a permissions change. The failed phase and its log, viewable from a phone, usually name the missing action.

About the app → · Download on the App Store

Sources