适用于 CodeBuild 的构建规范参考 - AWS CodeBuild
构建规范文件名称和存储位置构建规范语法构建规范示例构建规范版本
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。

适用于 CodeBuild 的构建规范参考

本主题提供有关构建规范文件的重要参考信息。A buildspec is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build.您可以将构建规范作为源代码的一部分，也可以在创建构建项目时定义构建规范。有关构建规范工作原理的信息，请参阅CodeBuild 的工作原理。

主题

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

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

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

  • 对同一存储库中的不同构建使用不同的构建规范文件，如 buildspec_debug.yml 和 buildspec_release.yml。

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

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

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

  • 运行 AWS CLI create-project 或 update-project 命令，将 buildspec 值设置为备用构建规范文件的路径（相对于内置环境变量 CODEBUILD_SRC_DIR 的值）。 您还可以在 create project AWS 中执行与 SDKs 操作等效的操作。 有关更多信息，请参阅创建构建项目或更改构建项目的设置。

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

  • 在 AWS CloudFormation 模板中，将类型为 BuildSpec 的资源中 Source 的 AWS::CodeBuild::Project 属性设置为备用构建规范文件的路径（相对于内置环境变量 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 操作系统支持的 shell。

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

  • bash

  • /bin/sh

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

  • powershell.exe

  • cmd.exe

env/variables

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

重要

我们强烈建议不要将敏感值(尤其是 AWS 访问密钥 IDs 和秘密访问密钥)存储在环境变量中。使用 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_ 开头的任何环境变量。 此前缀保留供内部使用。

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

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 中的自定义环境变量的名称。要存储敏感值,请参阅 Systems Manager Parameter Store 和演练: 用户指南 中的创建并测试字符串参数(控制台)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

如果要检索存储在 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 下的单独行上指定要导出的每个变量的名称。 在构建期间,要导出的变量必须在容器中可用。导出的变量可以是环境变量。

在构建期间，变量的值从 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 在构建的各个阶段将运行的命令。

注意

在构建规范版本 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: openjdk11、ruby: 2.6、nodejs: 12.x 或 java: 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"

You can specify one or more runtimes in the runtime-versions section of your buildspec file. If your runtime is dependent upon another runtime, you can also specify its dependent runtime in the buildspec file. If you do not specify any runtimes in the buildspec file, CodeBuild chooses the default runtimes that are available in the image you use. If you specify one or more runtimes, CodeBuild uses only those runtimes. If a dependent runtime is not specified, CodeBuild attempts to choose the dependent runtime for you.

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

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

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

28

Amazon Linux 2 标准：2.0

Amazon Linux 2 标准：3.0

Ubuntu 标准：3.0

Ubuntu 标准：4.0

android: 28

android: 28.x

android: latest

29

Amazon Linux 2 标准：2.0

Amazon Linux 2 标准：3.0

Ubuntu 标准：3.0

Ubuntu 标准：4.0

android: 29

android: 29.x
dotnet

3.0

Amazon Linux 2 标准：2.0

Ubuntu 标准：3.0

dotnet: 3.0

dotnet: 3.x

dotnet: latest

3.1

Amazon Linux 2 标准：3.0

Ubuntu 标准：4.0

Ubuntu 标准：5.0

dotnet: 3.1
5.0 Ubuntu 标准：5.0

dotnet: 5.0

dotnet: 5.x
Golang

1.12

所有支持的 Amazon Linux 2 映像

Ubuntu 标准：3.0

Ubuntu 标准：4.0

golang: 1.12

golang: 1.x

golang: latest

1.13

所有支持的 Amazon Linux 2 映像

Ubuntu 标准：3.0

Ubuntu 标准：4.0

golang: 1.13

1.14

Amazon Linux 2 标准：3.0

Ubuntu 标准：4.0

golang: 1.14
1.15

Ubuntu 标准：5.0

golang: 1.15
nodejs

10

所有支持的 Amazon Linux 2 映像

Ubuntu 标准：3.0

Ubuntu 标准：4.0

nodejs: 10

nodejs: 10.x

nodejs: latest

12

所有支持的 Amazon Linux 2 映像

所有 Ubuntu 映像

nodejs: 12

nodejs: 12.x
14

Ubuntu 标准：5.0

nodejs: 14

nodejs: 14.x
java

openjdk8

Ubuntu 标准：3.0

java: openjdk8

java: openjdk8.x

java: latest

openjdk11

Ubuntu 标准：3.0

java: openjdk11

java: openjdk11.x

corretto8

Amazon Linux 2 标准：2.0

Amazon Linux 2 标准：3.0

Ubuntu 标准：4.0

Ubuntu 标准：5.0

java: corretto8

java: corretto8.x

corretto11

Amazon Linux 2 标准：2.0

Amazon Linux 2 标准：3.0

Ubuntu 标准：4.0

Ubuntu 标准：5.0

java: corretto11

java: corretto11.x
php

7.3

所有支持的 Amazon Linux 2 映像

所有 Ubuntu 映像

php: 7.3

php: 7.x

php: latest

7.4

Amazon Linux 2 标准：3.0

Ubuntu 标准：4.0

Ubuntu 标准：5.0

php: 7.4
8.0

Ubuntu 标准：5.0

php: 8.0

php: 8.x
python

3.7

Amazon Linux 2 标准：3.0

Amazon Linux 2 aarch64：1.0

Ubuntu 标准：4.0

Ubuntu 标准：5.0

python: 3.7

python: 3.x

python: latest

3.8

Amazon Linux 2 标准：2.0

Amazon Linux 2 标准：3.0

所有 Ubuntu 映像

python: 3.8
3.9

Ubuntu 标准：5.0

python: 3.9
ruby

2.6

所有支持的 Amazon Linux 2 映像

所有 Ubuntu 映像

ruby: 2.6

ruby: 2.x

ruby: latest

2.7

Amazon Linux 2 标准：3.0

Ubuntu 标准：4.0

Ubuntu 标准：5.0

ruby: 2.7
注意

If you specify a runtime-versions section and use an image other than Ubuntu Standard Image 2.0 or later, or the Amazon Linux 2 (AL2) standard image 1.0 or later, the build issues the warning, "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 块中的命令之后运行。即使 finally 数据块中的命令失败,commands 数据块中的命令也会运行。例如，如果 commands 语句块包含三条命令，而第一条命令失败了，则 CodeBuild 会跳过剩下的两条命令来运行 finally 语句块中的任何命令。当 commands 和 finally 语句块中的所有命令都成功运行后，此阶段才算成功。如果某个阶段有任何命令失败，则该阶段失败。

phases/pre_build

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

phases/pre_build/commands

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

phases/pre_build/finally

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

phases/build

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

phases/build/commands

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

phases/build/finally

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

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 块中的命令之后运行。即使 finally 数据块中的命令失败,commands 数据块中的命令也会运行。例如，如果 commands 语句块包含三条命令，而第一条命令失败了，则 CodeBuild 会跳过剩下的两条命令来运行 finally 语句块中的任何命令。当 commands 和 finally 语句块中的所有命令都成功运行后，此阶段才算成功。如果某个阶段有任何命令失败，则该阶段失败。

重要

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

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，或者正在运行源代码上的单元测试，但并未构建源代码。

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

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

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

注意

即使仅定义了辅助构件，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.jar 或 my-parent-subdirectory/my-subdirectory/my-file.jar)。

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

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

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

重要

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

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

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

构建规范版本

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

Version 更改
0.2

  • environment_variables 已重命名为 env。

  • plaintext 已重命名为 variables。

  • artifacts 的 type 属性已被弃用。

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

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