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

适用于 CodeBuild 的构建规范参考

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

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

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

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

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

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

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

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

  • 运行 AWS CLI create-projectupdate-project 命令,设置 buildspec 相对于内置环境变量的值到备用buildspec文件的路径的值 CODEBUILD_SRC_DIR。您也可以使用等效的 create project 操作 AWS SDK。有关更多信息,请参阅创建构建项目 ()更改构建项目的设置 ()

  • 运行 AWS CLI start-build 命令,设置 buildspecOverride 相对于内置环境变量的值到备用buildspec文件的路径的值 CODEBUILD_SRC_DIR。您也可以使用等效的 start build 操作 AWS SDK。有关更多信息,请参阅 运行构建 ()。)

  • 在 AWS CloudFormation 模板,设置 BuildSpec 属性 Source 类型资源中 AWS::CodeBuild::Project 到替代buildspec文件的路径(相对于内置环境变量的值) 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 日志中隐藏以下内容:

ENV/壳牌

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

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

  • bash

  • /bin/sh

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

  • powershell.exe

  • cmd.exe

env/variables

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

重要

强烈建议不要将敏感值(尤其是 AWS 访问密钥 ID 和秘密访问密钥)存储在环境变量中。使用 CodeBuild 控制台和 AWS CLI 等工具能够以纯文本格式显示环境变量。对于敏感值,建议改用 parameter-storesecrets-manager 映射,如本节后面所述。

您设置的任何环境变量都将替换现有的环境变量。例如,如果靠泊装置图像已经包含名称为“环境变量”的环境变量 MY_VAR 有一个价值 my_value,并且您设置了名为 MY_VAR 有一个价值 other_value,然后 my_value 替换为 other_value...同样,如果靠泊装置图像已经包含名称的环境变量 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 参数存储。key 您在构建命令后面使用的名称,以指定此自定义环境变量,以及 value 是存储在存储在中的自定义环境变量的名称 Amazon EC2 Systems Manager 参数存储。要存储敏感值,请参阅 系统管理器参数存储巡视: 创建和测试字符串参数(控制台)Amazon EC2 Systems Manager 用户指南.

重要

要允许 CodeBuild 检索存储在 Amazon EC2 Systems Manager Parameter Store 中的自定义环境变量,您必须将 ssm:GetParameters 操作添加到您的 CodeBuild 服务角色。有关更多信息,请参阅 创建 CodeBuild 服务角色。)

从 Amazon EC2 Systems Manager Parameter Store 检索到的任何环境变量都将替换现有环境变量。例如,如果靠泊装置图像已经包含名称为“环境变量”的环境变量 MY_VAR 有一个价值 my_value,并且您检索名为 MY_VAR 有一个价值 other_value,然后 my_value 替换为 other_value...同样,如果靠泊装置图像已经包含名称的环境变量 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

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

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

  • secret-id: 用作密钥的唯一标识符的名称或 Amazon资源名称 (ARN)。要访问您的 AWS 账户中的密钥,只需指定密钥名称。要访问其他 AWS 账户中的密钥,请指定密钥 ARN。

  • json-key: 指定要检索其值的键值对的键名称。如果您不指定 json-key,CodeBuild 会索整个密钥文本。

  • version-stage: 指定要按附加到版本的暂存标签检索的密钥版本。暂存标签用于在轮换过程中跟踪不同版本。如果您使用 version-stage,不要指定 version-id...如果您没有指定版本阶段或版本ID,则默认情况下,将检索版本阶段值的版本 AWSCURRENT.

  • version-id: :指定要使用的密钥版本的唯一标识符。如果您指定 version-id,不要指定 version-stage...如果没有指定版本阶段或版本ID,则默认情况下,将检索awscurrent版本阶段值的版本。

有关更多信息,请参阅 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凭据-助手

可选的映射。用于表明 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 在构建的各个阶段将运行的命令。

注意

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

phases/*/run-as

可选的序列。在构建阶段中使用,以指定运行命令的 Linux 用户。如果还在构建规范文件的顶部为所有命令全局指定了 run-as,则阶段级别用户优先。例如,如果 run-as 全局指定用户 1,并且对于 install 阶段,只有一条 run-as 语句指定用户 2,则构建规范文件中的所有命令将以用户 1 的身份运行,但 install 阶段中的命令除外,这些命令以用户 2 的身份运行。

允许的构建阶段名称是:

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.xjava: 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"

您可以在构建规范文件的 runtime-versions 部分中指定一个或多个运行时。如果您的运行时依赖于另一个运行时,您还可以在构建规范文件中指定其依赖运行时。如果您未在构建规范文件中指定任何运行时,CodeBuild 选择在您使用的映像中提供的默认运行时。如果指定一个或多个运行时,则 CodeBuild 仅使用这些运行时。如果未指定依赖运行时,则 CodeBuild 尝试为您选择依赖运行时。

如果两个指定运行时冲突,构建将失败。例如,android: 29java: openjdk11 冲突,因此,如果同时指定了这两项,构建将失败。

可以指定以下支持的运行时。

Ubuntu 18.04 和 Amazon Linux 2 平台运行时
运行时名称 版本 特定版本 特定主要和最新次要版本 最新版本 映像
android

28.

android: 28

android: 28.x

android: latest

标准:2.0

标准:3.0

所有 Ubuntu 18.04 映像

29.

android: 29

android: 29.x

android: latest

标准:2.0

标准:3.0

所有 Ubuntu 18.04 映像

dotnet

3.0

dotnet: 3.0

dotnet: 3.x

dotnet: latest

标准:2.0

Ubuntu 标准:3.0

3.1

dotnet: 3.1

dotnet: 3.x

dotnet: latest

标准:3.0

Ubuntu 标准:4.0

Golang

1.12

golang: 1.12

golang: 1.x

golang: latest

所有 Ubuntu 18.04 映像

1.13

golang: 1.13

golang: 1.x

golang: latest

所有 Ubuntu 18.04 映像

1.14

golang: 1.14

golang: 1.x

golang: latest

标准:3.0

Ubuntu 标准:4.0

nodejs

8

nodejs: 8

nodejs: 8.x

nodejs: latest

标准:1.0

Ubuntu 标准:2.0

10*

nodejs: 10

nodejs: 10.x

nodejs: latest

所有 Ubuntu 18.04 映像

[12]

nodejs: 12

nodejs: 12.x

nodejs: latest

Ubuntu 标准:3.0

Ubuntu 标准:4.0

java

openjdk8

java: openjdk8

java: openjdk8.x

java: latest

Ubuntu 标准:2.0

Ubuntu 标准:3.0

openjdk11

java: openjdk11

java: openjdk11.x

java: latest

Ubuntu 标准:2.0

Ubuntu 标准:3.0

corretto8

java: corretto8

java: corretto8.x

java: latest

标准:2.0

标准:3.0

Ubuntu 标准:4.0

corretto11

java: corretto11

java: corretto11.x

java: latest

标准:2.0

标准:3.0

Ubuntu 标准:4.0

php

7.3

php: 7.3

php: 7.x

php: latest

所有 Ubuntu 18.04 映像

7.4

php: 7.4

php: 7.x

php: latest

标准:3.0

Ubuntu 标准:4.0

python

3.7

python: 3.7

python: 3.x

python: latest

标准:3.0

aarch64:1.0

Ubuntu 标准:2.0

Ubuntu 标准:4.0

3.8

python: 3.8

python: 3.x

python: latest

标准:2.0

标准:3.0

Ubuntu 标准:3.0

Ubuntu 标准:4.0

ruby

2.6

ruby: 2.6

ruby: 2.x

ruby: latest

所有 Ubuntu 18.04 映像

2.7

ruby: 2.7

ruby: 2.x

ruby: latest

标准:3.0

Ubuntu 标准:4.0

注意

如果您指定 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

commands: 可选的序列。包含一系列标量,其中每个标量表示 CodeBuild 在安装期间运行的单个命令。CodeBuild 按照命令列出的顺序依次运行每个命令。

phases/install/finally

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

phases/pre_build

可选的序列。表示 CodeBuild 在构建之前将运行的命令(如果有)。例如,可以使用此阶段登录 Amazon ECR,也可以安装 npm 依赖项。

phases/pre_build/commands

如果指定 pre_build,则为必需的序列。包含一系列标量,其中每个标量表示 CodeBuild 在构建之前运行的单个命令。CodeBuild 按照命令列出的顺序依次运行每个命令。

phases/pre_build/finally

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

phases/build

可选的序列。表示 CodeBuild 在生成过程中将运行的命令(如果有)。例如,您可以使用此阶段运行 Mocha、RSpec 或 sbt。

phases/build/commands

commands: 要求如果 build 已指定。包含一系列标量,其中每个标量表示 CodeBuild 在构建期间运行的单个命令。CodeBuild 按照命令列出的顺序依次运行每个命令。

phases/build/finally

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

phases/post_build

可选的序列。表示 CodeBuild 在生成后将运行的命令(如果有)。例如,您可以使用 Maven 将构建项目打包成 JAR 或 WAR 文件,还可以将 Docker 映像推入到 Amazon ECR 中。然后,您可以通过 Amazon SNS 发送构建通知。

phases/post_build/commands

commands: 要求如果 post_build 已指定。包含一系列标量,其中每个标量表示 CodeBuild 在构建之后运行的单个运行。CodeBuild 按照命令列出的顺序依次运行每个命令。

phases/post_build/finally

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

重要

如果早期构建阶段中的命令失败,则一些构建阶段中的命令可能无法运行。例如,如果 install 阶段的命令失败,则 pre_buildbuildpost_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.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

NUnit3XML(三元XML)

TESTNGXML

TestNG XML

VISUALSTUDIOTRX

Visual Studio TRX

代码覆盖报告

CLOVERXML

三叶草XML

COBERTURAXML

CoberturaXML(CoberturaXML)

JACOCOXML

JaCoCoXML(JaCoCoXML)

SIMPLECOV

SimpleCovJSON(简单CovJSON)

注意
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.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 控制台创建您的构建,在构建规范文件中指定名称,并在创建或更新项目时选择 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 为开头的所有顶级目录。

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

您可以使用 filesdiscard-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 块具有相同的语法。

注意

TheThethe 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.jarmy-parent-subdirectory/my-subdirectory/my-file.jar)。

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

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

  • my-subdirectory/**/* 从名为的子目录递归地表示所有文件 my-subdirectory.

重要

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

如果您在创建或更新构建项目时使用 AWS CLI 或 AWS 开发工具包声明构建规范,则构建规范必须是以 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 开发工具包一起使用并表示为单个字符串。

"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 并且路径将从包含测试结果的文件中删除。

构建规范版本

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

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

  • plaintext 已重命名为 variables

  • artifactstype 属性已被弃用。

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

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