适用于 CodeBuild 的构建规范参考
本主题提供有关构建规范文件的重要参考信息。A buildspec is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build.您可以将构建规范作为源代码的一部分,也可以在创建构建项目时定义构建规范。有关构建规范工作原理的信息,请参阅CodeBuild 的工作原理。
构建规范文件名称和存储位置
如果您在源代码中包含构建规范,则默认情况下,构建规范文件必须命名为 buildspec.yml
且放置在源目录的根目录中。
可以覆盖默认构建规范文件名和位置。例如,您可以:
-
对同一存储库中的不同构建使用不同的构建规范文件,如
buildspec_debug.yml
和buildspec_release.yml
。 -
将构建规范文件存储在源目录的根目录之外的位置,如
config/buildspec.yml
或 S3 存储桶。S3 存储桶必须与您的构建项目位于同一 AWS 区域。使用其 ARN 指定构建规范文件(例如,arn:aws:s3:::my-codebuild-sample2/buildspec.yml
)。
您可以只为构建项目指定一个构建规范,而不管构建规范文件的名称如何。
要覆盖默认构建规范文件名、默认位置或这两者,执行下列操作之一:
-
运行 AWS CLI
create-project
或update-project
命令,将buildspec
值设置为备用构建规范文件的路径(相对于内置环境变量CODEBUILD_SRC_DIR
的值)。 您还可以在create project
AWS 中执行与 SDKs 操作等效的操作。 有关更多信息,请参阅创建构建项目或更改构建项目的设置。 -
运行 AWS CLI
start-build
命令,将buildspecOverride
值设置为备用构建规范文件的路径(相对于内置环境变量CODEBUILD_SRC_DIR
的值)。 您还可以在start build
AWS 中执行与 SDKs 操作等效的操作。 有关更多信息,请参阅运行构建。 -
在 AWS CloudFormation 模板中,将类型为
BuildSpec
的资源中Source
的AWS::CodeBuild::Project
属性设置为备用构建规范文件的路径(相对于内置环境变量CODEBUILD_SRC_DIR
的值)。 有关更多信息,请参阅 BuildSpec 的 AWS CodeBuild 项目源中的 属性。AWS CloudFormation 用户指南
构建规范语法
构建规范文件必须以 YAML
如果命令包含 YAML 不支持的字符或字符串,则必须用引号 ("") 将命令括起来。以下命令用引号括起来,因为在 YAML 中不允许使用冒号 (:) 后跟空格。命令中的引号会被转义 (\")。
"export PACKAGE_NAME=$(cat package.json | grep name | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g')"
构建规范的语法如下:
version: 0.2 run-as:
Linux-user-name
env: shell:shell-tag
variables:key
: "value
"key
: "value
" parameter-store:key
: "value
"key
: "value
" exported-variables: -variable
-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
runtime-versions:runtime
:version
runtime
:version
commands: -command
-command
finally: -command
-command
pre_build: run-as:Linux-user-name
commands: -command
-command
finally: -command
-command
build: run-as:Linux-user-name
commands: -command
-command
finally: -command
-command
post_build: run-as:Linux-user-name
commands: -command
-command
finally: -command
-command
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
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
构建规范包含以下内容:
version
必需的映射。表示构建规范版本。建议使用 0.2
。
虽然仍支持版本 0.1,但建议尽可能使用版本 0.2。有关更多信息,请参阅构建规范版本。
run-as
可选的序列。仅适用于 Linux 用户。指定用于运行此 buildspec 文件中的命令的 Linux 用户。run-as
向指定的用户授予读取和运行权限。当您在构建规范文件的顶部指定 run-as
时,它将全局应用于所有命令。如果您不希望为所有构建规范文件命令指定一个用户,可以通过在其中一个 phases
语句块中使用 run-as
,为一个阶段中的命令指定一个用户。如果未指定 run-as
,则所有命令都将以根用户身份运行。
env
可选的序列。表示一个或多个自定义环境变量的信息。
为了保护敏感信息,CodeBuild 日志中隐藏以下内容:
-
AWS 访问密钥 ID。有关更多信息,请参阅 AWS Identity and Access Management 用户指南 中的管理 IAM 用户的访问密钥。
-
使用参数存储指定的字符串。有关更多信息,请参阅 Amazon EC2 Systems Manager 用户指南中的 Systems Manager Parameter Store 和 Systems Manager Parameter Store 控制台演练。
-
使用 AWS Secrets Manager 指定的字符串。有关更多信息,请参阅 密钥管理。
- env/外壳
-
可选的序列。指定 Linux 或 Windows 操作系统支持的 shell。
对于 Linux 操作系统,支持的 shell 标签包括:
-
bash
-
/bin/sh
对于 Windows 操作系统,支持的 shell 标签包括:
-
powershell.exe
-
cmd.exe
-
- env/variables
-
在指定了
env
并且您希望定义纯文本格式的自定义环境变量时必需。包含 的映射key
/value
标量,其中每个映射表示一个纯文本格式的自定义环境变量。key
是自定义环境变量的名称,value
是该变量的值。重要 我们强烈建议不要将敏感值(尤其是 AWS 访问密钥 IDs 和秘密访问密钥)存储在环境变量中。使用 CodeBuild 控制台和 AWS CLI 等工具能够以纯文本格式显示环境变量。对于敏感值,建议改用
parameter-store
或secrets-manager
映射,如本节后面所述。您设置的任何环境变量都将替换现有的环境变量。例如,如果 Docker 映像已经包含一个名为
MY_VAR
的环境变量,其值为my_value
,并且您设置了一个名为MY_VAR
的环境变量,其值为other_value
,那么,my_value
将替换为other_value
。 同样,如果 Docker 映像已经包含一个名为PATH
的环境变量,其值为/usr/local/sbin:/usr/local/bin
,并且您设置了一个名为PATH
的环境变量,其值为$PATH:/usr/share/ant/bin
,那么/usr/local/sbin:/usr/local/bin
将替换为文本值$PATH:/usr/share/ant/bin
。请勿设置名称以
CODEBUILD_
开头的任何环境变量。 此前缀保留供内部使用。如果具有相同名称的环境变量在多处都有定义,则应按照如下方式确定其值:
-
构建操作调用开始时的值优先级最高。您可以在创建构建时添加或覆盖环境变量。有关更多信息,请参阅在 AWS CodeBuild 中运行构建。
-
构建项目定义中的值优先级次之。您可以在创建或编辑项目时在项目级别添加环境变量。有关更多信息,请参阅 在 AWS CodeBuild 中创建构建项目和更改 AWS CodeBuild 中构建项目的设置 。
-
构建规范声明中的值优先级最低。
-
- env/parameter-store
-
在指定了
env
并且您要检索存储在 Amazon EC2 Systems Manager Parameter Store 中的自定义环境变量时必需。包含 的映射key
/value
标量,其中每个映射表示存储在 Amazon EC2 Systems Manager Parameter Store 中的单个自定义环境变量。key
是您之后在构建命令中用于引用此自定义环境变量的名称,以及value
是存储在 Amazon EC2 Systems Manager Parameter Store 中的自定义环境变量的名称。要存储敏感值,请参阅 Systems Manager Parameter Store 和演练: 用户指南 中的创建并测试字符串参数(控制台)Amazon EC2 Systems Manager。重要 要允许 CodeBuild 检索存储在 Amazon EC2 Systems Manager Parameter Store 中的自定义环境变量,您必须将
ssm:GetParameters
操作添加到您的 CodeBuild 服务角色。有关更多信息,请参阅创建 CodeBuild 服务角色。从 Amazon EC2 Systems Manager Parameter Store 检索到的任何环境变量都将替换现有环境变量。例如,如果 Docker 映像已经包含一个名为
MY_VAR
的环境变量,其值为my_value
,并且您检索到一个名为MY_VAR
的环境变量,其值为other_value
,那么,my_value
将替换为other_value
。 同样,如果 Docker 映像已经包含一个名为PATH
的环境变量,其值为/usr/local/sbin:/usr/local/bin
,并且您检索到一个名为PATH
的环境变量,其值为$PATH:/usr/share/ant/bin
,则/usr/local/sbin:/usr/local/bin
将替换为文本值$PATH:/usr/share/ant/bin
。请勿存储名称以
CODEBUILD_
开头的任何环境变量。 此前缀保留供内部使用。如果具有相同名称的环境变量在多处都有定义,则应按照如下方式确定其值:
-
构建操作调用开始时的值优先级最高。您可以在创建构建时添加或覆盖环境变量。有关更多信息,请参阅在 AWS CodeBuild 中运行构建。
-
构建项目定义中的值优先级次之。您可以在创建或编辑项目时在项目级别添加环境变量。有关更多信息,请参阅 在 AWS CodeBuild 中创建构建项目和更改 AWS CodeBuild 中构建项目的设置 。
-
构建规范声明中的值优先级最低。
-
- env/secrets-manager
-
如果要检索存储在 AWS Secrets Manager 中的自定义环境变量,则是必需的。使用以下模式指定 Secrets Manager
reference-key
:
:<key>
<secret-id>
:<json-key>
:<version-stage>
|<version-id>
<key>
-
(必填)本地环境变量名称。可以使用此名称在构建过程中访问变量。
<secret-id>
-
(必需) 用作密钥的唯一标识符的名称或 Amazon 资源名称 (ARN)。要访问您的 AWS 账户中的密钥,只需指定密钥名称。要访问其他 AWS 账户中的密钥,请指定密钥 ARN。
<json-key>
-
(可选)指定要检索其值的 Secrets Manager 键/值对的键名称。如果您不指定
json-key
,CodeBuild 会索整个密钥文本。 <version-stage>
-
(可选)指定要按附加到版本的暂存标签检索的密钥版本。暂存标签用于在轮换过程中跟踪不同版本。如果您使用
version-stage
,请不要指定version-id
。 如果您未指定版本阶段或版本 ID,则默认设置是检索版本阶段值为AWSCURRENT
的版本。 <version-id>
-
(可选)指定要使用的密钥版本的唯一标识符。如果指定
version-id
,请不要指定version-stage
。 如果您不指定版本阶段或版本 ID,则默认设置是检索版本阶段值为AWSCURRENT
的版本。
在以下示例中,
TestSecret
是存储在 Secrets Manager 中的键值对的名称。的键为TestSecret
。MY_SECRET_VAR
您可以使用LOCAL_SECRET_VAR
名称在构建期间访问变量。env: secrets-manager: LOCAL_SECRET_VAR: "TestSecret:MY_SECRET_VAR"
有关更多信息,请参阅 AWS Secrets Manager 用户指南 中的什么是 AWS Secrets Manager。
- env/exported-variables
-
可选的映射。用于列出您要导出的环境变量。在
exported-variables
下的单独行上指定要导出的每个变量的名称。 在构建期间,要导出的变量必须在容器中可用。导出的变量可以是环境变量。在构建期间,变量的值从
install
阶段开始可用。可以在install
阶段开始和post_build
阶段结束之间更新变量的值。在post_build
阶段结束后,无法更改导出的变量的值。注意 无法导出以下项:
-
构建项目中指定的 Amazon EC2 Systems Manager Parameter Store 密钥。
-
构建项目中指定的Secrets Manager 密钥
-
以
AWS_
开头的环境变量。
-
- env/git-credential-helper
-
可选的映射。用于指示 CodeBuild 是否使用其 Git 凭证辅助程序提供 Git 凭证。
yes
(如果已使用)。否则为no
或未指定。有关更多信息,请参阅 Git 网站上的 gitcredentials。 注意 由 Webhook 触发的公有 Git 存储库的构建不支持
git-credential-helper
。
proxy
可选的序列。如果是在显式代理服务器中运行构建,则用于表示设置。有关更多信息,请参阅 在显式代理服务器中运行 CodeBuild。
phases
必需的序列。表示 CodeBuild 在构建的各个阶段将运行的命令。
在构建规范版本 0.1 中,CodeBuild 将在构建环境中的默认 Shell 的单独实例中运行每条命令。这表示各个命令独立于其他所有命令而运行。因此,在默认情况下,您无法运行依赖所有上一个命令状态的单个命令 (如更改目录或设置环境变量)。要绕开此限制,建议使用版本 0.2 来解决此问题。如果必须使用构建规范版本 0.1,建议使用构建环境中的 Shell 和命令中的方法。
允许的构建阶段名称是:
- phases/install
-
可选的序列。表示 CodeBuild 在安装过程中将运行的命令(如果有)。建议使用仅适用于在构建环境中安装软件包的
install
阶段。例如,您可以使用此阶段来安装代码测试框架(如 Mocha 或 RSpec)。- phases/install/runtime-versions
-
可选的序列。Ubuntu 标准映像 2.0 或更高版本以及 Amazon Linux 2 标准映像 1.0 或更高版本支持运行时版本。如果指定,则本节中必须包含至少一个运行时。使用特定版本指定运行时,主要版本后跟
.x
以指定 CodeBuild 使用该主要版本及其最新次要版本,或后跟latest
以使用最新的主要版本和次要版本(例如java: openjdk11
、ruby: 2.6
、nodejs: 12.x
或java: latest
)。您可以使用一个数字或一个环境变量来指定运行时。例如,如果您使用 Amazon Linux 2 标准映像 2.0,则下面指定安装版本 8 的 Java、python 版本 3 的最新次要版本以及 Ruby 的环境变量中包含的版本。有关更多信息,请参阅CodeBuild 提供的 Docker 映像。phases: install: runtime-versions: java: corretto8 python: 3.x ruby: "$MY_RUBY_VAR"
You can specify one or more runtimes in the
runtime-versions
section of your buildspec file. If your runtime is dependent upon another runtime, you can also specify its dependent runtime in the buildspec file. If you do not specify any runtimes in the buildspec file, CodeBuild chooses the default runtimes that are available in the image you use. If you specify one or more runtimes, CodeBuild uses only those runtimes. If a dependent runtime is not specified, CodeBuild attempts to choose the dependent runtime for you.如果两个指定运行时冲突,构建将失败。例如,
android: 29
和java: openjdk11
冲突,因此,如果同时指定了这两项,构建将失败。可以指定以下支持的运行时。
Ubuntu 和 Amazon Linux 2 平台运行时运行时名称 Version 映像 特定版本 特定主要和最新次要版本 最新版本 android 28
Amazon Linux 2 标准:2.0
Amazon Linux 2 标准:3.0
Ubuntu 标准:3.0
Ubuntu 标准:4.0
android: 28
android: 28.x
android: latest
29
Amazon Linux 2 标准:2.0
Amazon Linux 2 标准:3.0
Ubuntu 标准:3.0
Ubuntu 标准:4.0
android: 29
android: 29.x
dotnet 3.0
Amazon Linux 2 标准:2.0
Ubuntu 标准:3.0
dotnet: 3.0
dotnet: 3.x
dotnet: latest
3.1
Amazon Linux 2 标准:3.0
Ubuntu 标准:4.0
Ubuntu 标准:5.0
dotnet: 3.1
5.0 Ubuntu 标准:5.0 dotnet: 5.0
dotnet: 5.x
Golang 1.12
所有支持的 Amazon Linux 2 映像
Ubuntu 标准:3.0
Ubuntu 标准:4.0
golang: 1.12
golang: 1.x
golang: latest
1.13
所有支持的 Amazon Linux 2 映像
Ubuntu 标准:3.0
Ubuntu 标准:4.0
golang: 1.13
1.14
Amazon Linux 2 标准:3.0
Ubuntu 标准:4.0
golang: 1.14
1.15 Ubuntu 标准:5.0
golang: 1.15
nodejs 10
所有支持的 Amazon Linux 2 映像
Ubuntu 标准:3.0
Ubuntu 标准:4.0
nodejs: 10
nodejs: 10.x
nodejs: latest
12
所有支持的 Amazon Linux 2 映像
所有 Ubuntu 映像
nodejs: 12
nodejs: 12.x
14 Ubuntu 标准:5.0
nodejs: 14
nodejs: 14.x
java openjdk8
Ubuntu 标准:3.0
java: openjdk8
java: openjdk8.x
java: latest
openjdk11
Ubuntu 标准:3.0
java: openjdk11
java: openjdk11.x
corretto8
Amazon Linux 2 标准:2.0
Amazon Linux 2 标准:3.0
Ubuntu 标准:4.0
Ubuntu 标准:5.0
java: corretto8
java: corretto8.x
corretto11
Amazon Linux 2 标准:2.0
Amazon Linux 2 标准:3.0
Ubuntu 标准:4.0
Ubuntu 标准:5.0
java: corretto11
java: corretto11.x
php 7.3
所有支持的 Amazon Linux 2 映像
所有 Ubuntu 映像
php: 7.3
php: 7.x
php: latest
7.4
Amazon Linux 2 标准:3.0
Ubuntu 标准:4.0
Ubuntu 标准:5.0
php: 7.4
8.0 Ubuntu 标准:5.0
php: 8.0
php: 8.x
python 3.7
Amazon Linux 2 标准:3.0
Amazon Linux 2 aarch64:1.0
Ubuntu 标准:4.0
Ubuntu 标准:5.0
python: 3.7
python: 3.x
python: latest
3.8
Amazon Linux 2 标准:2.0
Amazon Linux 2 标准:3.0
所有 Ubuntu 映像
python: 3.8
3.9 Ubuntu 标准:5.0
python: 3.9
ruby 2.6
所有支持的 Amazon Linux 2 映像
所有 Ubuntu 映像
ruby: 2.6
ruby: 2.x
ruby: latest
2.7
Amazon Linux 2 标准:3.0
Ubuntu 标准:4.0
Ubuntu 标准:5.0
ruby: 2.7
注意 If you specify a
runtime-versions
section and use an image other than Ubuntu Standard Image 2.0 or later, or the Amazon Linux 2 (AL2) standard image 1.0 or later, the build issues the warning, "Skipping install of runtimes. Runtime version selection is not supported by this build image
."
- phases/pre_build
-
可选的序列。表示 CodeBuild 在构建之前将运行的命令(如果有)。例如,可以使用此阶段登录 Amazon ECR,也可以安装 npm 依赖项。
- phases/build
-
可选的序列。表示 CodeBuild 在生成过程中将运行的命令(如果有)。例如,您可以使用此阶段运行 Mocha、RSpec 或 sbt。
- phases/post_build
-
可选的序列。表示 CodeBuild 在生成后将运行的命令(如果有)。例如,您可以使用 Maven 将构建项目打包成 JAR 或 WAR 文件,还可以将 Docker 映像推入到 Amazon ECR 中。然后,您可以通过 Amazon SNS 发送构建通知。
如果早期构建阶段中的命令失败,则一些构建阶段中的命令可能无法运行。例如,如果 install
阶段的命令失败,则 pre_build
、build
和 post_build
阶段的命令都不会在构建的生命周期内运行。有关更多信息,请参阅构建阶段过渡。
reports
- report-group-name-or-arn
-
可选的序列。指定报告将发送到的报告组。一个项目最多可具有五个报告组。指定现有报告组的 ARN 或新报告组的名称。如果您指定名称,CodeBuild 将使用项目名称和您指定的格式为
<project-name>-<report-group-name>
的名称创建一个报告组。 有关更多信息,请参阅报告组命名。 - reports/<report-group>/files
-
必需的序列。表示由报告生成的测试结果的原始数据所在的位置。包含一系列标量,其中各个标量表示一个相对于原始构建位置的单独位置(CodeBuild 可在此处查找测试文件;如果设置,则代表
base-directory
)。 位置可包含以下内容:-
单个文件 (如
my-test-report-file.json
)。 -
子目录中的单个文件 (例如,
或my-subdirectory
/my-test-report-file.json
)。my-parent-subdirectory
/my-subdirectory
/my-test-report-file.json -
'**/*'
表示所有文件均采用递归方式。 -
表示子目录中名为 的所有文件my-subdirectory
/*my-subdirectory
. -
表示从名为 的子目录以递归方式开始的所有文件my-subdirectory
/**/*my-subdirectory
.
-
- reports/<report-group>/file-format
-
可选的映射。表示报告文件格式。如果未指定,则使用
JUNITXML
。此值不区分大小写。可能的值有:测试报告
代码覆盖范围报告
-
CLOVERXML
-
XML -
-
COBERTURAXML
-
Cobertura XML
-
JACOCOXML
-
JaCoCo XML
-
SIMPLECOV
-
SimpleCov JSON
注意 CodeBuild 接受由 simplecov
而非 simplecov-json 生成的 JSON 代码覆盖率报告。
-
- reports/<report-group>/base-directory
-
可选的映射。表示一个或多个顶级目录(相对于原始构建位置),CodeBuild 使用该目录确定在何处查找原始测试文件。
- reports/<report-group>/discard-paths
-
可选。指定是否在输出中展平报告文件目录。如果未指定此项或包含
no
,则将输出报告文件,并且其目录结构保持不变。如果此项包含yes
,则将所有测试文件放置在同一个输出目录中。例如,如果测试结果的路径为com/myapp/mytests/TestResult.xml
,指定yes
会将此文件放置在/TestResult.xml
中。
artifacts
可选的序列。表示有关 CodeBuild 可在何处查找构建输出以及 CodeBuild 如何进行准备以便将其上传到 S3 输出存储桶的信息。如果出现以下情况,则不需要此序列,例如,您正在构建或将 Docker 映像推送到 Amazon ECR,或者正在运行源代码上的单元测试,但并未构建源代码。
- artifacts/files
-
必需的序列。表示包含构建环境中的输出项目的位置。包含一系列标量,其中每个标量表示一个相对于原始构建位置或基本目录 (如果已设置) 的单独位置,CodeBuild 可在此处查找构建输出项目。位置可包含以下内容:
-
单个文件 (如
my-file.jar
)。 -
子目录中的单个文件 (例如,
或my-subdirectory
/my-file.jar
)。my-parent-subdirectory
/my-subdirectory
/my-file.jar -
'**/*'
表示所有文件均采用递归方式。 -
表示子目录中名为 的所有文件my-subdirectory
/*my-subdirectory
. -
表示从名为 的子目录以递归方式开始的所有文件my-subdirectory
/**/*my-subdirectory
.
您在指定构建输出项目位置时,CodeBuild 可在构建环境中查找原始构建位置。您无需将包含路径的构建项目输出位置放在原始构建位置的前面,或指定
./
或类似。如果您需要了解此位置的路径,则可以在构建过程中运行命令echo $CODEBUILD_SRC_DIR
。各个构建环境的位置可能略有不同。 -
- artifacts/name
-
可选的名称。为构建构件指定名称。将在以下任一条件为 true 时使用此名称。
-
使用 CodeBuild API 创建构建,并于更新项目、创建项目或启动构建后,在
ProjectArtifacts
对象上设置overrideArtifactName
标记。 -
使用 CodeBuild 控制台创建您的构建,在构建规范文件中指定名称,并在创建或更新项目时选择 Enable semantic versioning (启用语义版本控制)。有关更多信息,请参阅创建构建项目 (控制台)。
可以在构建规范文件中指定在构建时计算得出的名称。构建规范文件中指定的名称使用 Shell 命令语言。例如,您可以将日期和时间附加到您的项目名称后面,以便它始终是唯一的。构件名称唯一防止覆盖构件。有关更多信息,请参阅 Shell 命令语言
。 这是追加有构件创建日期的构件名称的示例。
version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: myname-$(date +%Y-%m-%d)
这是使用 CodeBuild 环境变量的构件名称的示例。有关更多信息,请参阅构建环境中的环境变量。
version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: myname-$AWS_REGION
这是使用 CodeBuild 环境变量且追加了构件创建日期的构件名称的示例。
version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: $AWS_REGION-$(date +%Y-%m-%d)
-
- artifacts/discard-paths
-
可选。指定是否在输出中展平构建构件目录。如果未指定此项或包含
no
,则将输出构建构件,并且其目录结构保持不变。如果此项包含yes
,则将所有构建构件放置在同一个输出目录中。例如,如果构建输出构件中某个文件的路径为com/mycompany/app/HelloWorld.java
,则指定yes
会将此文件放置在/HelloWorld.java
中。 - artifacts/base-directory
-
可选的映射。表示相对于原始构建位置的一个或多个顶级目录,CodeBuild 使用这些目录确定在构建输出项目中包含哪些文件和子目录。有效值包括:
-
单个顶级目录 (如
my-directory
)。 -
'my-directory*'
表示名称以my-directory
为开头的所有顶级目录。
构建输出项目中不包含映射顶级目录,只包含其文件和子目录。
您可以使用
files
和discard-paths
进一步限制包含哪些文件和子目录。例如,对于以下目录结构:. ├── my-build1 │ └── my-file1.txt └── my-build2 ├── my-file2.txt └── my-subdirectory └── my-file3.txt
对于以下
artifacts
序列:artifacts: files: - '*/my-file3.txt' base-directory: my-build2
以下子目录和文件应包含在构建输出项目中:
. └── my-subdirectory └── my-file3.txt
对于以下
artifacts
序列:artifacts: files: - '**/*' base-directory: 'my-build*' discard-paths: yes
以下文件应包含在构建输出项目中:
. ├── my-file1.txt ├── my-file2.txt └── my-file3.txt
-
- artifacts/secondary-artifacts
-
可选的序列。将一个或多个构件定义表示为构件标识符与构件定义之间的映射。此块中的每个构件标识符都必须与项目的
secondaryArtifacts
属性中定义的构件匹配。每个单独的定义与上面的artifacts
块具有相同的语法。注意 即使仅定义了辅助构件,artifacts/files 序列也始终是必需的。
例如,如果项目具有以下结构:
{ "name": "sample-project", "secondaryArtifacts": [ { "type": "S3", "location": "output-bucket1", "artifactIdentifier": "artifact1", "name": "secondary-artifact-name-1" }, { "type": "S3", "location": "output-bucket2", "artifactIdentifier": "artifact2", "name": "secondary-artifact-name-2" } ] }
则 Buildpec 如下所示:
version: 0.2 phases: build: commands: - echo Building... artifacts: files: - '**/*' secondary-artifacts: artifact1: files: - directory/file1 name: secondary-artifact-name-1 artifact2: files: - directory/file2 name: secondary-artifact-name-2
cache
可选的序列。表示 CodeBuild 可在何处准备用于将缓存上传到 S3 缓存存储桶的文件的相关信息。如果项目的缓存类型为 No Cache
,则不需要此序列。
- cache/paths
-
必需的序列。表示缓存的位置。包含一系列标量,其中每个标量表示一个相对于原始构建位置或基本目录 (如果已设置) 的单独位置,CodeBuild 可在此处查找构建输出项目。位置可包含以下内容:
-
单个文件 (如
my-file.jar
)。 -
子目录中的单个文件 (例如,
或my-subdirectory
/my-file.jar
)。my-parent-subdirectory
/my-subdirectory
/my-file.jar -
'**/*'
表示所有文件均采用递归方式。 -
表示子目录中名为 的所有文件my-subdirectory
/*my-subdirectory
. -
表示从名为 的子目录以递归方式开始的所有文件my-subdirectory
/**/*my-subdirectory
.
-
因为构建规范声明必须为有效的 YAML,所以构建规范声明中的空格至关重要。如果构建规范声明中的空格数量无效,则构建可能会立即失败。您可以使用 YAML 验证程序测试构建规范声明是否为效的 YAML。
如果您在创建或更新构建项目时使用 AWS CLI 或 AWS SDKs 声明构建规范,则构建规范必须是以 YAML 格式表示的单个字符串,包括必需的空格和换行转义字符。将在下一部分中提供示例。
如果您使用 CodeBuild 或 AWS CodePipeline 控制台而不是 buildspec.yml 文件,则您只能插入适合 build
阶段的命令。不要使用前一语法,改为单行列出要在构建阶段运行的所有命令。对于多个命令,使用 &&
分开各个命令 (例如 mvn test && mvn
package
)。
您可以使用 CodeBuild 或 CodePipeline 控制台而不是 buildspec.yml 文件指定构建环境中构建输出项目的位置。您不要使用前一语法,而是要使用单行列出所有位置。对于多个位置,使用逗号分开各个位置
(buildspec.yml, target/my-app.jar
)。
构建规范示例
以下是 buildspec.yml 文件的示例。
version: 0.2 env: variables: JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64" parameter-store: LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword phases: install: commands: - echo Entered the install phase... - apt-get update -y - apt-get install -y maven finally: - echo This always runs even if the update or install command fails pre_build: commands: - echo Entered the pre_build phase... - docker login –u User –p $LOGIN_PASSWORD finally: - echo This always runs even if the login command fails build: commands: - echo Entered the build phase... - echo Build started on `date` - mvn install finally: - echo This always runs even if the install command fails post_build: commands: - echo Entered the post_build phase... - echo Build completed on `date` reports: arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1: files: - "**/*" base-directory: 'target/tests/reports' discard-paths: no reportGroupCucumberJson: files: - 'cucumber/target/cucumber-tests.xml' discard-paths: yes file-format: CUCUMBERJSON # default is JUNITXML artifacts: files: - target/messageUtil-1.0.jar discard-paths: yes secondary-artifacts: artifact1: files: - target/artifact-1.0.jar discard-paths: yes artifact2: files: - target/artifact-2.0.jar discard-paths: yes cache: paths: - '/root/.m2/**/*'
以下是上一构建规范的示例,此规范与 AWS CLI 或 AWS SDKs 一起使用并表示为单个字符串。
"version: 0.2\n\nenv:\n variables:\n JAVA_HOME: \"/usr/lib/jvm/java-8-openjdk-amd64\\"\n parameter-store:\n LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword\n phases:\n\n install:\n commands:\n - echo Entered the install phase...\n - apt-get update -y\n - apt-get install -y maven\n finally:\n - echo This always runs even if the update or install command fails \n pre_build:\n commands:\n - echo Entered the pre_build phase...\n - docker login –u User –p $LOGIN_PASSWORD\n finally:\n - echo This always runs even if the login command fails \n build:\n commands:\n - echo Entered the build phase...\n - echo Build started on `date`\n - mvn install\n finally:\n - echo This always runs even if the install command fails\n post_build:\n commands:\n - echo Entered the post_build phase...\n - echo Build completed on `date`\n\n reports:\n reportGroupJunitXml:\n files:\n - \"**/*\"\n base-directory: 'target/tests/reports'\n discard-paths: false\n reportGroupCucumberJson:\n files:\n - 'cucumber/target/cucumber-tests.xml'\n file-format: CUCUMBERJSON\n\nartifacts:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n secondary-artifacts:\n artifact1:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n artifact2:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n cache:\n paths:\n - '/root/.m2/**/*'"
以下是 build
阶段中命令的示例,与 CodeBuild 或 CodePipeline 控制台一起使用。
echo Build started on `date` && mvn install
在这些示例中:
-
将设置密钥为
JAVA_HOME
,值为/usr/lib/jvm/java-8-openjdk-amd64
的纯文本格式的自定义环境变量。 -
之后,将通过使用密钥
LOGIN_PASSWORD
在构建命令中引用您在 Amazon EC2 Systems Manager Parameter Store 中存储的一个名为dockerLoginPassword
的自定义环境变量。 -
您无法更改这些构建阶段名称。将在此示例中运行的命令有
apt-get update -y
、apt-get install -y maven
(用于安装 Apache Maven)、mvn install
(用于编译和测试源代码并将源代码打包到构建输出项目中,以及在构建输出构件的内部存储库中安装该项目)、docker login
(用于使用与您在 Amazon EC2 Systems Manager Parameter Store 中设置的自定义环境变量dockerLoginPassword
的值对应的密码登录 Docker)以及若干echo
命令。此处包含的echo
命令用于显示 CodeBuild 运行命令的方式以及运行命令的顺序。 -
files
表示要上传到构建输出位置的文件。在此示例中,CodeBuild 上传单个文件messageUtil-1.0.jar
。 在生成环境中名为messageUtil-1.0.jar
的相对目录中,可找到target
文件。由于指定了discard-paths: yes
,因此将直接上传messageUtil-1.0.jar
(而不上传到中间target
目录)。文件名称messageUtil-1.0.jar
和target
的相对目录名称均基于 Apache Maven 如何创建并存储构建输出项目 (仅针对此示例)。在您自己的方案中,这些文件名称和目录会有所不同。 -
reports
表示在构建过程中生成报告的两个报告组:-
arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1
指定报告组的 ARN。测试框架生成的测试结果位于target/tests/reports
目录中。文件格式为JunitXml
,路径不会从包含测试结果的文件中删除。 -
reportGroupCucumberJson
指定一个新的报告组。如果项目名称为my-project
,则在运行构建时创建一个名为my-project-reportGroupCucumberJson
的报告组。测试框架生成的测试结果位于cucumber/target/cucumber-tests.xml
中。 测试文件格式为CucumberJson
,路径将从包含测试结果的文件中删除。
-
构建规范版本
下表列出了构建规范版本以及版本间的变化。
Version | 更改 |
---|---|
0.2 |
|
0.1 | 这是构建规范格式的初始定义。 |