适用于 CodeBuild 的构建规范参考 - Amazon CodeBuild
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

适用于 CodeBuild 的构建规范参考

此主题提供有关构建规范 (buildspec) 文件的重要参考信息。buildspec 是构建命令和相关设置的集合,采用 YAML 格式,由 CodeBuild 用来运行构建任务。您可以将 buildspec 作为源代码的一部分,也可以在创建构建项目时定义 buildspec。有关 buildspec 工作原理的信息,请参阅 CodeBuild 的工作原理

buildspec 文件名称和存储位置

如果您在源代码中包含 buildspec,则默认情况下,buildspec 文件必须命名为 buildspec.yml 且放置在源目录的根目录中。

可以覆盖默认 buildspec 文件名和位置。例如,您可以:

  • 对同一存储库中的不同构建使用不同的 buildspec 文件,如 buildspec_debug.ymlbuildspec_release.yml

  • 将 buildspec 文件存储在源目录的根目录之外的位置,如 config/buildspec.yml 或 S3 存储桶。S3 存储桶必须与您的构建项目位于同一 Amazon 区域。使用其 ARN 指定 buildspec 文件(例如,arn:aws:s3:::<my-codebuild-sample2>/buildspec.yml)。

您可以只为构建项目指定一个 buildspec,而不管 buildspec 文件的名称如何。

要覆盖默认 buildspec 文件名、默认位置或这两者,执行下列操作之一:

  • 运行 Amazon CLI create-projectupdate-project 命令,将 buildspec 值设置为备用 buildspec 文件的路径(相对于内置环境变量 CODEBUILD_SRC_DIR 的值)。您还可以在 Amazon 开发工具包中执行与 create project 操作等效的操作。有关更多信息,请参阅创建构建项目更改构建项目设置

  • 运行 Amazon CLI start-build 命令,将 buildspecOverride 值设置为备用 buildspec 文件的路径(相对于内置环境变量 CODEBUILD_SRC_DIR 的值)。您还可以在 Amazon 开发工具包中执行与 start build 操作等效的操作。有关更多信息,请参阅 手动运行构建

  • 在 Amazon CloudFormation 模板中,将类型为 AWS::CodeBuild::Project 的资源中 SourceBuildSpec 属性设置为备用 buildspec 文件的路径(相对于内置环境变量 CODEBUILD_SRC_DIR 的值)。有关更多信息,请参阅《Amazon CloudFormation 用户指南》中Amazon 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 日志中隐藏以下内容:

env/shell

可选的序列。指定 Linux 或 Windows 操作系统支持的 shell。

对于 Linux 操作系统,支持的 shell 标签有:

  • bash

  • /bin/sh

对于 Windows 操作系统,支持的 shell 标签有:

  • powershell.exe

  • cmd.exe

env/variables

在指定了 env 并且您希望定义纯文本格式的自定义环境变量时必需。包含 key/value 标量的映射,其中每个映射表示一个纯文本形式的自定义环境变量。key 是自定义环境变量的名称,value 是该变量的值。

重要

我们强烈建议不要将敏感值存储在环境变量中。使用 CodeBuild 控制台和 Amazon CLI 等工具能够以纯文本格式显示环境变量。对于敏感值,建议改用 parameter-storesecrets-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_ 开头的任何环境变量。此前缀是专为内部使用预留的。

如果具有相同名称的环境变量在多处都有定义,则应按照如下方式确定其值:

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 与其他 Amazon 服务进行交互

从 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_ 开头的任何环境变量。此前缀是专为内部使用预留的。

如果具有相同名称的环境变量在多处都有定义,则应按照如下方式确定其值:

env/secrets-manager

您要检索存储在 Amazon Secrets Manager 中的自定义环境变量时必需。使用以下模式指定 Secrets Manager reference-key

<key>: <secret-id>:<json-key>:<version-stage>:<version-id>

<key>

(必需)本地环境变量名称。在构建过程中使用此名称访问变量。

<secret-id>

(必需)用作密钥的唯一标识符的名称或 Amazon 资源名称 (ARN)。要访问您的 Amazon 账户中的密钥,只需指定密钥名称。要访问其他 Amazon 账户中的密钥,请指定密钥 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"

有关更多信息,请参阅《Amazon Secrets Manager 用户指南》中的什么是 Amazon Secrets Manager

env/exported-variables

可选的映射。用于列出您要导出的环境变量。在 exported-variables 下的单独行上指定要导出的每个变量的名称。在构建过程中,要导出的变量必须在容器中可用。导出的变量可以是环境变量。

导出的环境变量与 Amazon CodePipeline 结合使用,将环境变量从管道的当前构建阶段导出到后续阶段。有关更多信息,请参阅《Amazon 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 语句块中的任何命令。当 commandsfinally 语句块中的所有命令都成功运行后,此阶段才算成功。如果某个阶段有任何命令失败,则该阶段失败。

允许的构建阶段名称是:

phases/install

可选的序列。表示 CodeBuild 在安装过程中将运行的命令(如果有)。建议使用仅适用于在构建环境中安装软件包的 install 阶段。例如,您可以使用此阶段来安装代码测试框架 (如 Mocha 或 RSpec)。

phases/install/runtime-versions

可选的序列。Ubuntu 标准映像 5.0 或更高版本以及 Amazon Linux 2 标准映像 4.0 或更高版本支持运行时版本。如果指定,则本节中必须包含至少一个运行时。使用特定版本指定运行时,主要版本后跟 .x 以指定 CodeBuild 使用该主要版本及其最新次要版本,或后跟 latest 以使用最新的主要版本和次要版本(例如 ruby: 3.2nodejs: 18.xjava: 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: 29java: 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.jsonmy-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.jarmy-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 为开头的所有顶级目录。

构建输出项目中不包含映射顶级目录,只包含其文件和子目录。

您可以使用 filesdiscard-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/**/*"

  • 要排除所有点文件夹:"**/.*/**/*"

  • 要排除所有点文件:"**/.*"

可选。如果输出类型为 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.jarmy-parent-subdirectory/my-subdirectory/my-file.jar)。

  • '**/*' 表示所有文件均采用递归方式。

  • my-subdirectory/* 表示名为 my-subdirectory 的子目录中的所有文件。

  • my-subdirectory/**/* 表示采用递归方式的所有文件都从名为 my-subdirectory 的子目录开始。

重要

因为 buildspec 声明必须为有效的 YAML,所以 buildspec 声明中的空格至关重要。如果 buildspec 声明中的空格数量无效,则构建可能会立即失败。您可以使用 YAML 验证程序测试 buildspec 声明是否为有效的 YAML。

如果您在创建或更新构建项目时使用 Amazon CLI 或 Amazon 开发工具包声明 buildspec,则 buildspec 必须是以 YAML 格式表示的单个字符串,包括必需的空格和换行转义字符。将在下一部分中提供示例。

如果您使用 CodeBuild 或 Amazon 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 的示例,此规范与 Amazon CLI 或 Amazon 开发工具包一起使用并表示为单个字符串。

"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 -yapt-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.jartarget 的相对目录名称均基于 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
  • environment_variables 已重命名为 env

  • plaintext 已重命名为 variables

  • artifactstype 属性已被弃用。

  • 在版本 0.1 中,Amazon CodeBuild 将在构建环境内默认 Shell 的单独实例中运行每个构建命令。在版本 0.2 中,CodeBuild 将在构建环境中默认 Shell 的同一实例中运行所有构建命令。

0.1 这是 buildspec 格式的初始定义。