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

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

适用于 CodeBuild 的构建规范参考

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

构建规范文件名称和存储位置

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

可以覆盖默认构建规范文件名和位置。譬如,您可以:

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

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

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

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

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

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

  • 在 Amazon CloudFormation 模板中,将类型为 AWS::CodeBuild::Project 的资源中 SourceBuildSpec 属性设置为备用构建规范文件的路径(相对于内置环境变量 CODEBUILD_SRC_DIR 的值)。有关更多信息,请参阅中的 BuildSpec 属性Amazon CodeBuild项目源中的Amazon 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 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

构建规范包含以下内容:

version

必需的映射。表示构建规范版本。建议使用 0.2

注意

虽然仍支持版本 0.1,但建议尽可能使用版本 0.2。有关更多信息,请参阅 构建规范版本

run-as

可选的序列。仅适用于 Linux 用户。指定用于运行此生成规范文件中的命令的 Linux 用户。run-as授予指定用户读取和运行权限。当您在构建规范文件的顶部指定 run-as 时,它将全局应用于所有命令。如果您不希望为所有构建规范文件命令指定一个用户,可以通过在其中一个 phases 语句块中使用 run-as,为一个阶段中的命令指定一个用户。如果未指定 run-as,则所有命令都将以根用户身份运行。

env

可选的序列。表示一个或多个自定义环境变量的信息。

注意

为了保护敏感信息,隐藏以下内容 CodeBuild 日志:

en/贝壳

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

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

  • bash

  • /bin/sh

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

  • powershell.exe

  • cmd.exe

env/variables

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

重要

强烈建议不要将敏感值(尤其是 Amazon 访问密钥 ID 和秘密访问密钥)存储在环境变量中。使用以下工具能够以纯文本格式显示环境变量: 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 中的自定义环境变量。包含的映射密钥/标量,其中每个映射表示一个存储在 Amazon EC2 Systems Manager Parameter Store 中的自定义环境变量。密钥是您之后在构建命令中用于表示此自定义环境变量的名称,并是存储在 Amazon EC2 Systems Manager Parameter Store 中的自定义环境变量的名称。要存储敏感值,请参阅Systems Manager Parameter Store演练:创建和测试 String 参数(控制台)中的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_ 开头的任何环境变量。此前缀是专为 内部使用预留的。

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

env/secrets-manager

如果您要检索存储在中的自定义环境变量,则必需Amazon Secrets Manager. 指定 Secrets Managerreference-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 中的键值对的名称。的关键TestSecretMY_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_ 开头的环境变量。

en/git-凭证助手

可选的映射。用来表示是否 CodeBuild 使用其 Git 凭证辅助程序来提供 Git 凭证。yes如果使用它。否则为 no 或未指定。有关更多信息,请参阅 Git 网站上的 gitcredentials

注意

由 Webhook 触发的公有 Git 存储库的构建不支持 git-credential-helper

proxy

可选的序列。如果是在显式代理服务器中运行构建,则用于表示设置。有关更多信息,请参阅 在显式代理服务器中运行 CodeBuild

proxy/upload-artifacts

可选的映射。如果您希望显式代理服务器中的构建来上传构件,请设置为 yes。默认为 no

proxy/logs

可选的映射。设置为yes用于在显式代理服务器中创建的构建 CloudWatch 日志。默认为 no

phases

必需的序列。表示命令 CodeBuild 在构建的各个阶段将运行。

注意

在 Buildspec 版本 0.1 中, CodeBuild 在生成环境内默认 Shell 的单独实例中运行各个命令。这表示各个命令独立于其他所有命令而运行。因此,在默认情况下,您无法运行依赖所有上一个命令状态的单个命令 (如更改目录或设置环境变量)。要绕开此限制,建议使用版本 0.2 来解决此问题。如果必须使用构建规范版本 0.1,建议使用构建环境中的 Shell 和命令中的方法。

phases/*/run-as

可选的序列。在构建阶段中使用,以指定运行命令的 Linux 用户。如果还在构建规范文件的顶部为所有命令全局指定了 run-as,则阶段级别用户优先。例如,如果全局run-as指定 User-1 和install只有阶段run-as语句指定 User-2,然后 buildspec 文件中的所有命令都以 User-1 的身份运行除了中的命令install阶段,以 User-2 身份运行。

phases/*/在故障中

可选的序列。指定在此阶段发生故障时要采取的操作。它可以是以下值之一:

  • ABORT-中止构建。

  • CONTINUE-继续下一阶段。

如果未指定此属性,则失败过程将遵循转换阶段,如中所示构建阶段过渡.

phases/*/finally

可选的数据块。中指定的命令finally块在命令之后运行commands数据块。中的命令finally即便在commands数据块失败。例如,如果commands块包含三个命令,第一个命令失败, CodeBuild 跳过剩下的两个命令并在finally数据块。当 commandsfinally 语句块中的所有命令都成功运行后,此阶段才算成功。如果某个阶段有任何命令失败,则该阶段失败。

允许的构建阶段名称是:

phases/install

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

phases/install/runtime-versions

可选的序列。Ubuntu 标准映像 2.0 或更高版本以及 Amazon Linux 2 标准映像 1.0 或更高版本支持运行时版本。如果指定,则本节中必须包含至少一个运行时。使用特定版本指定运行时,主要版本,然后是主要版本.x指定 CodeBuild 使用该主要版本及其最新次要版本,或者latest使用最新的主要和次要版本(例如,java: openjdk11ruby: 2.6nodejs: 12.x,或者java: latest)。您可以使用一个数字或一个环境变量来指定运行时。例如,如果您使用的是 Amazon Linux 2 标准映像 2.0,则下面指定安装版本 8 的 Java、python 版本 3 的最新次要版本以及 Ruby 的环境变量中包含的版本。有关更多信息,请参阅 提供的 Docker 映像 CodeBuild

phases: install: runtime-versions: java: corretto8 python: 3.x ruby: "$MY_RUBY_VAR"

您可以在构建规范文件的 runtime-versions 部分中指定一个或多个运行时。如果您的运行时依赖于另一个运行时,您还可以在构建规范文件中指定其依赖运行时。如果您未在构建规范文件中指定任何运行时, 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 按照列出的顺序从开始到结束一次运行一个命令。

报告

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.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

三叶草 XML

COBERTURAXML

Cobertura XML

JACOCOXML

JaCoCo XML

SIMPLECOV

SimpleCov JSON

注意

CodeBuild 接受由simplecov,不是implecov-json.

reports/<report-group>/base-directory

可选的映射。表示相对于原始构建位置的一个或多个顶级目录,则为 CodeBuild 用于确定在哪里查找原始测试文件。

reports/<report-group>/discard-paths

可选。指定是否在输出中展平报告文件目录。如果未指定此项或包含 no,则将输出报告文件,并且其目录结构保持不变。如果此项包含 yes,则将所有测试文件放置在同一个输出目录中。例如,如果测试结果的路径为 com/myapp/mytests/TestResult.xml,指定 yes 会将此文件放置在 /TestResult.xml 中。

人工制品

可选的序列。表示有关位置的信息 CodeBuild 可以找到构建输出以及如何 CodeBuild 为将其上传到 S3 输出存储桶做好准备。如果出现以下情况,则不需要此序列,例如,您正在构建或将 Docker 镜像推送到 Amazon ECR,或者正在运行源代码上的单元测试,但并未构建源代码。

注意

Amazon S3 元数据有 CodeBuild 标头名为x-amz-meta-codebuild-buildarn其中包含buildArn的 CodeBuild 构建,将构件发布到 Amazon S3。这些区域有: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 和overrideArtifactName标志设置在ProjectArtifacts对象在更新项目、创建项目或启动构建时。

  • 您将 CodeBuild 创建构建的控制台,在构建规范文件中指定了名称,并选择启用语义版本控制创建或更新项目时。有关更多信息,请参阅 创建构建项目 (控制台)

可以在构建规范文件中指定在构建时计算得出的名称。构建规范文件中指定的名称使用 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
文件/件排除路径

可选的映射。表示一条或多条路径,相对于base-directory,那 CodeBuild 将从构建工件中排除。

文件/件启用符号链接

可选。如果输出类型为ZIP,指定是否在 ZIP 文件中保留内部符号链接。如果其中包含yes,源中的所有内部符号链接都将保留在工件 ZIP 文件中。

文件/件s3 前缀

可选。指定将工件输出到 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" } ] }

则 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

缓存

可选的序列。表示有关位置的信息 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 的子目录开始。

重要

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

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

如果您将 CodeBuild 要么Amazon 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/**/*'

以下是上一构建规范的示例,此规范与 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 的纯文本格式的自定义环境变量。

  • 名为的自定义环境变量dockerLoginPassword之后,将通过使用密钥在构建命令中引用您在 Amazon EC2 Systems Manager Parameter Store 中存储的。LOGIN_PASSWORD.

  • 您无法更改这些构建阶段名称。在此示例中运行的命令有:apt-get update -yapt-get install -y maven(安装 Apache Maven),mvn install(用于编译、测试源代码并将其打包成生成输出项目,还将构建输出项目安装在其内部存储库中),docker login(使用与自定义环境变量值对应的密码登录 DockerdockerLoginPassword您在 Amazon EC2 Systems Manager Parameter Store 中设置了,还有几个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,路径将从包含测试结果的文件中删除。

构建规范版本

下表列出了构建规范版本以及版本间的变化。

版本 更改
0.2
  • environment_variables 已重命名为 env

  • plaintext 已重命名为 variables

  • artifactstype 属性已被弃用。

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

0.1 这是构建规范格式的初始定义。