{"id":9511,"library":"aws-cdk-aws-codebuild","title":"AWS CDK CodeBuild Construct Library (v1)","description":"The `aws-cdk.aws-codebuild` package is part of the AWS Cloud Development Kit (CDK) v1, providing constructs for defining AWS CodeBuild resources programmatically in Python. It allows users to create, configure, and manage CodeBuild projects, build specifications, and associated resources. While AWS CDK v2 is the latest major version, v1 continues to receive maintenance updates for existing projects. Releases for CDK v1 often align with new AWS service features or bug fixes, typically on a weekly or bi-weekly cadence.","status":"active","version":"1.204.0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["aws","cdk","codebuild","iac","cloud","devops","cicd"],"install":[{"cmd":"pip install aws-cdk.aws-codebuild==1.204.0","lang":"bash","label":"Install specific v1 version"},{"cmd":"pip install \"aws-cdk.aws-codebuild<2.0.0\"","lang":"bash","label":"Install latest v1 version"}],"dependencies":[{"reason":"Provides core CDK constructs, app, and stack definitions, essential for any CDK application.","package":"aws-cdk.core","optional":false},{"reason":"Frequently used with CodeBuild for source artifacts, build outputs, or caching.","package":"aws-cdk.aws-s3","optional":true}],"imports":[{"note":"This import path is specific to AWS CDK v1. AWS CDK v2 consolidates all constructs under `aws_cdk_lib`.","wrong":"from aws_cdk_lib import aws_codebuild as codebuild","symbol":"Project","correct":"from aws_cdk import aws_codebuild as codebuild"},{"note":"When using `aws-cdk.aws-codebuild` (v1), ensure your imports correctly reference `aws_cdk.aws_codebuild`.","wrong":"from aws_cdk_lib import aws_codebuild","symbol":"Source","correct":"from aws_cdk import aws_codebuild as codebuild"},{"note":"While direct import works, aliasing `aws_codebuild` as `codebuild` is a common convention for brevity and readability.","wrong":"import aws_cdk.aws_codebuild","symbol":"BuildSpec","correct":"from aws_cdk import aws_codebuild as codebuild"}],"quickstart":{"code":"import os\nfrom aws_cdk import (  # type: ignore\n    core as cdk,\n    aws_codebuild as codebuild\n)\n\nclass MyCodeBuildStack(cdk.Stack):\n    def __init__(self, scope: cdk.App, construct_id: str, **kwargs) -> None:\n        super().__init__(scope, construct_id, **kwargs)\n\n        # Define a simple CodeBuild project that prints a message\n        codebuild.Project(\n            self,\n            \"MySimpleBuildProject\",\n            project_name=\"MySimpleBuildProject\",\n            build_spec=codebuild.BuildSpec.from_object({\n                \"version\": \"0.2\",\n                \"phases\": {\n                    \"install\": {\n                        \"commands\": [\n                            \"echo 'Installing dependencies...'\"\n                        ]\n                    },\n                    \"build\": {\n                        \"commands\": [\n                            \"echo 'Hello from CodeBuild!'\",\n                            \"env\"\n                        ]\n                    }\n                },\n                \"artifacts\": {\n                    \"files\": []\n                }\n            }),\n            source=codebuild.Source.no_source(), # No external source needed for this basic example\n            environment=codebuild.BuildEnvironment(\n                build_image=codebuild.LinuxBuildImage.STANDARD_5_0\n            )\n        )\n\napp = cdk.App()\nMyCodeBuildStack(app, \"CodeBuildQuickstartStack\")\napp.synth()","lang":"python","description":"This quickstart demonstrates how to define a basic AWS CodeBuild project using AWS CDK v1. It creates a project with an inline build specification that prints a message during the build phase and uses `Source.no_source()` for simplicity. For deployment, ensure your AWS environment is configured (e.g., `aws configure`) and you have bootstrapped your CDK environment (`cdk bootstrap`). You can then run `cdk synth` to generate CloudFormation or `cdk deploy` to deploy it."},"warnings":[{"fix":"For new projects, strongly consider using AWS CDK v2 (`pip install aws-cdk-lib`). For existing v1 projects, ensure `aws-cdk.core` and specific `aws-cdk.aws-*` packages are installed and use v1 import patterns. Refer to the official AWS CDK v2 upgrade guide for migration details.","message":"AWS CDK v1 (`aws-cdk.*` packages) and v2 (`aws-cdk-lib`) have fundamentally different import paths and API structures. Using v1 packages with v2 imports, or vice-versa, will lead to `ModuleNotFoundError` or `AttributeError`.","severity":"breaking","affected_versions":"All versions of aws-cdk-aws-codebuild (v1) when mixing with aws-cdk-lib (v2)."},{"fix":"Review the CodeBuild logs carefully for access denied messages. Grant necessary IAM permissions to the `project.role` using methods like `project.role.add_to_policy()`, or define a custom `iam.Role` and assign it to the project. Always use `cdk diff` to inspect IAM policy changes before deploying.","message":"CodeBuild projects require an IAM service role with explicit permissions to access any AWS resources they interact with (e.g., S3 buckets for artifacts, ECR repositories for images, KMS keys, etc.). Missing permissions are a frequent cause of build failures.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Validate your `BuildSpec` YAML syntax. Consult the official AWS CodeBuild User Guide for the correct `BuildSpec` schema and examples. Test complex `BuildSpec` files in a controlled environment or iterate quickly with small changes.","message":"The `BuildSpec` configuration is sensitive to syntax and content. Incorrect YAML, invalid phase names, or commands referencing non-existent paths/executables will cause the build to fail.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"If using CDK v1, run `pip install aws-cdk.aws-codebuild`. If intending to use CDK v2, install `aws-cdk-lib` and update your imports to `from aws_cdk_lib import aws_codebuild`.","cause":"The `aws-cdk.aws-codebuild` package (for CDK v1) is not installed, or you might be trying to use v1 imports while having only `aws-cdk-lib` (CDK v2) installed.","error":"ModuleNotFoundError: No module named 'aws_cdk.aws_codebuild'"},{"fix":"If you are using CDK v2, change your import statement to `from aws_cdk_lib import aws_codebuild as codebuild`. If you intend to use v1, ensure only v1 packages are installed (`aws-cdk.core`, `aws-cdk.aws-codebuild`) and no v2 packages like `aws-cdk-lib`.","cause":"This error occurs when `aws-cdk-lib` (CDK v2) is installed, but the code attempts to use a v1 import path like `from aws_cdk import aws_codebuild`. In v2, all constructs are consolidated under `aws_cdk_lib`.","error":"AttributeError: module 'aws_cdk' has no attribute 'aws_codebuild'"},{"fix":"Inspect the detailed build logs in the AWS CodeBuild console for specific error messages. These logs will usually pinpoint the exact line in your `BuildSpec` that failed, or indicate a permissions issue (`AccessDenied`). Address the root cause based on log output.","cause":"A generic build failure. Common culprits are misconfigured `BuildSpec`, insufficient IAM permissions for the CodeBuild service role, or issues with the source code or build environment.","error":"CodeBuild project failed with exit code 1"}]}