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.


buildspec.yml at the repo root.

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.
Notes on key sections
- version: use
0.2. Version0.1is deprecated and lacks several modern features. - env: you can supply inline variables, Parameter Store keys under
parameter-storeand Secrets Manager references undersecrets-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
installphase usingruntime-versions. - finally: a phase-level
finallyalways runs, which is useful for cleanup or guaranteed notifications. - on-failure: use
on-failureper phase to control whether the pipeline continues, aborts, or retries on errors.

CODEBUILD_ such as:
CODEBUILD_BUILD_NUMBER— sequential build counterCODEBUILD_RESOLVED_SOURCE_VERSION— commit SHA or resolved versionCODEBUILD_BUILD_SUCCEEDING—1if succeeding,0otherwise

artifacts.filesare globs for files to include in the primary artifact.base-directoryselects the root path for artifact collection.discard-paths: nopreserves directory structure.discard-paths: yesflattens contents.secondary-artifactsallow multiple artifact outputs (deployment package + test reports, for example). CodeBuild supports up to 12 secondary artifacts.
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
reportswithfile-format(e.g.,JUNITXMLorCOBERTURA) andbase-directory. CodeBuild parses these and surfaces test and coverage results in the console Reports tab. - Typical use: run tests during the
buildphase and write JUnit XML and coverage XML into areports/directory, then reference those files underreportsin the spec.
- Local caching reduces dependency install times. Common paths:
/root/.cache/pip/**/*— pip wheel/cachenode_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).
- 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

- Use
version: 0.2for the full feature set (runtime versions, reports, caching,finally, exported variables). - Phases execute in strict order:
install→pre_build→build→post_build.post_buildruns unless a phase is set toon-failure: ABORT. - Control phase failure behavior with
on-failure(values:CONTINUE,ABORT,RETRY). - Inject secure configuration using
parameter-storeandsecrets-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-artifactsto capture multiple outputs. Usereportsto surface test/coverage results inside the CodeBuild console. - Enable caching for dependency directories to reduce repeated download/install times and speed up builds.
- AWS CodeBuild buildspec reference
- AWS CodeBuild environment variables
- AWS Systems Manager Parameter Store
- AWS Secrets Manager
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.