# CodeBuild service role permissions

IAM policy examples · Updated 17 November 2026

**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.

## 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](https://cloudconsole.dev/iam/assume-role-trust-policy).

## 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 step | Extra permissions |
|---|---|
| `docker push` to ECR | See [ECR push policy](https://cloudconsole.dev/iam/ecr-push-pull) |
| Read a secret in `env.secrets-manager` | `secretsmanager:GetSecretValue` on that secret |
| `env.parameter-store` | `ssm:GetParameters` on those parameters |
| Build in a VPC | The EC2 network-interface actions in the CodeBuild VPC docs |
| CDK or CloudFormation deploy | Usually `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](https://cloudconsole.dev/iam/iam-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 CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [AWS CodeBuild documentation](https://docs.aws.amazon.com/codebuild/)
- [Actions, resources, and condition keys for AWS CodeBuild](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awscodebuild.html)

## Related

- [IAM policy: push and pull one ECR repository](https://cloudconsole.dev/iam/ecr-push-pull)
- [iam:PassRole: policy example and why it matters](https://cloudconsole.dev/iam/iam-passrole)
- [GitHub Actions OIDC: IAM role trust policy](https://cloudconsole.dev/iam/github-actions-oidc)
- [How to retry a failed CodePipeline stage](https://cloudconsole.dev/how-to/retry-failed-codepipeline-stage)
- [IAM role trust policy: examples and how it works](https://cloudconsole.dev/iam/assume-role-trust-policy)
- [ABAC: tag-based access control policy example](https://cloudconsole.dev/iam/abac-tags)

---

Source: https://cloudconsole.dev/iam/codebuild-service-role

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
