选择您的 Cookie 首选项

我们使用必要 Cookie 和类似工具提供我们的网站和服务。我们使用性能 Cookie 收集匿名统计数据,以便我们可以了解客户如何使用我们的网站并进行改进。必要 Cookie 无法停用,但您可以单击“自定义”或“拒绝”来拒绝性能 Cookie。

如果您同意,AWS 和经批准的第三方还将使用 Cookie 提供有用的网站功能、记住您的首选项并显示相关内容,包括相关广告。要接受或拒绝所有非必要 Cookie,请单击“接受”或“拒绝”。要做出更详细的选择,请单击“自定义”。

适用于 CodeBuild 的构建规范参考

聚焦模式
适用于 CodeBuild 的构建规范参考 - AWS 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 存储桶必须与您的构建项目位于同一 AWS 区域。使用其 ARN 指定 buildspec 文件(例如,arn:aws:s3:::<my-codebuild-sample2>/buildspec.yml)。

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

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

  • 运行 AWS CLI create-projectupdate-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 的资源中 SourceBuildSpec 属性设置为备用 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 日志中隐藏以下内容:

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

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

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 语句块中的任何命令。当 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。

如果您在创建或更新构建项目时使用 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 -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 中,AWS CodeBuild 将在构建环境内默认 Shell 的单独实例中运行每个构建命令。在版本 0.2 中,CodeBuild 将在构建环境中默认 Shell 的同一实例中运行所有构建命令。

0.1 这是 buildspec 格式的初始定义。
隐私网站条款Cookie 首选项
© 2025, Amazon Web Services, Inc. 或其附属公司。保留所有权利。