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

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

构建 CodeBuild 的规范参考

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

主题

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

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

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

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

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

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

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

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

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

  • 在 Amazon CloudFormation 模板中，将类型为 AWS::CodeBuild::Project 的资源中 Source 的 BuildSpec 属性设置为备用构建规范文件的路径（相对于内置环境变量 CODEBUILD_SRC_DIR 的值）。有关更多信息，请参阅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 日志中隐藏以下内容：

env/Shell

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

对于 Linux 操作系统，支持的外壳标签包括：

  • bash

  • /bin/sh

对于 Windows 操作系统，支持的外壳标记包括：

  • powershell.exe

  • cmd.exe

env/variables

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

重要

强烈建议不要将敏感值（尤其是 Amazon 访问密钥 ID 和秘密访问密钥）存储在环境变量中。使用 CodeBuild der 控制台和Amazon 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 中的自定义环境变量。包含密钥/值标量，其中各个映射表示一个存储在 Amazon EC2 Systems Manager Parameter Store 中的自定义环境变量。密钥是您之后在构建命令中用于表示此自定义环境变量的名称，而值是存储在 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

如果您要检索存储在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>

（可选）指定要检索其值的密钥管理器键值对的键名称。如果您不指定json-key，CodeBuild Store 会检索整个密钥文本。

<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-凭证助手

可选的映射。用于指示 CodeBuild der 是否使用其 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。

注意

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

phases/*/run-as

可选的序列。在构建阶段中使用，以指定运行命令的 Linux 用户。如果还在构建规范文件的顶部为所有命令全局指定了 run-as，则阶段级别用户优先。例如，如果全局run-as指定用户 1，对于install仅阶段 arun-as语句指定 User-2，然后构建规范文件中的所有命令都以 User1 的形式运行但命令install阶段，它们以用户 2 的形式运行。

phases/*/故障时

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

  • ABORT-中止构建。

  • CONTINUE-继续下一个阶段。

如果未指定此属性，则失败过程遵循转换阶段，如构建阶段过渡。

phases/*/finally

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

允许的构建阶段名称是：

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 提供的码头映像。 

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

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

如果两个指定运行时冲突，构建将失败。例如，android: 29 和 java: 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>。有关更多信息，请参阅报告组命名。

reports/<report-group>/files

必需的序列。表示由报告生成的测试结果的原始数据所在的位置。包含一系列标量，其中各个标量表示一个相对于原始构建位置或（如果已设置）的单独位置，CodeBuilder 可在此处查找测试文件。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

Nit 3 XML XML XML

TESTNGXML

TestNG XML

VISUALSTUDIOTRX

Visual Studio TRX

代码覆盖率报告

CLOVERXML

XML 三叶草

COBERTURAXML

科伯图拉 XML XML

JACOCOXML

JaCoCo XML XML

SIMPLECOV

SimpleCov JSON

注意

CodeBuild 接受 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 来创建您的构建，并使用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 为开头的所有顶级目录。

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

您可以使用 files 和 discard-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

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。

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

如果您使用 CodeBuild 或Amazon CodePipeline控制台而不是构建规范 .yml 文件，则可以插入build仅阶段。不要使用前一语法，改为单行列出要在构建阶段运行的所有命令。对于多个命令，使用 && 分开各个命令 (例如 mvn test && mvn package)。

您可以使用 CodeBuild dspec.yCodePipeline 控制台而不是 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 -y和apt-get install -y maven（安装阿帕奇 Maven），mvn install（用于编译、测试源代码并将其打包为生成输出项目，并在其内部存储库中安装生成输出项目），docker login（使用与自定义环境变量的值对应的密码登录 DockerdockerLoginPassword），以及几个echo命令。这些区域有：echo命令来显示 CodeBuild der 如何运行命令以及运行命令的顺序。

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

构建规范版本

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

版本 更改
0.2

  • environment_variables 已重命名为 env。

  • plaintext 已重命名为 variables。

  • artifacts 的 type 属性已被弃用。

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

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