此主题提供有关构建规范 (buildspec) 文件的重要参考信息。buildspec 是构建命令和相关设置的集合,采用 YAML 格式,由 CodeBuild 用来运行构建任务。您可以将 buildspec 作为源代码的一部分,也可以在创建构建项目时定义 buildspec。有关 buildspec 工作原理的信息,请参阅 CodeBuild 的工作原理。
buildspec 文件名称和存储位置
如果您在源代码中包含 buildspec,则默认情况下,buildspec 文件必须命名为 buildspec.yml
且放置在源目录的根目录中。
可以覆盖默认 buildspec 文件名和位置。例如,您可以:
-
对同一存储库中的不同构建使用不同的 buildspec 文件,如
buildspec_debug.yml
和buildspec_release.yml
。 -
将 buildspec 文件存储在源目录的根目录之外的位置,如
config/buildspec.yml
或 S3 存储桶。S3 存储桶必须与您的构建项目位于同一 AWS 区域。使用其 ARN 指定 buildspec 文件(例如,arn:aws:s3:::
)。<my-codebuild-sample2>
/buildspec.yml
您可以只为构建项目指定一个 buildspec,而不管 buildspec 文件的名称如何。
要覆盖默认 buildspec 文件名、默认位置或这两者,执行下列操作之一:
-
运行 AWS CLI
create-project
或update-project
命令,将buildspec
值设置为备用 buildspec 文件的路径(相对于内置环境变量CODEBUILD_SRC_DIR
的值)。您还可以在 AWS 开发工具包中执行与create project
操作等效的操作。有关更多信息,请参阅创建构建项目或更改构建项目设置。 -
运行 AWS CLI
start-build
命令,将buildspecOverride
值设置为备用 buildspec 文件的路径(相对于内置环境变量CODEBUILD_SRC_DIR
的值)。您还可以在 AWS 开发工具包中执行与start build
操作等效的操作。有关更多信息,请参阅 手动运行构建。 -
在 AWS CloudFormation 模板中,将类型为
AWS::CodeBuild::Project
的资源中Source
的BuildSpec
属性设置为备用 buildspec 文件的路径(相对于内置环境变量CODEBUILD_SRC_DIR
的值)。有关更多信息,请参阅《AWS CloudFormation 用户指南》中AWS CodeBuild 项目源中的 BuildSpec 属性。
buildspec 语法
buildspec 文件必须以 YAML
如果命令包含 YAML 不支持的字符或字符串,则必须用引号 ("") 将命令括起来。以下命令用引号括起来,因为在 YAML 中不允许使用冒号 (:) 后跟空格。命令中的引号会被转义 (\")。
"export PACKAGE_NAME=$(cat package.json | grep name | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g')"
buildspec 的语法如下:
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
on-failure: ABORT | CONTINUE
runtime-versions:
runtime
: version
runtime
: version
commands:
- command
- command
finally:
- command
- command
pre_build:
run-as: Linux-user-name
on-failure: ABORT | CONTINUE
commands:
- command
- command
finally:
- command
- command
build:
run-as: Linux-user-name
on-failure: ABORT | CONTINUE
commands:
- command
- command
finally:
- command
- command
post_build:
run-as: Linux-user-name
on-failure: ABORT | CONTINUE
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
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
buildspec 包含以下内容:
版本
必需的映射。表示 buildspec 版本。建议使用 0.2
。
注意
虽然仍支持版本 0.1,但建议尽可能使用版本 0.2。有关更多信息,请参阅 buildspec 版本。
run-as
可选的序列。仅适用于 Linux 用户。指定用于运行此 buildspec 文件中的命令的 Linux 用户。run-as
向指定的用户授予读取和运行权限。当您在 buildspec 文件的顶部指定 run-as
时,它将全局应用于所有命令。如果您不希望为所有 buildspec 文件命令指定一个用户,可以通过在其中一个 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/shell
-
可选的序列。指定 Linux 或 Windows 操作系统支持的 shell。
对于 Linux 操作系统,支持的 shell 标签有:
-
bash
-
/bin/sh
对于 Windows 操作系统,支持的 shell 标签有:
-
powershell.exe
-
cmd.exe
-
- env/variables
-
在指定了
env
并且您希望定义纯文本格式的自定义环境变量时必需。包含key
/value
标量的映射,其中每个映射表示一个纯文本形式的自定义环境变量。key
是自定义环境变量的名称,value
是该变量的值。重要
我们强烈建议不要将敏感值存储在环境变量中。使用 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 中更改构建项目设置:
-
buildspec 声明中的值优先级最低。
-
- 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 中的自定义环境变量的名称。要存储敏感值,请参阅《Amazon EC2 Systems Manager 用户指南》中的 Systems Manager Parameter Store 和演练:创建和测试参数(控制台)。重要
要允许 CodeBuild 检索存储在 Amazon EC2 Systems Manager Parameter Store 中的自定义环境变量,您必须将
ssm:GetParameters
操作添加到您的 CodeBuild 服务角色。有关更多信息,请参阅 允许 CodeBuild 与其他 AWS 服务进行交互。从 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 中更改构建项目设置:
-
buildspec 声明中的值优先级最低。
-
- 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
下的单独行上指定要导出的每个变量的名称。在构建过程中,要导出的变量必须在容器中可用。导出的变量可以是环境变量。导出的环境变量与 AWS CodePipeline 结合使用,将环境变量从管道的当前构建阶段导出到后续阶段。有关更多信息,请参阅《AWS CodePipeline 用户指南》中的使用变量。
在构建期间,变量的值从
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。
- proxy/upload-artifacts
-
可选的映射。如果您希望显式代理服务器中的构建来上传构件,请设置为
yes
。默认为no
。 - proxy/logs
-
可选的映射。要使显式代理服务器中的构建创建 CloudWatch 日志,请设置为
yes
。默认为no
。
phases
必需的序列。表示 CodeBuild 在构建的各个阶段将运行的命令。
注意
在 buildspec 版本 0.1 中,CodeBuild 将在构建环境中的默认 Shell 的单独实例中运行每条命令。这表示各个命令独立于其他所有命令而运行。因此,在默认情况下,您无法运行依赖所有上一个命令状态的单个命令(如更改目录或设置环境变量)。要绕开此限制,建议使用版本 0.2 来解决此问题。如果必须使用 buildspec 版本 0.1,建议使用构建环境中的 Shell 和命令中的方法。
- phases/*/run-as
-
可选的序列。在构建阶段中使用,以指定运行命令的 Linux 用户。如果还在 buildspec 文件的顶部为所有命令全局指定了
run-as
,则阶段级别用户优先。例如,如果在全局范围内将run-as
指定为 User-1,而仅针对install
阶段将run-as
语句指定为 User-2,则除install
阶段的命令外,buildspec 文件中的所有命令都将以 User-1 的身份运行。 - phases/*/on-failure
-
可选的序列。指定该阶段发生故障时要采取的操作。它可以是以下值之一:
-
ABORT
- 中止构建。 -
CONTINUE
- 继续到下一阶段。
如果未指定此属性,则发生故障后会进入转换阶段,如构建阶段过渡所述。
-
- phases/*/finally
-
可选的数据块。在
finally
语句块中指定的命令在commands
语句块命令之后运行。即便commands
语句块命令失败,仍会运行finally
语句块命令。例如,如果commands
语句块包含三条命令,而第一条命令失败了,则 CodeBuild 会跳过剩下的两条命令来运行finally
语句块中的任何命令。当commands
和finally
语句块中的所有命令都成功运行后,此阶段才算成功。如果某个阶段有任何命令失败,则该阶段失败。
允许的构建阶段名称是:
- phases/install
-
可选的序列。表示 CodeBuild 在安装过程中将运行的命令(如果有)。建议使用仅适用于在构建环境中安装软件包的
install
阶段。例如,您可以使用此阶段来安装代码测试框架 (如 Mocha 或 RSpec)。- phases/install/runtime-versions
-
可选的序列。Ubuntu 标准映像 5.0 或更高版本以及 Amazon Linux 2 标准映像 4.0 或更高版本支持运行时版本。如果指定,则本节中必须包含至少一个运行时。使用特定版本指定运行时,主要版本后跟
.x
以指定 CodeBuild 使用该主要版本及其最新次要版本,或后跟latest
以使用最新的主要版本和次要版本(例如ruby: 3.2
、nodejs: 18.x
或java: latest
)。您可以使用一个数字或一个环境变量来指定运行时。例如,如果您使用 Amazon Linux 2 标准映像 4.0,则下面指定安装版本 17 的 Java、python 版本 3 的最新次要版本以及 Ruby 的环境变量中包含的版本。有关更多信息,请参阅 CodeBuild 提供的 Docker 映像。phases: install: runtime-versions: java: corretto8 python: 3.x ruby: "$MY_RUBY_VAR"
您可以在 buildspec 文件的
runtime-versions
部分中指定一个或多个运行时。如果您的运行时依赖于另一个运行时,您还可以在 buildspec 文件中指定其依赖运行时。如果您未在 buildspec 文件中指定任何运行时,CodeBuild 选择在您使用的映像中提供的默认运行时。如果指定一个或多个运行时,则 CodeBuild 仅使用这些运行时。如果未指定依赖运行时,则 CodeBuild 尝试为您选择依赖运行时。如果两个指定运行时冲突,构建将失败。例如,
android: 29
和java: openjdk11
冲突,因此,如果同时指定了这两项,构建将失败。有关可用运行时的更多信息,请参阅可用的运行时。
注意
如果您指定
runtime-versions
部分且使用的映像不是 Ubuntu 标准映像 2.0 或更高版本或 Amazon Linux 2(AL2)标准映像 1.0 或更高版本,则构建会发出警告“Skipping install of runtimes. Runtime version selection is not supported by this build image
”。
- phases/install/commands
-
可选的序列。包含一系列标量,其中各个标量表示 CodeBuild 将在安装过程中运行的单个命令。CodeBuild 按照列出的顺序从开始到结束一次运行一个命令。
- phases/pre_build
-
可选的序列。表示 CodeBuild 在构建之前将运行的命令(如果有)。例如,可以使用此阶段登录 Amazon ECR,也可以安装 npm 依赖项。
- phases/pre_build/commands
-
如果指定
pre_build
,则为必需的序列。包含一系列标量,其中各个标量表示 CodeBuild 将在生成前运行的单个命令。CodeBuild 按照列出的顺序从开始到结束一次运行一个命令。
- phases/build
-
可选的序列。表示 CodeBuild 在构建期间运行的命令(如果有)。例如,您可以使用此阶段运行 Mocha、RSpec 或 sbt。
- phases/build/commands
-
在指定
build
时是必需的。包含一系列标量,其中各个标量表示 CodeBuild 将在构建过程中运行的单个命令。CodeBuild 按照列出的顺序从开始到结束一次运行一个命令。
- phases/post_build
-
可选的序列。表示 CodeBuild 在构建之后运行的命令(如果有)。例如,您可以使用 Maven 将构建构件打包成 JAR 或 WAR 文件,还可以将 Docker 映像推入到 Amazon ECR 中。然后,您可以通过 Amazon SNS 发送构建通知。
- phases/post_build/commands
-
在指定
post_build
时是必需的。包含一系列标量,其中各个标量表示 CodeBuild 将在构建后运行的单个命令。CodeBuild 按照列出的顺序从开始到结束一次运行一个命令。
reports
- report-group-name-or-arn
-
可选的序列。指定报告将发送到的报告组。一个项目最多可具有五个报告组。指定现有报告组的 ARN 或新报告组的名称。如果您指定一个名称,CodeBuild 将使用项目名称和您指定的格式为
<project-name>-<report-group-name>
的名称创建一个报告组。也可以使用 buildspec 中的环境变量(例如$REPORT_GROUP_NAME
)来设置报告组名称。有关更多信息,请参阅 报告组命名。 - reports/<report-group>/files
-
必需的序列。表示由报告生成的测试结果的原始数据所在的位置。包含一系列标量,其中各个标量表示一个相对于原始构建位置或
base-directory
(如果已设置)的单独位置,CodeBuild 可在此处查找测试文件。位置可包含以下内容:-
单个文件 (如
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
。此值不区分大小写。可能的值有:测试报告
-
CUCUMBERJSON
-
Cucumber JSON
-
JUNITXML
-
JUnit XML
-
NUNITXML
-
NUnit XML
-
NUNIT3XML
-
NUnit 3 XML
-
TESTNGXML
-
TestNG XML
-
VISUALSTUDIOTRX
-
Visual Studio TRX
代码覆盖率报告
-
CLOVERXML
-
Clover 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,或者正在运行源代码上的单元测试,但并未构建源代码。
注意
Amazon S3 元数据有一个名为 x-amz-meta-codebuild-buildarn
的 CodeBuild 标头,其中包含将构件发布到 Amazon S3 的 CodeBuild 构建的 buildArn
。添加 buildArn
是为了允许对通知进行源跟踪并引用生成构件的构建。
- 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 控制台创建您的构建,在 buildspec 文件中指定名称,并在创建或更新项目时选择启用语义版本控制。有关更多信息,请参阅 创建构建项目(控制台)。
可以在 buildspec 文件中指定在构建时计算得出的名称。buildspec 文件中指定的名称使用 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)
您可以在名称中添加路径信息,这样可以根据名称中的路径将命名的构件放置在目录中。在此示例中,构建构件放在
builds/<build number>/my-artifacts
下的输出中。version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: builds/$CODEBUILD_BUILD_NUMBER/my-artifacts
-
- 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-build-1 │ └── my-file-1.txt └── my-build-2 ├── my-file-2.txt └── my-subdirectory └── my-file-3.txt
对于以下
artifacts
序列:artifacts: files: - '*/my-file-3.txt' base-directory: my-build-2
以下子目录和文件应包含在构建输出项目中:
. └── my-subdirectory └── my-file-3.txt
对于以下
artifacts
序列:artifacts: files: - '**/*' base-directory: 'my-build*' discard-paths: yes
以下文件应包含在构建输出项目中:
. ├── my-file-1.txt ├── my-file-2.txt └── my-file-3.txt
-
- artifacts/exclude-paths
-
可选的映射。表示一个或多个相对于
base-directory
的路径,CodeBuild 会将其从构建构件中排除。星号 (*
) 字符与不跨越文件夹边界的名称组分的零个或多个字符匹配。双星号 (**
) 与所有目录中名称组分的零个或多个字符匹配。exclude-paths 示例包括以下内容:
-
要从所有目录中排除文件:
"**/
file-name
/**/*" -
要排除所有点文件夹:
"**/.*/**/*"
-
要排除所有点文件:
"**/.*"
-
- artifacts/enable-symlinks
-
可选。如果输出类型为
ZIP
,则指定 ZIP 文件中是否保留内部符号链接。如果为yes
,则来源中的所有内部符号链接都将保留在构件 ZIP 文件中。 - artifacts/s3-prefix
-
可选。指定将构件输出到 Amazon S3 存储桶时使用的前缀,命名空间类型为
BUILD_ID
。如果使用,存储桶中的输出路径为<s3-prefix>/<build-id>/<name>.zip
。 - 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" } ] }则 buildspec 如下所示:
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
的子目录开始。
-
重要
因为 buildspec 声明必须为有效的 YAML,所以 buildspec 声明中的空格至关重要。如果 buildspec 声明中的空格数量无效,则构建可能会立即失败。您可以使用 YAML 验证程序测试 buildspec 声明是否为有效的 YAML。
如果您在创建或更新构建项目时使用 AWS CLI 或 AWS 开发工具包声明 buildspec,则 buildspec 必须是以 YAML 格式表示的单个字符串,包括必需的空格和换行转义字符。将在下一部分中提供示例。
如果您使用 CodeBuild 或 AWS CodePipeline 控制台而不是 buildspec.yml 文件,则您只能插入适合 build
阶段的命令。不要使用前一语法,改为单行列出要在构建阶段运行的所有命令。对于多个命令,使用 &&
分开各个命令(例如 mvn test && mvn
package
)。
您可以使用 CodeBuild 或 CodePipeline 控制台而不是 buildspec.yml 文件指定构建环境中构建输出构件的位置。您不要使用前一语法,而是要使用单行列出所有位置。对于多个位置,使用逗号将各个位置隔开(例如,buildspec.yml, target/my-app.jar
)。
buildspec 示例
以下是 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/**/*'
以下是上一 buildspec 的示例,此规范与 AWS CLI 或 AWS 开发工具包一起使用并表示为单个字符串。
"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
,路径将从包含测试结果的文件中删除。
-
buildspec 版本
下表列出了 buildspec 版本以及版本间的变化。
版本 | 更改 |
---|---|
0.2 |
|
0.1 | 这是 buildspec 格式的初始定义。 |