# AWS CodeBuild

AWS CodeBuild provides managed Docker environments with excellent container support, making it perfect for KushoAI testing in AWS-native CI/CD pipelines.

# Prerequisites

AWS Account: Active AWS account with CodeBuild access
IAM Permissions: Appropriate permissions for CodeBuild and ECR access
Docker Environment: CodeBuild provides managed Docker environments
Parameter Store (recommended): For secure credential management

# Docker Image

All execution uses the Kusho test runner Docker image:

public.ecr.aws/y5g4u6y7/kusho-test-runner:latest

# Setup Instructions

# 1. Create buildspec.yml

Create a buildspec.yml file in your repository root:

# 2. Basic Build Configuration

version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
  variables:
    BASE_URL: https://be.kusho.ai
    ENVIRONMENT_ID: 2

phases:
  pre_build:
    commands:
      - echo "Starting Kusho API tests..."
      - echo "Build started on `date`"
      - echo "Git commit SHA: $CODEBUILD_RESOLVED_SOURCE_VERSION"

  build:
    commands:
      - echo "Running Kusho test suite..."
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$CODEBUILD_WEBHOOK_HEAD_REF" \
          -e TEST_SUITE_UUID="$TEST_SUITE_UUID" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest

  post_build:
    commands:
      - echo "Build completed on `date`"
      - echo "Test execution finished"

# 3. Configure AWS Systems Manager Parameter Store

Store your sensitive data in Parameter Store:

# Create secure string parameter
aws ssm put-parameter \
    --name "/kusho/api-key" \
    --value "your-kusho-api-key" \
    --type "SecureString" \
    --description "Kusho API key for CI/CD testing"

# 4. Create CodeBuild Project

Using AWS CLI:

aws codebuild create-project \
    --name "kusho-api-tests" \
    --source type=GITHUB,location=https://github.com/your-org/your-repo \
    --artifacts type=NO_ARTIFACTS \
    --environment type=LINUX_CONTAINER,image=aws/codebuild/amazonlinux2-x86_64-standard:3.0,computeType=BUILD_GENERAL1_MEDIUM \
    --service-role arn:aws:iam::account:role/service-role/codebuild-service-role

# Execution Methods

# 1. Execute by Test Suite UUID

version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
  variables:
    BASE_URL: https://be.kusho.ai
    ENVIRONMENT_ID: 2
    TEST_SUITE_UUID: "uuid1,uuid2,uuid3"

phases:
  build:
    commands:
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$CODEBUILD_WEBHOOK_HEAD_REF" \
          -e TEST_SUITE_UUID="$TEST_SUITE_UUID" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest

# 2. Execute by Group ID

version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
  variables:
    BASE_URL: https://be.kusho.ai
    ENVIRONMENT_ID: 2
    GROUP_ID: 87

phases:
  build:
    commands:
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$CODEBUILD_WEBHOOK_HEAD_REF" \
          -e GROUP_ID="$GROUP_ID" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest

# 3. Execute by Tags

version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
  variables:
    BASE_URL: https://be.kusho.ai
    ENVIRONMENT_ID: 2
    TEST_TAGS: "smoke,regression"

phases:
  build:
    commands:
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$CODEBUILD_WEBHOOK_HEAD_REF" \
          -e TAGS="$TEST_TAGS" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest

# 4. Execute E2E Workflows

version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
  variables:
    BASE_URL: https://be.kusho.ai
    ENVIRONMENT_ID: 2
    E2E_TEST_SUITE_UUID: "e5d1b703-a798-4bd9-becb-8977bc2a1ec3"
    EXECUTION_PROFILE_UUID: "profile-uuid-here"

phases:
  build:
    commands:
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$CODEBUILD_WEBHOOK_HEAD_REF" \
          -e E2E_TEST_SUITE_UUID="$E2E_TEST_SUITE_UUID" \
          -e EXECUTION_PROFILE_UUID="$EXECUTION_PROFILE_UUID" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest

# Complete Pipeline Examples

# Multi-Phase Testing Pipeline

version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
  variables:
    BASE_URL: https://be.kusho.ai
    STAGING_ENV_ID: 2
    PRODUCTION_ENV_ID: 1

phases:
  pre_build:
    commands:
      - echo "Logging in to Amazon ECR..."
      - echo "Build started on `date`"
      - echo "Testing commit $CODEBUILD_RESOLVED_SOURCE_VERSION"

  build:
    commands:
      - echo "Running smoke tests on staging..."
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$STAGING_ENV_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="Smoke tests for commit $CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e TAGS="smoke" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
      
      - echo "Running integration tests on staging..."
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$STAGING_ENV_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="Integration tests for commit $CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e TAGS="integration" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest

  post_build:
    commands:
      - |
        if [ "$CODEBUILD_WEBHOOK_HEAD_REF" = "refs/heads/main" ]; then
          echo "Running production smoke tests..."
          docker run --rm \
            -e BASE_URL="$BASE_URL" \
            -e ENVIRONMENT_ID="$PRODUCTION_ENV_ID" \
            -e API_KEY="$KUSHO_API_KEY" \
            -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
            -e CI_COMMIT_MESSAGE="Production tests for commit $CODEBUILD_RESOLVED_SOURCE_VERSION" \
            -e TAGS="smoke" \
            public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
        else
          echo "Skipping production tests - not main branch"
        fi
      - echo "Build completed on `date`"

# Environment-Specific Pipeline

version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
    STAGING_TEST_SUITE_UUID: /kusho/staging/test-suite-uuid
    PRODUCTION_TEST_SUITE_UUID: /kusho/production/test-suite-uuid
  variables:
    BASE_URL: https://be.kusho.ai

phases:
  pre_build:
    commands:
      - |
        if [ "$CODEBUILD_WEBHOOK_HEAD_REF" = "refs/heads/main" ]; then
          export TARGET_ENV="production"
          export ENVIRONMENT_ID="1"
          export TEST_SUITE_UUID="$PRODUCTION_TEST_SUITE_UUID"
        else
          export TARGET_ENV="staging"
          export ENVIRONMENT_ID="2" 
          export TEST_SUITE_UUID="$STAGING_TEST_SUITE_UUID"
        fi
      - echo "Targeting $TARGET_ENV environment"

  build:
    commands:
      - echo "Running tests against $TARGET_ENV..."
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$TARGET_ENV tests for $CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e TEST_SUITE_UUID="$TEST_SUITE_UUID" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest

# AWS CodeBuild Features

# Built-in Environment Variables

CodeBuild provides several useful environment variables:

$CODEBUILD_RESOLVED_SOURCE_VERSION - Git commit SHA
$CODEBUILD_WEBHOOK_HEAD_REF - Git branch reference
$CODEBUILD_PROJECT_NAME - CodeBuild project name
$CODEBUILD_BUILD_NUMBER - Build number
$CODEBUILD_START_TIME - Build start time

# Build Phases

CodeBuild supports multiple phases for organized execution:

install - Install runtime dependencies
pre_build - Pre-build setup commands
build - Main build commands
post_build - Post-build cleanup and notifications

# Conditional Execution

phases:
  build:
    commands:
      - |
        if [ "$CODEBUILD_WEBHOOK_HEAD_REF" = "refs/heads/main" ]; then
          echo "Running production tests..."
          # Production test commands
        elif [[ "$CODEBUILD_WEBHOOK_HEAD_REF" == *"feature/"* ]]; then
          echo "Running feature branch tests..."
          # Feature branch test commands
        else
          echo "Running standard tests..."
          # Standard test commands
        fi

# AWS-Specific Integrations

# ECR Image Caching

version: 0.2

env:
  variables:
    AWS_DEFAULT_REGION: us-east-1
    AWS_ACCOUNT_ID: 123456789012
    IMAGE_REPO_NAME: kusho-test-runner
    IMAGE_TAG: latest

phases:
  pre_build:
    commands:
      - echo "Logging in to Amazon ECR..."
      - aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com
      
      - echo "Checking if image exists in ECR..."
      - |
        if aws ecr describe-images --repository-name $IMAGE_REPO_NAME --image-ids imageTag=$IMAGE_TAG >/dev/null 2>&1; then
          echo "Using cached image from ECR"
          export DOCKER_IMAGE="$AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG"
        else
          echo "Pulling and caching image"
          docker pull public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
          docker tag public.ecr.aws/y5g4u6y7/kusho-test-runner:latest $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG
          docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG
          export DOCKER_IMAGE="$AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG"
        fi

  build:
    commands:
      - echo "Running tests with image: $DOCKER_IMAGE"
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$CODEBUILD_WEBHOOK_HEAD_REF" \
          -e TEST_SUITE_UUID="$TEST_SUITE_UUID" \
          $DOCKER_IMAGE

version: 0.2

env:
  variables:
    SNS_TOPIC_ARN: arn:aws:sns:us-east-1:123456789012:kusho-test-notifications

phases:
  post_build:
    commands:
      - |
        if [ $CODEBUILD_BUILD_SUCCEEDING -eq 1 ]; then
          SUBJECT="✅ Kusho Tests Passed - Build $CODEBUILD_BUILD_NUMBER"
          MESSAGE="All Kusho API tests passed successfully for commit $CODEBUILD_RESOLVED_SOURCE_VERSION"
        else
          SUBJECT="❌ Kusho Tests Failed - Build $CODEBUILD_BUILD_NUMBER"
          MESSAGE="Kusho API tests failed for commit $CODEBUILD_RESOLVED_SOURCE_VERSION. Check build logs for details."
        fi
      - |
        aws sns publish \
          --topic-arn $SNS_TOPIC_ARN \
          --subject "$SUBJECT" \
          --message "$MESSAGE"

# CloudWatch Metrics

phases:
  post_build:
    commands:
      - |
        aws cloudwatch put-metric-data \
          --namespace "Kusho/Tests" \
          --metric-data MetricName=TestExecution,Value=1,Unit=Count,Dimensions=Project=$CODEBUILD_PROJECT_NAME,Status=$([[ $CODEBUILD_BUILD_SUCCEEDING -eq 1 ]] && echo "Success" || echo "Failure")

# Integration with AWS CodePipeline

# Pipeline Configuration

Create a CodePipeline that includes CodeBuild:

{
  "pipeline": {
    "name": "kusho-testing-pipeline",
    "stages": [
      {
        "name": "Source",
        "actions": [
          {
            "name": "SourceAction",
            "actionTypeId": {
              "category": "Source",
              "owner": "AWS",
              "provider": "GitHub",
              "version": "1"
            },
            "configuration": {
              "Owner": "your-github-org",
              "Repo": "your-repo",
              "Branch": "main",
              "OAuthToken": ""
            },
            "outputArtifacts": [{"name": "SourceOutput"}]
          }
        ]
      },
      {
        "name": "Test",
        "actions": [
          {
            "name": "KushoTests",
            "actionTypeId": {
              "category": "Build",
              "owner": "AWS",
              "provider": "CodeBuild",
              "version": "1"
            },
            "configuration": {
              "ProjectName": "kusho-api-tests"
            },
            "inputArtifacts": [{"name": "SourceOutput"}]
          }
        ]
      }
    ]
  }
}

# Best Practices

# Security

Use Parameter Store or Secrets Manager for sensitive data
Implement least-privilege IAM policies
Enable CloudTrail for audit logging

# Performance

Use ECR for image caching to reduce build times
Choose appropriate compute types for your workload
Implement build caching strategies

# Cost Optimization

Use spot instances for non-critical builds
Implement build timeouts to prevent runaway costs
Monitor build metrics and optimize resource usage

# Organization

Use consistent naming conventions for projects
Implement build templates for reusability
Use environment variables for configuration

# Troubleshooting

# Common Issues

IAM Permission Issues
- Ensure CodeBuild service role has necessary permissions
- Verify Parameter Store read permissions
- Check ECR pull permissions
Docker Pull Issues
- Verify network connectivity to ECR registry
- Check VPC configuration if using VPC mode
- Ensure adequate disk space for Docker images
Environment Variable Issues
- Verify Parameter Store parameter names and paths
- Check parameter permissions and encryption
- Ensure proper variable naming conventions

# Debug Commands

phases:
  pre_build:
    commands:
      - echo "Debug Information:"
      - echo "Build ID: $CODEBUILD_BUILD_ID"
      - echo "Project Name: $CODEBUILD_PROJECT_NAME"
      - echo "Source Version: $CODEBUILD_RESOLVED_SOURCE_VERSION"
      - echo "Webhook Head Ref: $CODEBUILD_WEBHOOK_HEAD_REF"
      - docker --version
      - aws --version
      - env | grep CODEBUILD | sort

# CloudWatch Logs

Enable detailed logging in your CodeBuild project configuration:

CloudWatch Logs: Enabled
Log Group Name: /aws/codebuild/kusho-api-tests
Stream Name Prefix: build-logs

Monitor logs for:

Docker pull progress
Test execution output
Error messages and stack traces
Build phase timing information