的构建规范参考 CodeBuild - AWS CodeBuild
buildspec 文件名称和存储位置buildspec 语法buildspec 示例buildspec 版本

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

的构建规范参考 CodeBuild

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

主题

buildspec 文件名称和存储位置

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

可以覆盖默认 buildspec 文件名和位置。例如，您可以：

  • 对同一存储库中的不同构建使用不同的 buildspec 文件，如 buildspec_debug.yml 和 buildspec_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-project或update-project命令，将buildspec值设置为相对于内置环境变量CODEBUILD_SRC_DIR值的备用 buildspec 文件的路径。您也可以使用 AWS 软件开发工具包中的create project操作执行等效操作。有关更多信息，请参阅创建构建项目或更改构建项目的设置。

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

  • 在 AWS CloudFormation 模板中，将资源类型SourceAWS::CodeBuild::Project中的BuildSpec属性设置为相对于内置环境变量CODEBUILD_SRC_DIR值的备用 buildspec 文件的路径。有关更多信息，请参阅《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
    # steps:
  pre_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
  build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
  post_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
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-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 中的自定义环境变量的名称。要存储敏感值，请参阅《Amazon EC2 Systems Manager 用户指南》中的 Systems Manager Parameter Store 和演练：创建和测试参数（控制台）。

重要

CodeBuild 要允许检索存储在 Amazon EC2 Systems Manager 参数存储中的自定义环境变量，您必须将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 下的单独行上指定要导出的每个变量的名称。在构建过程中，要导出的变量必须在容器中可用。导出的变量可以是环境变量。

导出的环境变量与结合使用，用于 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

可选的映射。将设置为，yes以便在显式代理服务器中进行构建，以创建 CloudWatch 日志。默认值为 no。

phases

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

注意

在 buildspec 版本 0.1 中，在构建环境中默认外壳的单独实例中 CodeBuild 运行每个命令。这表示各个命令独立于其他所有命令而运行。因此，在默认情况下，您无法运行依赖所有上一个命令状态的单个命令（如更改目录或设置环境变量）。要绕开此限制，建议使用版本 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块中的任何命令。当 commands 和 finally 语句块中的所有命令都成功运行后，此阶段才算成功。如果某个阶段有任何命令失败，则该阶段失败。

允许的构建阶段名称是：

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.x、或java: latest）。您可以使用一个数字或一个环境变量来指定运行时。例如，如果您使用 Amazon Linux 2 标准映像 4.0，则下面指定安装版本 17 的 Java、python 版本 3 的最新次要版本以及 Ruby 的环境变量中包含的版本。有关更多信息，请参阅 提供的 Docker 镜像 CodeBuild。

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

您可以在 buildspec 文件的 runtime-versions 部分中指定一个或多个运行时。如果您的运行时依赖于另一个运行时，您还可以在 buildspec 文件中指定其依赖运行时。如果您未在 buildspec 文件中指定任何运行时，请 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>。也可以使用 buildspec 中的环境变量来设置报告组名称，例如$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

Clover XML

COBERTURAXML

Cobertura XML

JACOCOXML

JaCoCo XML

SIMPLECOV

SimpleCov json

注意

CodeBuild 接受 simplecov 生成的 JSON 代码覆盖率报告，而不是 s implecov-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 元数据有一个名为buildArn的 CodeBuild 标头，x-amz-meta-codebuild-buildarn其中包含将 CodeBuild 构件发布到 Amazon S3 的版本。添加 buildArn 是为了允许对通知进行源跟踪并引用生成构件的构建。

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 控制台创建构建，在 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 为开头的所有顶级目录。

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

您可以使用 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
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.jar 或 my-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 SDK 声明构建规范，则 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 软件开发工具包。 AWS CLI

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

buildspec 版本

下表列出了 buildspec 版本以及版本间的变化。

版本 更改
0.2

  • environment_variables 已重命名为 env。

  • plaintext 已重命名为 variables。

  • artifacts 的 type 属性已被弃用。

  • 在 0.1 版中，在编译环境中使用默认 shell 的单独实例 AWS CodeBuild 运行每个构建命令。在 0.2 版中，在编译环境中使用同一个默认 shell 实例 CodeBuild 运行所有构建命令。
0.1 这是 buildspec 格式的初始定义。