Skip to main content
Earlier we built a simple CI/CD pipeline, connected it to GitHub, and walked it through to the deploy phase. This article continues that work and focuses on the CodeBuild buildspec.yml that drives the build phase. It explains how to structure a complete buildspec, inject environment variables from multiple sources, export variables to downstream pipeline actions, produce primary and secondary artifacts, integrate test reports, and configure caching. This demo uses a sample repository (public on GitHub) and a CodeBuild project that builds that sample app. We start by showing the console context where the build project is found.
A screenshot of the AWS Management Console Home page showing a "Recently visited" services list (CodeBuild, CloudFront, EC2, S3, etc.) on the left and an "Applications" panel on the right indicating no applications with a "Create application" button.
From the CodeBuild console you can inspect the configured build projects and open the project that builds the demo application.
A screenshot of the AWS CodeBuild console showing the "Build projects" list with project names, source providers, repositories, latest build statuses, and last modified times. The left navigation menu and top action buttons (Create project, Start build, etc.) are also visible.
Open the sample repository to locate the buildspec.yml at the repo root.
A dark-mode screenshot of a GitHub repository page for "020-100-sample-app," showing the repo file list (src, tests, README.md, etc.), commit info, and the README preview. The right sidebar displays repository details like stars, forks, and contributor info.
Below is a consolidated, corrected, and complete buildspec.yml used by the demo. It demonstrates buildspec version: 0.2 features: environment variables from inline, Parameter Store and Secrets Manager, exported variables, runtime versions, four phases (install / pre_build / build / post_build), finally blocks, test report groups, artifacts (primary and secondary), and local caching.
Quick reference table — important buildspec keys and purpose: Notes on key sections
  • version: use 0.2. Version 0.1 is deprecated and lacks several modern features.
  • env: you can supply inline variables, Parameter Store keys under parameter-store and Secrets Manager references under secrets-manager. CodeBuild resolves these at runtime — ensure the CodeBuild service role has IAM permissions to read those keys/secrets.
  • exported-variables: variables listed here are emitted to the pipeline and can be consumed by later CodePipeline actions.
  • runtime-versions: declare language runtimes under the install phase using runtime-versions.
  • finally: a phase-level finally always runs, which is useful for cleanup or guaranteed notifications.
  • on-failure: use on-failure per phase to control whether the pipeline continues, aborts, or retries on errors.
Start a build from the console to inspect the build execution details — the UI shows download/source steps, where the YAML was loaded from, and decrypted environment variable processing. Here’s the console view for a started build.
A screenshot of the AWS CodeBuild console showing a devops build that has just started, with a green "Build started" banner and buttons like Stop build and Debug build. The Build status panel shows the build is in progress and tabs for build logs, phase details, environment variables, and other details.
Example excerpt from a CodeBuild log (cleaned for readability):
Built-in CodeBuild environment variables CodeBuild provides many useful variables prefixed with CODEBUILD_ such as:
  • CODEBUILD_BUILD_NUMBER — sequential build counter
  • CODEBUILD_RESOLVED_SOURCE_VERSION — commit SHA or resolved version
  • CODEBUILD_BUILD_SUCCEEDING — 1 if succeeding, 0 otherwise
You can view resolved environment variables for a build in the build details UI. Variables sourced from Parameter Store or Secrets Manager are listed; secret values may be masked.
Screenshot of the AWS CodeBuild console showing a specific build's details (resolved source version, start/end time, and report links). The Environment variables tab is open, listing variables such as BUILD_ENVIRONMENT, NOTIFICATION_TOPIC, and DOCKER_USERNAME.
Artifacts
  • artifacts.files are globs for files to include in the primary artifact.
  • base-directory selects the root path for artifact collection.
  • discard-paths: no preserves directory structure. discard-paths: yes flattens contents.
  • secondary-artifacts allow multiple artifact outputs (deployment package + test reports, for example). CodeBuild supports up to 12 secondary artifacts.
The earlier artifacts snippet already demonstrates a primary artifact named with the build number and a secondary artifact containing test reports. Reports integration
  • Define report groups under reports with file-format (e.g., JUNITXML or COBERTURA) and base-directory. CodeBuild parses these and surfaces test and coverage results in the console Reports tab.
  • Typical use: run tests during the build phase and write JUnit XML and coverage XML into a reports/ directory, then reference those files under reports in the spec.
Caching
  • Local caching reduces dependency install times. Common paths:
    • /root/.cache/pip/**/* — pip wheel/cache
    • node_modules/**/* — Node packages
  • CodeBuild also supports S3 caching configured in the project settings.
  • In the demo, local caching reduced build durations substantially (e.g., from ~90s to ~35s as a rough example).
After a build completes you can inspect:
  • Build logs (all phases)
  • Phase details and timings
  • Resolved environment variables and their sources
  • Report groups and parsed test/coverage results
  • Artifacts in the artifact store (typically S3)
  • Cache usage and configuration
Screenshot of the AWS CodeBuild console showing the Environment variables tab for a build project. It lists variables like BUILD_ENVIRONMENT (demo), NOTIFICATION_TOPIC, and DOCKER_USERNAME, with the left-side navigation menu visible.
Key exam / operational takeaways
  • Use version: 0.2 for the full feature set (runtime versions, reports, caching, finally, exported variables).
  • Phases execute in strict order: install → pre_build → build → post_build. post_build runs unless a phase is set to on-failure: ABORT.
  • Control phase failure behavior with on-failure (values: CONTINUE, ABORT, RETRY).
  • Inject secure configuration using parameter-store and secrets-manager, and ensure the CodeBuild service role has permissions to access them.
  • Export variables to pass data from a build into downstream CodePipeline actions.
  • Use primary and secondary-artifacts to capture multiple outputs. Use reports to surface test/coverage results inside the CodeBuild console.
  • Enable caching for dependency directories to reduce repeated download/install times and speed up builds.
Links and references
Remember: never leave your service role without the proper Parameter Store / Secrets Manager permissions—otherwise CodeBuild cannot decrypt or read those values and the build will fail.

Watch Video

Practice Lab