In the realm of modern software development, the seamless integration and deployment of code have become paramount. Behind the scenes, tools and configurations orchestrate these processes, and one key player in this symphony is the BuildSpec file.
If you’ve ever embarked on the journey of setting up a CI/CD pipeline, you’ve likely encountered the enigmatic BuildSpec file. It’s the silent architect behind the scenes, dictating how your code transitions from development to production.
In this blog we will discuss the following points.
- Buildspec file name and location
- Buildspec syntax
- Buildspec example
Now that we’ve set the stage for automating builds and deployments using AWS CodeBuild, let’s delve into the technical heart of this process — the buildspec.yml file.
1. Buildspec Filename and Location.
- If you include the buildspec.yml file on the source code, by default the buildspec file must be named as “buildspec.yml” and shall be at the root of the source directory.
- For different builds, we can name the file buildspec_debug.yml or buildspec_release.yml.
- We can also store the file at other locations like config/buildspec.yml, where config is a directory.
- AWS also gives us provision to store the buildspec.yml in S3 bucket. In this case, the S3 bucket shall be in the same AWS Region where the build project is launched. And the file will be specified using its ARN (Amazon Resource Name).
There shall be one buildspec file per build project, regardless of buildspec file name.
2. Buildspec File Syntax.
The buildspec file shall be in YAML format.
The syntax of the file is as follows:
version: 0.2
run-as: Linux-user-name
env:
shell: shell-tag
variables:
key: “value”
parameter-store:
key: “value”
exported-variables:
– variable
secrets-manager:
key: secret-id:json-key:version-stage:version-id
git-credential-helper: no | yes
proxy:
upload-artifacts: no | yes
logs: no | yes
batch:
fast-fail: false | true
# build-list:
# build-matrix:
# build-graph:
phases:
install:
run-as: Linux-user-name
on-failure: ABORT | CONTINUE
runtime-versions:
runtime: version
runtime: version
commands:
– command
– command
finally:
– command
– command
# steps:
pre_build:
run-as: Linux-user-name
on-failure: ABORT | CONTINUE
commands:
– command
– command
finally:
– command
– command
# steps:
build:
run-as: Linux-user-name
on-failure: ABORT | CONTINUE
commands:
– command
– command
finally:
– command
– command
# steps:
post_build:
run-as: Linux-user-name
on-failure: ABORT | CONTINUE
commands:
– command
– command
finally:
– command
– command
# steps:
reports:
report-group-name-or-arn:
files:
– location
– location
base-directory: location
discard-paths: no | yes
file-format: report-format
artifacts:
files:
– location
– location
name: artifact-name
discard-paths: no | yes
base-directory: location
exclude-paths: excluded paths
enable-symlinks: no | yes
s3-prefix: prefix
secondary-artifacts:
artifactIdentifier:
files:
– location
– location
name: secondary-artifact-name
discard-paths: no | yes
base-directory: location
artifactIdentifier:
files:
– location
– location
discard-paths: no | yes
base-directory: location
cache:
paths:
– path
– path
The buildspec contains the following:
1. Version:
- It is a required filed.
- It represents the buildspec version.
- It is recommended to use 0.2 whenever possible.
2. Run-as:
- Optional field
- It is available for Linux users only.
- It will specify a Linux user to run all the commands in that file with read and run permissions.
- If you don’t want to specify a user for all buildspec file commands, you can specify one for commands in a phase by using run-as in one of the phases blocks
- If run-as is not specified, then all commands run as the root user.
3. Env:
- It is an optional field.
- It represents information for one or more custom environment variables.
- It consists of 6 sub-parts.
- Shell
- Variables
- Parameter-store
- Exported-variables
- Secrets-manager
- Git-credential-helper
We will go through the rest of the sections in our next blog.