OpenMCF logoOpenMCF

Loading...

AWS CodeBuild Project

Deploys an AWS CodeBuild project with configurable source providers, build environments, artifact outputs, and an optional webhook for automatic build triggers. Supports GitHub, Bitbucket, GitLab, CodeCommit, S3, and CodePipeline source types.

What Gets Created

When you deploy an AwsCodeBuildProject resource, OpenMCF provisions:

  • CodeBuild Project — an aws_codebuild_project resource with the specified source, environment, artifacts, and logging configuration
  • Webhook — created only when webhook is configured, registers a webhook with the source provider for automatic build triggers on push and pull request events
  • VPC Configuration — created only when vpcConfig is configured, places the build environment inside a VPC for access to private resources

Prerequisites

  • AWS credentials configured via environment variables or OpenMCF provider config
  • An IAM service role granting CodeBuild permission to access source code, write artifacts, and publish logs
  • A source repository accessible to CodeBuild (GitHub via CodeStar Connections, CodeCommit, Bitbucket, GitLab, or S3)
  • An S3 bucket if using S3 artifacts or S3 cache
  • VPC, subnets, and security groups if running builds inside a VPC
  • A KMS key if custom encryption for build artifacts is required

Quick Start

Create a file codebuild.yaml:

apiVersion: aws.openmcf.org/v1
kind: AwsCodeBuildProject
metadata:
  name: my-build
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.AwsCodeBuildProject.my-build
spec:
  region: us-west-2
  source:
    type: GITHUB
    location: https://github.com/my-org/my-app.git
  environment:
    type: LINUX_CONTAINER
    computeType: BUILD_GENERAL1_SMALL
    image: aws/codebuild/amazonlinux2-x86_64-standard:5.0
  artifacts:
    type: NO_ARTIFACTS
  serviceRole:
    value: arn:aws:iam::123456789012:role/codebuild-service-role

Deploy:

openmcf apply -f codebuild.yaml

This creates a CodeBuild project that pulls from a GitHub repository, runs builds in a standard Linux container, and produces no stored artifacts (CI-only).

Configuration Reference

Required Fields

FieldTypeDescriptionValidation
regionstringAWS region where the project will be created (e.g., us-west-2).Required
source.typestringSource provider: GITHUB, BITBUCKET, CODECOMMIT, CODEPIPELINE, GITHUB_ENTERPRISE, GITLAB, GITLAB_SELF_MANAGED, NO_SOURCE, S3Must be one of the listed values
source.locationstringRepository URL or S3 pathRequired unless type is CODEPIPELINE or NO_SOURCE
environment.typestringContainer type: LINUX_CONTAINER, LINUX_GPU_CONTAINER, ARM_CONTAINER, WINDOWS_SERVER_2019_CONTAINER, WINDOWS_SERVER_2022_CONTAINER, LINUX_LAMBDA_CONTAINER, ARM_LAMBDA_CONTAINERMust be one of the listed values
environment.computeTypestringCompute capacity: BUILD_GENERAL1_SMALL through BUILD_GENERAL1_2XLARGE, or BUILD_LAMBDA_1GB through BUILD_LAMBDA_10GBMust be one of the listed values
environment.imagestringDocker image for the build environment (e.g., aws/codebuild/amazonlinux2-x86_64-standard:5.0)Required, non-empty
artifacts.typestringArtifact output type: NO_ARTIFACTS, S3, CODEPIPELINEMust be one of the listed values. Must be CODEPIPELINE when source is CODEPIPELINE
serviceRoleStringValueOrRefIAM role ARN for CodeBuild. Can reference an AwsIamRole resource via valueFrom.Required

Optional Fields

FieldTypeDefaultDescription
descriptionstring—Project description (max 255 characters)
encryptionKeyStringValueOrRefAWS-managed keyKMS key ARN for artifact encryption. Can reference AwsKmsKey via valueFrom.
buildTimeoutint60Build timeout in minutes (5-2160)
queuedTimeoutint480Queue timeout in minutes (5-480)
concurrentBuildLimitintUnlimitedMaximum concurrent builds (minimum 1)
sourceVersionstring—Default branch, tag, or commit to build
source.buildspecstringbuildspec.ymlBuild specification file path or inline YAML. Required when type is NO_SOURCE.
source.gitCloneDepthintFull cloneGit clone depth (0 = full clone)
source.reportBuildStatusboolfalseReport build status back to the source provider
source.fetchSubmodulesboolfalseFetch Git submodules during source download
environment.privilegedModeboolfalseEnable Docker daemon access inside the build container
environment.imagePullCredentialsTypestringCODEBUILDImage pull credentials: CODEBUILD or SERVICE_ROLE
environment.environmentVariableslist[]Build environment variables with name, value, and optional type (PLAINTEXT, PARAMETER_STORE, SECRETS_MANAGER)
environment.registryCredentialobject—Private registry credentials (credential ARN, credentialProvider: SECRETS_MANAGER)
artifacts.locationStringValueOrRef—S3 bucket name. Required when type is S3. Can reference AwsS3Bucket via valueFrom.
artifacts.namestring—Artifact output name
artifacts.pathstring—S3 prefix path for artifacts
artifacts.packagingstringNONEPackaging type: NONE or ZIP
artifacts.namespaceTypestringNONENamespace: NONE or BUILD_ID
artifacts.encryptionDisabledboolfalseDisable artifact encryption
cache.typestringNO_CACHECache type: NO_CACHE, S3, or LOCAL
cache.locationStringValueOrRef—S3 cache location. Required when type is S3. Can reference AwsS3Bucket via valueFrom.
cache.modesstring[][]Local cache modes: LOCAL_SOURCE_CACHE, LOCAL_DOCKER_LAYER_CACHE, LOCAL_CUSTOM_CACHE
logsConfig.cloudwatchLogs.statusstringENABLEDCloudWatch logging: ENABLED or DISABLED
logsConfig.cloudwatchLogs.groupNameStringValueOrRefAuto-generatedLog group name. Can reference AwsCloudwatchLogGroup via valueFrom.
logsConfig.cloudwatchLogs.streamNamestringAuto-generatedLog stream name prefix
logsConfig.s3Logs.statusstringDISABLEDS3 logging: ENABLED or DISABLED
logsConfig.s3Logs.locationStringValueOrRef—S3 bucket and prefix for logs. Can reference AwsS3Bucket via valueFrom.
logsConfig.s3Logs.encryptionDisabledboolfalseDisable log file encryption
vpcConfig.vpcIdStringValueOrRef—VPC ID. Can reference AwsVpc via valueFrom. Required if vpcConfig is set.
vpcConfig.subnetIdsStringValueOrRef[]—VPC subnets (max 16). Can reference AwsVpc via valueFrom. Required if vpcConfig is set.
vpcConfig.securityGroupIdsStringValueOrRef[]—Security groups (max 5). Can reference AwsSecurityGroup via valueFrom. Required if vpcConfig is set.
webhook.buildTypestringBUILDWebhook build type: BUILD or BUILD_BATCH
webhook.filterGroupslist[]Filter groups (OR'd). Each group contains filters (AND'd) with type, pattern, and optional excludeMatchedPattern.

Examples

GitHub CI with Webhook

A standard CI project triggered by pushes and pull requests on the main branch:

apiVersion: aws.openmcf.org/v1
kind: AwsCodeBuildProject
metadata:
  name: app-ci
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.AwsCodeBuildProject.app-ci
spec:
  region: us-west-2
  source:
    type: GITHUB
    location: https://github.com/my-org/my-app.git
    reportBuildStatus: true
  environment:
    type: LINUX_CONTAINER
    computeType: BUILD_GENERAL1_SMALL
    image: aws/codebuild/amazonlinux2-x86_64-standard:5.0
  artifacts:
    type: NO_ARTIFACTS
  serviceRole:
    value: arn:aws:iam::123456789012:role/codebuild-role
  webhook:
    filterGroups:
      - filters:
          - type: EVENT
            pattern: PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED
          - type: HEAD_REF
            pattern: ^refs/heads/main$

Docker Build with Layer Caching

A privileged build project for Docker image builds with local layer caching:

apiVersion: aws.openmcf.org/v1
kind: AwsCodeBuildProject
metadata:
  name: docker-builder
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.AwsCodeBuildProject.docker-builder
spec:
  region: us-west-2
  source:
    type: GITHUB
    location: https://github.com/my-org/my-service.git
    gitCloneDepth: 1
    reportBuildStatus: true
  environment:
    type: LINUX_CONTAINER
    computeType: BUILD_GENERAL1_LARGE
    image: aws/codebuild/amazonlinux2-x86_64-standard:5.0
    privilegedMode: true
    environmentVariables:
      - name: ECR_REPO
        value: 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-service
      - name: DOCKER_BUILDKIT
        value: "1"
  artifacts:
    type: NO_ARTIFACTS
  serviceRole:
    value: arn:aws:iam::123456789012:role/codebuild-docker-role
  buildTimeout: 30
  cache:
    type: LOCAL
    modes:
      - LOCAL_DOCKER_LAYER_CACHE
      - LOCAL_SOURCE_CACHE
  webhook:
    filterGroups:
      - filters:
          - type: EVENT
            pattern: PUSH
          - type: HEAD_REF
            pattern: ^refs/heads/main$

CodePipeline Build Stage

A build project designed as a stage in AWS CodePipeline with Secrets Manager variables:

apiVersion: aws.openmcf.org/v1
kind: AwsCodeBuildProject
metadata:
  name: pipeline-build
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.AwsCodeBuildProject.pipeline-build
spec:
  region: us-west-2
  source:
    type: CODEPIPELINE
    buildspec: buildspec.yml
  environment:
    type: LINUX_CONTAINER
    computeType: BUILD_GENERAL1_MEDIUM
    image: aws/codebuild/amazonlinux2-x86_64-standard:5.0
    environmentVariables:
      - name: STAGE
        value: production
      - name: DB_CONNECTION_STRING
        value: prod/db-connection-string
        type: SECRETS_MANAGER
  artifacts:
    type: CODEPIPELINE
  serviceRole:
    value: arn:aws:iam::123456789012:role/codebuild-pipeline-role
  buildTimeout: 20
  concurrentBuildLimit: 3

Using Foreign Key References

Reference other OpenMCF-managed resources instead of hardcoding IDs:

apiVersion: aws.openmcf.org/v1
kind: AwsCodeBuildProject
metadata:
  name: connected-build
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.AwsCodeBuildProject.connected-build
spec:
  region: us-west-2
  source:
    type: GITHUB
    location: https://github.com/my-org/my-app.git
  environment:
    type: LINUX_CONTAINER
    computeType: BUILD_GENERAL1_SMALL
    image: aws/codebuild/amazonlinux2-x86_64-standard:5.0
  artifacts:
    type: NO_ARTIFACTS
  serviceRole:
    valueFrom:
      kind: AwsIamRole
      name: codebuild-role
      field: status.outputs.role_arn
  encryptionKey:
    valueFrom:
      kind: AwsKmsKey
      name: build-key
      field: status.outputs.key_arn
  vpcConfig:
    vpcId:
      valueFrom:
        kind: AwsVpc
        name: main-vpc
        field: status.outputs.vpc_id
    subnetIds:
      - valueFrom:
          kind: AwsVpc
          name: main-vpc
          field: status.outputs.private_subnets[0].id
      - valueFrom:
          kind: AwsVpc
          name: main-vpc
          field: status.outputs.private_subnets[1].id
    securityGroupIds:
      - valueFrom:
          kind: AwsSecurityGroup
          name: codebuild-sg
          field: status.outputs.security_group_id

Stack Outputs

After deployment, the following outputs are available in status.outputs:

OutputTypeDescription
project_arnstringARN of the CodeBuild project, used for IAM policies and cross-resource references
project_namestringName of the CodeBuild project
service_role_arnstringIAM service role ARN used by the project
webhook_urlstringWebhook URL from the source provider (empty when no webhook is configured)
webhook_payload_urlstringURL that receives webhook payloads (empty when no webhook is configured)

Related Components

  • AwsIamRole — provides the service role for CodeBuild
  • AwsVpc — provides VPC and subnets for builds that access private resources
  • AwsSecurityGroup — controls network access for VPC-enabled builds
  • AwsS3Bucket — stores build artifacts and cache
  • AwsCloudwatchLogGroup — hosts build logs

Next article

AWS CodePipeline

AWS CodePipeline Deploys an AWS CodePipeline continuous delivery pipeline with ordered stages, provider-specific actions, S3 artifact stores, and optional V2 features including git-based triggers and pipeline-level variables. What Gets Created When you deploy an AwsCodePipeline resource, OpenMCF provisions: CodePipeline — an awscodepipeline resource (V1 or V2) with the specified execution mode, IAM role, and artifact configuration Artifact Stores — one or more S3 bucket references for storing...
Read next article
Presets
3 ready-to-deploy configurationsView presets →