CodeBuild buildspec.yml Reference

The buildspec.yml file is a YAML-formatted configuration file that tells AWS CodeBuild exactly what to do during a build. It is the heart of a CodeBuild project, defining the sequence of phases (install, pre_build, build, post_build), environment variables, artifacts to produce, cache settings, and reports. Without a buildspec.yml, CodeBuild would have no instructions; you can either include it in your source code (at the root) or define it inline in the CodeBuild console/CLI. The exam tests your ability to write and interpret buildspec.yml correctly, including mandatory vs. optional fields and common pitfalls.

When a build starts, CodeBuild reads the buildspec.yml and executes phases in this order: 1. Install: Install dependencies (e.g., packages, runtime versions). 2. Pre_build: Commands to run before the main build (e.g., signing in, pulling dependencies). 3. Build: The actual build commands (e.g., compile, test). 4. Post_build: Commands after build (e.g., packaging, notifications). 5. Finally (optional): Always runs, even if previous phases fail.

Each phase can contain multiple commands, and the phase fails if any command returns a non-zero exit code (unless you use || true or similar). The environment is isolated per build; each build runs in a fresh container. CodeBuild also supports batch builds, where multiple builds run in parallel using a batch buildspec.

- version: Required. Must be 0.2 (the current version). Older version 0.1 is deprecated. - run-as: Optional. Linux user to run commands (default: root). Useful for restricted permissions. - env: Optional. Defines environment variables. - variables: Plain text key-value pairs. - parameter-store: References AWS Systems Manager Parameter Store parameters. - secrets-manager: References AWS Secrets Manager secrets. - exported-variables: List of variables to export to subsequent phases (e.g., for batch builds). - phases: Required. Contains install, pre_build, build, post_build, and optionally finally. - Each phase has: - runtime-versions: Map of runtime names to versions (e.g., nodejs: 14). Supported runtimes: Android, Docker, Dotnet, Go, Java, Node.js, PHP, Python, Ruby, etc. Must be specified in install phase. - commands: List of shell commands to execute sequentially. - finally: A list of commands that run after the phase's main commands, regardless of success/failure. Only at the phase level. - artifacts: Required. Defines output files. - files: List of file patterns to include (e.g., **/*). - name: Name of the artifact (default: project name). - discard-paths: Boolean; if true, flattens directory structure. - base-directory: Base directory for relative paths. - secondary-artifacts: Map of additional artifact sets. - cache: Optional. Speeds up builds by caching dependencies. - paths: List of paths to cache (e.g., /root/.npm). - type: Only local is supported (stores in S3 or local). - reports: Optional. Defines test reports. - Report group name with: - files: List of report file patterns. - base-directory: Base directory for report files. - file-format: CUCUMBERJSON or JUNITXML. - batch: Optional. For batch builds. - fast-fail: Boolean; if true, fails entire batch if one build fails. - build-list: List of build-specific overrides. - build-graph: For dependency-based builds.

Timers: CodeBuild has a default build timeout of 60 minutes, configurable up to 8 hours (480 minutes) for on-demand builds, or up to 2 hours for Lambda compute. If no output is produced for 30 minutes (default idle timeout), the build is terminated. These are set in the CodeBuild project, not in buildspec.yml.

Sample buildspec.yml:

version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 14
    commands:
      - npm install
  pre_build:
    commands:
      - echo "Running pre-build commands"
  build:
    commands:
      - npm run build
  post_build:
    commands:
      - echo "Build completed on `date`"
artifacts:
  files:
    - '**/*'
  base-directory: 'build'

To validate syntax, you can use aws codebuild batch-get-builds or run a build and check logs. There is no official linter; errors appear in build logs.

A large e-commerce company uses CodeBuild to build and test dozens of microservices. Each service has its own buildspec.yml in its repository. The buildspec.yml specifies runtime-versions for Java 11, installs Maven dependencies, runs unit tests (using JUnit), and produces a JAR artifact. The post_build phase uploads the JAR to an S3 bucket and triggers a deployment via CodeDeploy. To speed up builds, they cache the Maven local repository (~/.m2) using the cache section. This reduces build times from 15 minutes to 3 minutes. They also configure reports to publish test results to CodeBuild, enabling developers to see test failures directly in the console. A common issue is when developers forget to update the buildspec.yml when changing the build tool (e.g., Gradle to Maven), causing the install phase to fail because Maven is not installed.

A SaaS company uses batch builds to build their application for multiple environments (development, staging, production) in parallel. They define a batch buildspec.yml that includes a batch section with a build-list that overrides environment variables for each build (e.g., ENVIRONMENT: dev, ENVIRONMENT: prod). Each build runs the same phases but with different variable values. The artifacts are named differently (e.g., app-dev.zip, app-prod.zip). This approach reduces total build time from 30 minutes (sequential) to 10 minutes (parallel). They must ensure that the build environment is consistent across batches, so they pin runtime versions and use a custom Docker image. A pitfall is using exported-variables incorrectly; if a variable is exported in one batch build, it is not available in another unless explicitly passed.

A financial services firm requires that all builds be immutable and auditable. They store buildspec.yml files in CodeCommit and enforce that every build uses a buildspec.yml from the source (not inline). They configure CodeBuild to log all commands to CloudWatch Logs with a retention policy of 7 years. The buildspec.yml includes a finally block that sends a notification to an SNS topic with the build result. They also use Parameter Store to inject database credentials and API keys, avoiding hardcoded secrets. A common misconfiguration is setting env with parameter-store but not granting the CodeBuild service role permission to read the parameter, causing the build to fail with an access denied error.