CodeBuild

Simfra runs CodeBuild projects inside real Docker containers. Your buildspec.yml is parsed and executed phase by phase, source is downloaded from CodeCommit or S3, artifacts are uploaded to S3, and logs are forwarded to CloudWatch Logs.

Prerequisites

  • SIMFRA_DOCKER=true

Create a Build Project

aws --endpoint-url http://localhost:4599 codebuild create-project \
  --name my-build \
  --source type=CODECOMMIT,location=https://git-codecommit.us-east-1.amazonaws.com/v1/repos/my-app \
  --artifacts type=S3,location=my-artifacts \
  --environment type=LINUX_CONTAINER,computeType=BUILD_GENERAL1_SMALL,image=aws/codebuild/standard:7.0 \
  --service-role arn:aws:iam::000000000000:role/codebuild-role

Source types supported:

Type Description
CODECOMMIT Clones from a Simfra CodeCommit repository
S3 Downloads a zip/tar from an S3 bucket
NO_SOURCE No source - useful for builds that pull their own code

Start a Build

aws --endpoint-url http://localhost:4599 codebuild start-build \
  --project-name my-build

The build immediately enters IN_PROGRESS and advances through phases in the background.

Build Phases

Each build progresses through the same phases as real CodeBuild:

  1. SUBMITTED - Build request accepted
  2. QUEUED - Waiting for capacity
  3. PROVISIONING - Docker container being created
  4. DOWNLOAD_SOURCE - Source downloaded from CodeCommit/S3
  5. INSTALL - install phase commands from buildspec
  6. PRE_BUILD - pre_build phase commands
  7. BUILD - build phase commands
  8. POST_BUILD - post_build phase commands
  9. UPLOAD_ARTIFACTS - Artifacts packaged and uploaded to S3
  10. FINALIZING - Logs collected and container cleaned up
  11. COMPLETED - Terminal state

Check Build Status

aws --endpoint-url http://localhost:4599 codebuild batch-get-builds \
  --ids my-build:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Buildspec Example

The standard buildspec.yml format is supported:

version: 0.2

env:
  variables:
    APP_NAME: "my-app"

phases:
  install:
    commands:
      - echo "Installing dependencies..."
      - pip install -r requirements.txt
  pre_build:
    commands:
      - echo "Running tests..."
      - pytest
  build:
    commands:
      - echo "Building..."
      - python setup.py bdist_wheel
  post_build:
    commands:
      - echo "Build complete"

artifacts:
  files:
    - "**/*"
  base-directory: dist

Environment variables from the buildspec env.variables section and from the project's environment configuration are both available inside the container. Standard CodeBuild variables (CODEBUILD_BUILD_ID, CODEBUILD_BUILD_ARN, CODEBUILD_BUILD_NUMBER, CODEBUILD_SRC_DIR, CODEBUILD_SOURCE_VERSION) are set automatically.

Privileged Builds (Docker-in-Docker)

For builds that need to run docker build inside the container:

aws --endpoint-url http://localhost:4599 codebuild create-project \
  --name docker-build \
  --source type=CODECOMMIT,location=https://git-codecommit.us-east-1.amazonaws.com/v1/repos/my-app \
  --artifacts type=NO_ARTIFACTS \
  --environment type=LINUX_CONTAINER,computeType=BUILD_GENERAL1_SMALL,image=aws/codebuild/standard:7.0,privilegedMode=true \
  --service-role arn:aws:iam::000000000000:role/codebuild-role

When privilegedMode is true, the Docker socket is bind-mounted into the build container, enabling docker build, docker push, and other Docker commands.

ECR Build Images

Build images can be pulled from Simfra's ECR registry. The build runner automatically authenticates with ECR using the project's service role and rewrites the image URI to point at Simfra's local registry.

Cross-Service Integration

  • S3: Artifacts are uploaded to S3 after the build phase. The bucket must exist.
  • CloudWatch Logs: Build output is forwarded to a log group (default: /aws/codebuild/<project-name>, or the group specified in logsConfig).
  • EventBridge: State change events are emitted on build start, success, and failure.
  • CodePipeline: When triggered by a pipeline, CodeBuild builds are started and polled automatically.

Next Steps

  • CodePipeline - orchestrate multi-stage pipelines with CodeBuild actions
  • CodeCommit - host Git repositories for use as CodeBuild source
  • CodeDeploy - deploy build artifacts to EC2, Lambda, or ECS