本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 在 中创建构建项目AWS CodeBuild 您可以使用 AWS CodeBuild 控制台、AWS CLI 或 AWS 开发工具包创建构建项目。 **Topics** + [先决条件](#create-project-prerequisites) + [创建构建项目（控制台）](#create-project-console) + [创建构建项目 (AWS CLI)](#create-project-cli) + [创建构建项目（AWS 开发工具包）](#create-project-sdks) + [创建构建项目 (CloudFormation)](#create-project-cloud-formation) ## 先决条件 在创建构建项目之前，请回答[计划构建](planning.md)中的问题。 ## 创建构建项目（控制台） 从 [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 打开 AWS CodeBuild 控制台。 如果显示了 CodeBuild 信息页面，请选择**创建构建项目**。否则，请在导航窗格中，展开**构建**，选择**构建项目**，然后选择**创建构建项目**。 选择**创建构建项目**。 填写以下部分：完成后，选择页面底部的**创建构建项目**。 **Topics** + [项目配置](#create-project-console-project-config) + [来源](#create-project-console-source) + [环境](#create-project-console-environment) + [BuildSpec](#create-project-console-buildspec) + [批量配置](#create-project-console-batch-config) + [构件](#create-project-console-artifacts) + [日志](#create-project-console-logs) ### 项目配置 **项目名称**： 输入此构建项目的名称。构建项目名称在您的各个 AWS 账户内必须是唯一的。 **描述** 输入构建项目的可选描述，以帮助其他用户了解此项目的用途。 **构建徽章** （可选）选择**启用构建徽章**，以使您的项目的构建状态可见且可嵌入。有关更多信息，请参阅 [构建徽章示例](sample-build-badges.md)。 如果您的源提供商是 Amazon S3，则构建徽章不适用。 **启用并发构建限制** （可选）如果要限制此项目的并发构建数量，请执行以下步骤： 1. 选择**限制此项目可以启动的并发构建数量**。 1. 在**并发构建限制**中，输入此项目允许的并发构建的最大数量。此限制不得大于为该账户设置的并发构建限制。如果您尝试输入大于账户限制的数字，则会显示错误消息。 仅当当前构建数量小于或等于此限值时，才会启动新构建。如果当前构建计数达到此限值，则新构建将受到限制且不会运行。 **其他信息**： （可选）对于**标签**，输入您希望支持 AWS 服务使用的任何标签的名称和值。使用**添加行**添加标签。最多可以添加 50 个标签。 ### 来源 **源提供商** 选择源代码提供商类型。使用以下列表为您的源提供商选择适当的选项： CodeBuild 不支持 Bitbucket 服务器。 ------ #### [ Amazon S3 ] **存储桶** 选择包含源代码的输入存储桶的名称。 **S3 对象密钥或 S3 文件夹** 输入 ZIP 文件的名称或包含源代码的文件夹的路径。输入正斜杠 (/) 以下载 S3 存储桶中的所有内容。 **源版本** 输入表示输入文件版本的对象的版本 ID。有关更多信息，请参阅 [源版本示例 AWS CodeBuild](sample-source-version.md)。 ------ #### [ CodeCommit ] **存储库** 选择要使用的存储库。 **参考类型** 选择**分支**、**Git 标签**或**提交 ID**，以指定源代码的版本。有关更多信息，请参阅 [源版本示例 AWS CodeBuild](sample-source-version.md)。 我们建议您选择看起来不像提交 ID 的 Git 分支名称，例如 `811dd1ba1aba14473856cee38308caed7190c0d` 或 `5392f7`。这可以帮助您避免 Git 签出与实际提交发生冲突。 **Git 克隆深度** 选择该选项，以创建一个浅克隆，其历史记录会截断至指定数量的提交。如果您需要完整克隆，请选择**完整**。 **Git 子模块** 如果您希望在存储库中包含 Git 子模块，请选择**使用 Git 子模块**。 ------ #### [ Bitbucket ] **凭证** 选择**默认来源凭证**或**自定义来源凭证**，然后按照说明管理默认来源凭证或自定义源凭证。 **连接类型** 选择 **CodeConnections**、**OAuth**、**应用程序密码**或**个人访问令牌**以连接到 CodeBuild。 **Connection** 选择 Bitbucket 连接或 Secrets Manager 密钥，通过指定的连接类型进行连接。 **存储库** 选择**我的 Bitbucket 账户中的存储库**或**公共存储库**，然后输入存储库 URL。 **源版本** 输入分支、提交 ID、标签，或引用以及提交 ID。有关更多信息，请参阅 [源版本示例 AWS CodeBuild](sample-source-version.md)。 我们建议您选择看起来不像提交 ID 的 Git 分支名称，例如 `811dd1ba1aba14473856cee38308caed7190c0d` 或 `5392f7`。这可以帮助您避免 Git 签出与实际提交发生冲突。 **Git 克隆深度** 选择**Git 克隆深度**以创建一个浅克隆，其历史记录会截断至指定数量的提交。如果您需要完整克隆，请选择**完整**。 **Git 子模块** 如果您希望在存储库中包含 Git 子模块，请选择**使用 Git 子模块**。 **构建状态** 如果您希望向源提供商报告构建的开始和完成状态，请选择**在您的构建开始和完成时向源提供商报告构建状态**。 为了能够向源提供商报告构建状态，与源提供商关联的用户必须拥有对存储库的写入权限。如果用户没有写入权限，则无法更新构建状态。有关更多信息，请参阅[源提供商访问权限](access-tokens.md)。 在**状态上下文**中，输入要在 Bitbucket 提交状态中用于 `name` 参数的值。有关更多信息，请参阅 Bitbucket API 文档中的[构建](https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Bworkspace%7D/%7Brepo_slug%7D/commit/%7Bnode%7D/statuses/build)。 在**目标 URL** 中，输入要在 Bitbucket 提交状态中用于 `url` 参数的值。有关更多信息，请参阅 Bitbucket API 文档中的[构建](https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Bworkspace%7D/%7Brepo_slug%7D/commit/%7Bnode%7D/statuses/build)。 由 Webhook 触发的构建的状态将始终报告给源提供商。要将从控制台或 API 调用启动的构建状态报告给源提供商，您必须选择此设置。 如果项目的构建通过 webhook 触发，则必须将新的提交推送到存储库，此设置才能生效。 如果您希望每次将代码更改推送到该存储库时 CodeBuild 都构建源代码，请在**主要源 Webhook 事件**中选择**每次将代码更改推送到此存储库时都会重新生成**。有关 webhook 和筛选条件组的更多信息，请参阅 [Bitbucket Webhook 事件](bitbucket-webhook.md)。 ------ #### [ GitHub ] **凭证** 选择**默认来源凭证**或**自定义来源凭证**，然后按照说明管理默认来源凭证或自定义源凭证。 **连接类型** 选择 **GitHub 应用程序**、**OAuth** 或**个人访问令牌**以连接到 CodeBuild。 **Connection** 选择 GitHub 连接或 Secrets Manager 密钥，通过指定的连接类型进行连接。 **存储库** 选择**我的 GitHub 账户中的存储库**、**公共存储库**或 **GitHub 范围内的 webhook**，然后输入存储库 URL。 **源版本** 输入分支、提交 ID、标签，或引用以及提交 ID。有关更多信息，请参阅 [源版本示例 AWS CodeBuild](sample-source-version.md)。 我们建议您选择看起来不像提交 ID 的 Git 分支名称，例如 `811dd1ba1aba14473856cee38308caed7190c0d` 或 `5392f7`。这可以帮助您避免 Git 签出与实际提交发生冲突。 **Git 克隆深度** 选择**Git 克隆深度**以创建一个浅克隆，其历史记录会截断至指定数量的提交。如果您需要完整克隆，请选择**完整**。 **Git 子模块** 如果您希望在存储库中包含 Git 子模块，请选择**使用 Git 子模块**。 **构建状态** 如果您希望向源提供商报告构建的开始和完成状态，请选择**在您的构建开始和完成时向源提供商报告构建状态**。 为了能够向源提供商报告构建状态，与源提供商关联的用户必须拥有对存储库的写入权限。如果用户没有写入权限，则无法更新构建状态。有关更多信息，请参阅 [源提供商访问权限](access-tokens.md)。 在**状态上下文**中，输入要在 GitHub 提交状态中用于 `context` 参数的值。有关更多信息，请参阅《GitHub 开发人员指南》中的[创建提交状态](https://developer.github.com/v3/repos/statuses/#create-a-commit-status)。 在**目标 URL** 中，输入要在 GitHub 提交状态中用于 `target_url` 参数的值。有关更多信息，请参阅《GitHub 开发人员指南》中的[创建提交状态](https://developer.github.com/v3/repos/statuses/#create-a-commit-status)。 由 Webhook 触发的构建的状态将始终报告给源提供商。要将从控制台或 API 调用启动的构建状态报告给源提供商，您必须选择此设置。 如果项目的构建通过 webhook 触发，则必须将新的提交推送到存储库，此设置才能生效。 如果您希望每次将代码更改推送到该存储库时 CodeBuild 都构建源代码，请在**主要源 Webhook 事件**中选择**每次将代码更改推送到此存储库时都会重新生成**。有关 webhook 和筛选条件组的更多信息，请参阅 [GitHub webhook 事件](github-webhook.md)。 ------ #### [ GitHub Enterprise Server ] **凭证** 选择**默认来源凭证**或**自定义来源凭证**，然后按照说明管理默认来源凭证或自定义源凭证。 **连接类型** 选择 **CodeConnections** 或**个人访问令牌**以连接到 CodeBuild。 **Connection** 选择 GitHub Enterprise 连接或 Secrets Manager 密钥，通过指定的连接类型进行连接。 **存储库** 选择**我的 GitHub Enterprise 账户中的存储库**或 **GitHub Enterprise 范围内的 webhook**，然后输入存储库 URL。 **源版本** 输入拉取请求、分支、提交 ID、标签，或引用以及提交 ID。有关更多信息，请参阅 [源版本示例 AWS CodeBuild](sample-source-version.md)。 我们建议您选择看起来不像提交 ID 的 Git 分支名称，例如 `811dd1ba1aba14473856cee38308caed7190c0d` 或 `5392f7`。这可以帮助您避免 Git 签出与实际提交发生冲突。 **Git 克隆深度** 选择**Git 克隆深度**以创建一个浅克隆，其历史记录会截断至指定数量的提交。如果您需要完整克隆，请选择**完整**。 **Git 子模块** 如果您希望在存储库中包含 Git 子模块，请选择**使用 Git 子模块**。 **构建状态** 如果您希望向源提供商报告构建的开始和完成状态，请选择**在您的构建开始和完成时向源提供商报告构建状态**。 为了能够向源提供商报告构建状态，与源提供商关联的用户必须拥有对存储库的写入权限。如果用户没有写入权限，则无法更新构建状态。有关更多信息，请参阅 [源提供商访问权限](access-tokens.md)。 在**状态上下文**中，输入要在 GitHub 提交状态中用于 `context` 参数的值。有关更多信息，请参阅《GitHub 开发人员指南》中的[创建提交状态](https://developer.github.com/v3/repos/statuses/#create-a-commit-status)。 在**目标 URL** 中，输入要在 GitHub 提交状态中用于 `target_url` 参数的值。有关更多信息，请参阅《GitHub 开发人员指南》中的[创建提交状态](https://developer.github.com/v3/repos/statuses/#create-a-commit-status)。 由 Webhook 触发的构建的状态将始终报告给源提供商。要将从控制台或 API 调用启动的构建状态报告给源提供商，您必须选择此设置。 如果项目的构建通过 webhook 触发，则必须将新的提交推送到存储库，此设置才能生效。 **不安全的 SSL** 选择**启用不安全的 SSL**，在连接到您的 GitHub Enterprise 项目存储库时忽略 SSL 警告。 如果您希望每次将代码更改推送到该存储库时 CodeBuild 都构建源代码，请在**主要源 Webhook 事件**中选择**每次将代码更改推送到此存储库时都会重新生成**。有关 webhook 和筛选条件组的更多信息，请参阅 [GitHub webhook 事件](github-webhook.md)。 ------ #### [ GitLab ] **凭证** 选择**默认来源凭证**或**自定义来源凭证**，然后按照说明管理默认来源凭证或自定义源凭证。 **连接类型** **CodeConnections** 用于将 GitLab 连接到 CodeBuild。 **Connection** 选择要通过 CodeConnections 进行连接的 GitLab 连接。 **存储库** 选择要使用的存储库。 **源版本** 输入拉取请求 ID、分支、提交 ID、标签，或引用以及提交 ID。有关更多信息，请参阅 [源版本示例 AWS CodeBuild](sample-source-version.md)。 我们建议您选择看起来不像提交 ID 的 Git 分支名称，例如 `811dd1ba1aba14473856cee38308caed7190c0d` 或 `5392f7`。这可以帮助您避免 Git 签出与实际提交发生冲突。 **Git 克隆深度** 选择**Git 克隆深度**以创建一个浅克隆，其历史记录会截断至指定数量的提交。如果您需要完整克隆，请选择**完整**。 **构建状态** 如果您希望向源提供商报告构建的开始和完成状态，请选择**在您的构建开始和完成时向源提供商报告构建状态**。 为了能够向源提供商报告构建状态，与源提供商关联的用户必须拥有对存储库的写入权限。如果用户没有写入权限，则无法更新构建状态。有关更多信息，请参阅 [源提供商访问权限](access-tokens.md)。 ------ #### [ GitLab Self Managed ] **凭证** 选择**默认来源凭证**或**自定义来源凭证**，然后按照说明管理默认来源凭证或自定义源凭证。 **连接类型** **CodeConnections** 用于将 GitLab 自行管理连接到 CodeBuild。 **Connection** 选择要通过 CodeConnections 进行连接的 GitLab 自行管理连接。 **存储库** 选择要使用的存储库。 **源版本** 输入拉取请求 ID、分支、提交 ID、标签，或引用以及提交 ID。有关更多信息，请参阅 [源版本示例 AWS CodeBuild](sample-source-version.md)。 我们建议您选择看起来不像提交 ID 的 Git 分支名称，例如 `811dd1ba1aba14473856cee38308caed7190c0d` 或 `5392f7`。这可以帮助您避免 Git 签出与实际提交发生冲突。 **Git 克隆深度** 选择**Git 克隆深度**以创建一个浅克隆，其历史记录会截断至指定数量的提交。如果您需要完整克隆，请选择**完整**。 **构建状态** 如果您希望向源提供商报告构建的开始和完成状态，请选择**在您的构建开始和完成时向源提供商报告构建状态**。 为了能够向源提供商报告构建状态，与源提供商关联的用户必须拥有对存储库的写入权限。如果用户没有写入权限，则无法更新构建状态。有关更多信息，请参阅 [源提供商访问权限](access-tokens.md)。 ------ ### 环境 **预置模型** 请执行以下操作之一： + 要使用由 AWS CodeBuild 管理的按需实例集，请选择**按需**。通过按需实例集，CodeBuild 可为您的构建提供计算能力。构建完成后，计算机就会被销毁。按需实例集是完全托管式的，并包括自动扩展功能以应对需求激增。 + 要使用由 AWS CodeBuild 管理的预留容量实例集，请选择**预留容量**，然后选择**实例集名称**。使用预留容量实例集，您可以为构建环境配置一组专用实例。这些计算机保持闲置状态，可以立即处理生成或测试，并缩短构建持续时间。使用预留容量实例集，您的计算机将始终处于运行状态，并且只要预调配完毕，它们就会继续产生成本。 有关信息，请参阅[在预留容量实例集上运行构建](fleets.md)。 **环境映像** 请执行以下操作之一： + 要使用由 AWS CodeBuild 托管的 Docker 映像，请选择**托管映像**，然后从**操作系统**、**运行时**和**映像**以及**映像版本**中进行相应选择。从**环境类型**中进行选择（如果可用）。 + 要使用其他 Docker 映像，请选择**自定义映像**。对于**环境类型**，请选择 **ARM**、**Linux**、**Linux GPU** 或 **Windows**。如果您针对**外部注册表 URL** 选择**其他注册表**，请使用 `docker repository/docker image name` 格式在 Docker Hub 中输入 Docker 映像的名称和标签。如果您选择 **Amazon ECR**，请使用 **Amazon ECR 存储库**和 **Amazon ECR 映像**在您的 AWS 账户中选择 Docker 映像。 + 要使用私有 Docker 映像，请选择**自定义映像**。对于**环境类型**，请选择 **ARM**、**Linux**、**Linux GPU** 或 **Windows**。对于**映像注册表**，选择**其他注册表**，然后输入您的私有 Docker 映像的凭证的 ARN。凭证必须由 Secrets Manager 创建。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[什么是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/)。 CodeBuild 会覆盖自定义 Docker 映像的 `ENTRYPOINT`。 **计算** 请执行以下操作之一： + 要使用 EC2 计算，请选择 **EC2**。EC2 计算在操作运行期间提供了优化的灵活性。 + 要使用 Lambda 计算，请选择 **Lambda**。Lambda 计算为构建提供优化的启动速度。由于启动延迟较短，Lambda 支持更快的构建。Lambda 还会自动扩展，因此构建无需在队列中等待运行。有关信息，请参阅[在 AWS Lambda 计算基础上运行构建](lambda.md)。 **服务角色** 请执行以下操作之一： + 如果您没有 CodeBuild 服务角色，请选择**新建服务角色**。在**角色名称**中，为新角色输入名称。 + 如果您拥有 CodeBuild 服务角色，请选择**现有服务角色**。在**角色 ARN** 中，选择服务角色。 当您使用控制台来创建构建项目时，您可以同时创建 CodeBuild 服务角色。默认情况下，这个角色仅能与该构建项目配合使用。如果您使用控制台将此服务角色与另一个构建项目关联，则此角色将更新以便与关联的构建项目结合使用。一个服务角色最多可与 10 个构建项目结合使用。 **其他配置** **自动重试限制** 指定构建失败后额外的自动重试次数。例如，如果自动重试限制设置为 2，则 CodeBuild 将调用 `RetryBuild` API 来自动重试您的构建，最多再重试 2 次。 **超时** 请指定 5 分钟到 36 小时之间的一个值，在此时间后，如果构建未完成，CodeBuild 会将其停止。如果**小时**和**分钟**都留空，则将使用 60 分钟的默认值。 **特权** （可选）仅当您打算使用此构建项目来构建 Docker 映像时，才应选择**如果要构建 Docker 映像或希望您的构建获得提升的特权，请启用此标志**。否则，尝试与 Docker 守护程序交互的所有关联的构建都将失败。您还必须启动 Docker 守护程序，以便您的构建与其交互。执行此操作的一种方法是通过运行以下构建命令在您的构建规范的 `install` 阶段初始化 Docker 守护程序。如果您选择了由具有 Docker 支持的 CodeBuild 提供的构建环境映像，请不要运行这些命令。 默认情况下，为非 VPC 构建启用 Docker 进程守护程序。如果您想使用 Docker 容器进行 VPC 构建，请参阅 Docker 文档网站上的[运行时权限和 Linux 功能](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)并启用特权模式。此外，Windows 不支持特权模式。 ``` - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & - timeout 15 sh -c "until docker info; do echo .; sleep 1; done" ``` **VPC** 如果要将 CodeBuild 与您的 VPC 结合使用： + 对于 **VPC**，请选择 CodeBuild 使用的 VPC ID。 + 对于 **VPC 子网**，请选择包含 CodeBuild 使用的资源的子网。 + 对于 **VPC 安全组**，请选择 CodeBuild 用来支持对 VPC 中资源的访问的安全组。 有关更多信息，请参阅 [AWS CodeBuild 与亚马逊 Virtual Private Cloud 一起使用](vpc-support.md)。 **计算** 请选择可用选项之一。 **注册表凭证** 使用非私有注册表映像配置项目时，请指定注册表凭证。 仅当映像被私有注册表中的映像覆盖时，才会使用此凭证。 **环境变量**： 请输入每个环境变量的名称和值，然后选择类型，以供构建使用。 CodeBuild 会自动为您的 AWS 区域设置环境变量。如果您尚未将以下环境变量添加到 buildspec.yml 中，则必须设置这些变量： + AWS\$1ACCOUNT\$1ID + IMAGE\$1REPO\$1NAME + IMAGE\$1TAG 控制台和 AWS CLI 用户可以查看环境变量。如果您不担心环境变量的可见性，请设置**名称**和**值**字段，然后将**类型**设置为**明文**。 我们建议您将具有敏感值（例如 AWS 访问密钥 ID、AWS 秘密访问密钥或密码）的环境变量作为参数存储在 Amazon EC2 Systems Manager Parameter Store 或 AWS Secrets Manager 中。 如果您使用的是 Amazon EC2 Systems Manager Parameter Store，则对于**类型**，请选择**参数**。对于**名称**，请输入标识符供 CodeBuild 引用。对于**值**，请按照 Amazon EC2 Systems Manager Parameter Store 中存储的参数名称输入参数名称。使用名为 `/CodeBuild/dockerLoginPassword` 的参数作为示例，对于**类型**，选择**参数**。对于**名称**，请输入 `LOGIN_PASSWORD`。对于**值**，请输入 `/CodeBuild/dockerLoginPassword`。 如果您使用 Amazon EC2 Systems Manager Parameter Store，我们建议您使用以 `/CodeBuild/` 开头的参数名称（例如，`/CodeBuild/dockerLoginPassword`）来存储参数。您可以使用 CodeBuild 控制台在 Amazon EC2 Systems Manager 中创建参数。选择**创建参数**，然后按照对话框中的说明操作。（在该对话框中，对于 **KMS 密钥**，您可以指定您账户中的 AWS KMS 密钥的 ARN。Amazon EC2 Systems Manager 使用此密钥在存储过程中加密参数的值并在检索过程中解密参数的值。） 如果您使用 CodeBuild 控制台创建参数，控制台将在参数名称被存储时以 `/CodeBuild/` 作为它的开头。有关更多信息，请参阅《Amazon EC2 Systems Manager 用户指南》**中的 [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) 和 [Systems Manager Parameter Store 控制台演练](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-walk.html#sysman-paramstore-console)。 如果您的构建项目引用了 Amazon EC2 Systems Manager Parameter Store 中存储的参数，则构建项目的服务角色必须允许 `ssm:GetParameters` 操作。如果您之前选择了**新建服务角色**，CodeBuild 将在您的构建项目的默认服务角色中包含此操作。但是，如果您选择了**现有服务角色**，必须单独将此操作添加到您的服务角色中。 如果您的构建项目引用了 Amazon EC2 Systems Manager Parameter Store 中存储的但参数名称不以 `/CodeBuild/` 开头的参数，且您选择了**新建服务角色**，您必须更新该服务角色以允许访问不以 `/CodeBuild/` 开头的参数名称。这是因为该服务角色仅允许访问以 `/CodeBuild/` 开头的参数名称。 如果您选择**新建服务角色**，服务角色将拥有解密 Amazon EC2 Systems Manager Parameter Store 中 `/CodeBuild/` 命名空间下的所有参数的权限。 您设置的环境变量将替换现有的环境变量。例如，如果 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_` 打头的名称设置任何环境变量。此前缀是专为内部使用预留的。 如果具有相同名称的环境变量在多处都有定义，则应按照如下方式确定其值： + 构建操作调用开始时的值优先级最高。 + 构建项目定义中的值优先级次之。 + buildspec 声明中的值优先级最低。 如果您使用 Secrets Manager，对于**类型**，请选择 **Secrets Manager**。对于**名称**，请输入标识符供 CodeBuild 引用。对于**值**，请使用模式 `secret-id:json-key:version-stage:version-id` 输入 `reference-key`。有关信息，请参阅 [Secrets Manager reference-key in the buildspec file](build-spec-ref.md#secrets-manager-build-spec)。 如果您使用 Secrets Manager，我们建议您存储名称以 `/CodeBuild/`（例如 `/CodeBuild/dockerLoginPassword`）开头的密钥。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[什么是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。 如果您的构建项目引用了 Secrets Manager 中存储的密钥，则构建项目的服务角色必须允许 `secretsmanager:GetSecretValue` 操作。如果您之前选择了**新建服务角色**，CodeBuild 将在您的构建项目的默认服务角色中包含此操作。但是，如果您选择了**现有服务角色**，必须单独将此操作添加到您的服务角色中。 如果您的构建项目引用了 Secrets Manager 中存储的但密钥名称不以 `/CodeBuild/` 开头的密钥，且您选择了**新建服务角色**，您必须更新该服务角色以允许访问不以 `/CodeBuild/` 开头的密钥名称。这是因为该服务角色仅允许访问以 `/CodeBuild/` 开头的密钥名称。 如果您选择**新建服务角色**，该服务角色将拥有解密 Secrets Manager 中 `/CodeBuild/` 命名空间下的所有密钥的权限。 ### BuildSpec **构建规范** 请执行以下操作之一： + 如果您的源代码包含 buildspec 文件，请选择**使用 buildspec 文件**。默认情况下，CodeBuild 在源代码根目录中查找名为 `buildspec.yml` 的文件。如果您的 buildspec 文件使用其他名称或位置，请在 **Buildspec 名称**中输入其从源根目录开始的路径（例如，`buildspec-two.yml` 或 `configuration/buildspec.yml`。如果 buildspec 文件位于 S3 存储桶中，则该存储桶必须位于您的构建项目所在的同一 AWS 区域中。使用 ARN（例如 `arn:aws:s3:::/buildspec.yml`）指定该 buildspec 文件。 + 如果您的源代码不包括 buildspec 文件，或者如果您要运行的构建命令不是在源代码根目录的 `buildspec.yml` 文件中为 `build` 阶段指定的构建命令，则选择**插入构建命令**。对于**构建命令**，请输入您要在 `build` 阶段运行的命令。对于多个命令，使用 `&&` 分开各个命令（例如 `mvn test && mvn package`）。要在其他阶段运行命令，或者，如果 `build` 阶段对应的命令列表特别长，请将 `buildspec.yml` 文件添加到源代码根目录，将命令添加到该文件中，然后选择**在源代码根目录中使用 buildspec.yml**。 有关更多信息，请参阅[Buildspec 参考](build-spec-ref.md)。 ### 批量配置 您可以将一组构建作为单个操作来运行。有关更多信息，请参阅 [批量运行构建](batch-build.md)。 **定义批量配置** 选择该选项会允许在此项目中进行批量构建。 **批量服务角色** 为批量构建提供服务角色。 选择下列选项之一： + 如果您没有批量服务角色，请选择**新建服务角色**。在**服务角色**中，为新角色输入名称。 + 如果您拥有批量服务角色，请选择**现有服务角色**。在**服务角色**中，选择对应的服务角色。 批量构建为批量配置引入了全新的安全角色。新角色是必需的，因为 CodeBuild 必须能够代表您调用 `StartBuild`、`StopBuild` 和 `RetryBuild` 操作，才能将构建作为批处理的一部分运行。客户应该使用新角色，而不是他们在构建中使用的角色，原因有两个： + 向构建角色授予 `StartBuild`、`StopBuild` 和 `RetryBuild` 权限后，将允许单个构建通过 buildspec 启动多个构建。 + CodeBuild 批量构建会对构建数量以及可用于批量构建的计算类型进行限制。如果构建角色拥有这些权限，则构建本身就有可能绕过这些限制。 **批量支持的计算类型** 选择批处理允许的计算类型。选择所有适用的选项。 **批量支持的实例集** 选择批量支持的实例集。选择所有适用的选项。 **批处理允许的最大构建数量** 输入批处理允许的最大构建数量。如果批处理超过此限制，则会失败。 **批处理超时** 输入完成批量构建能够使用的最长时间。 **合并构件** 选择**将批处理中的所有构件合并到一个位置**，将批处理中的所有构件合并到一个位置。 **批量报告模式** 为批量构建选择所需的构建状态报告模式。 该字段仅在以下情况下可用：项目源为 Bitbucket、GitHub 或 GitHub Enterprise，且选中了**源**下的**在您的构建开始和完成时向源提供商报告构建状态**。 **聚合构建** 选择该选项，可将批处理中所有构建的状态合并到一个状态报告中。 **单个构建** 选择该选项，可分别报告批处理中所有构建的构建状态。 ### 构件 **类型** 请执行以下操作之一： + 如果您不想创建任何构建输出构件，请选择**无构件**。如果您只运行构建测试，或者您要将 Docker 映像推送到 Amazon ECR 存储库，建议执行此操作。 + 要将构建输出存储在 S3 存储桶中，请选择 **Amazon S3**，然后执行以下操作： + 如果要将项目名称用于构建输出 ZIP 文件或文件夹，请将**名称**留空。否则，请输入名称。（如果您要输出 ZIP 文件，并且要让 ZIP 文件包含文件扩展名，请务必在 ZIP 文件名之后添加扩展名。） + 如果希望构建规范文件中指定的名称覆盖控制台中指定的任何名称，请选择**启用语义版本控制**。buildspec 文件中的名称是构建时计算得出的，使用 Shell 命令语言。例如，您可以将日期和时间附加到您的构件名称后面，以便确保其唯一性。为构件提供唯一名称可防止其被覆盖。有关更多信息，请参阅[buildspec 语法](build-spec-ref.md#build-spec-ref-syntax)。 + 对于**存储桶名称**，请选择输出存储桶的名称。 + 如果您在此过程的前面部分选择了**插入构建命令**，那么对于**输出文件**，请输入构建（该构建要放到构建输出 ZIP 文件或文件夹中）中的文件位置。对于多个位置，使用逗号将各个位置隔开（例如，`appspec.yml, target/my-app.jar`）。有关更多信息，请参阅[buildspec 语法](build-spec-ref.md#build-spec-ref-syntax)中 `files` 的描述。 + 如果不想加密构建构件，请选择**删除构件加密**。 对于所需的每个辅助构件集： 1. 对于**构件标识符**，输入少于 128 个字符且仅包含字母数字字符和下划线的值。 1. 选择**添加构件**。 1. 按照前面步骤的说明配置辅助构件。 1. 选择**保存构件**。 **其他配置** **加密密钥** （可选）执行以下操作之一： + 要使用您的账户中的 AWS 托管式密钥 Amazon S3 加密构建输出构件，请将**加密密钥**留空。这是默认值。 + 要使用客户托管密钥加密构建输出构件，请在**加密密钥**中输入 KMS 密钥的 ARN。采用格式 `arn:aws:kms:region-ID:account-ID:key/key-ID`。 **缓存类型** 对于**缓存类型**，请选择下列选项之一： + 如果您不想使用缓存，请选择**无缓存**。 + 如果要使用 Amazon S3 缓存，请选择 **Amazon S3**，然后执行以下操作： + 对于**存储桶**，选择存储缓存的 S3 存储桶的名称。 + （可选）对于**缓存路径前缀**，输入 Amazon S3 路径前缀。**缓存路径前缀**值类似于目录名称。它使您能够在存储桶的同一目录下存储缓存。 **重要** 请勿将尾部斜杠 (/) 附加到路径前缀后面。 + 如果想要使用本地缓存，请选择**本地**，然后选择一个或多个本地缓存模式。 **注意** Docker 层缓存模式仅适用于 Linux。如果您选择该模式，您的项目必须在特权模式下运行。 使用缓存可节省大量构建时间，因为构建环境的可重用部分被存储在缓存中，并且可跨构建使用。有关在 buildspec 文件中指定缓存的信息，请参阅[buildspec 语法](build-spec-ref.md#build-spec-ref-syntax)。有关缓存的更多信息，请参阅 [缓存构建以提高性能](build-caching.md)。 ### 日志 选择要创建的日志。您可以创建 Amazon CloudWatch Logs 或 Amazon S3 日志，也可以两者都创建。 **CloudWatch** 如果要创建 Amazon CloudWatch Logs 日志： **CloudWatch Logs** 选择 **CloudWatch Logs**。 **组名** 输入 Amazon CloudWatch Logs 日志组的名称。 **流名称** 输入 Amazon CloudWatch Logs 日志流名称。 **S3** 如果要创建 Amazon S3 日志： **S3 日志** 选择 **S3 日志**。 **存储桶**： 选择您的日志的 S3 存储桶的名称。 **路径前缀** 输入日志的前缀。 **禁用 S3 日志加密** 如果您不希望加密您的 S3 日志，请选择此选项。 ## 创建构建项目 (AWS CLI) 有关将 AWS CLI 与 CodeBuild 结合使用的更多信息，请参阅[命令行参考](cmd-ref.md)。 要使用 AWS CLI 创建 CodeBuild 构建项目，您需要创建 JSON 格式的[项目](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_Project.html)结构，填写该结构，然后调用 [https://docs.aws.amazon.com/cli/latest/reference/codebuild/create-project.html](https://docs.aws.amazon.com/cli/latest/reference/codebuild/create-project.html) 命令来创建项目。 ### 创建 JSON 文件 利用 [https://docs.aws.amazon.com/cli/latest/reference/codebuild/create-project.html](https://docs.aws.amazon.com/cli/latest/reference/codebuild/create-project.html) 命令和 `--generate-cli-skeleton` 选项创建骨架 JSON 文件： ``` aws codebuild create-project --generate-cli-skeleton > ``` 这将创建 JSON 文件，其路径和文件名由 ** 指定。 ### 填写 JSON 文件 按照下面所示修改 JSON 数据，并保存您的结果。 ``` { "name": "", "description": "", "source": { "type": "CODECOMMIT" | "CODEPIPELINE" | "GITHUB" | "GITHUB_ENTERPRISE" | "GITLAB" | "GITLAB_SELF_MANAGED" | "BITBUCKET" | "S3" | "NO_SOURCE", "location": "", "gitCloneDepth": "", "buildspec": "", "InsecureSsl": "", "reportBuildStatus": "", "buildStatusConfig": { "context": "", "targetUrl": "" }, "gitSubmodulesConfig": { "fetchSubmodules": "" }, "auth": { "type": "", "resource": "" }, "sourceIdentifier": "" }, "secondarySources": [ { "type": "CODECOMMIT" | "CODEPIPELINE" | "GITHUB" | "GITHUB_ENTERPRISE" | "GITLAB" | "GITLAB_SELF_MANAGED" | "BITBUCKET" | "S3" | "NO_SOURCE", "location": "", "gitCloneDepth": "", "buildspec": "", "InsecureSsl": "", "reportBuildStatus": "", "auth": { "type": "", "resource": "" }, "sourceIdentifier": "" } ], "secondarySourceVersions": [ { "sourceIdentifier": "", "sourceVersion": "" } ], "sourceVersion": "", "artifacts": { "type": "CODEPIPELINE" | "S3" | "NO_ARTIFACTS", "location": "", "path": "", "namespaceType": "", "name": "", "overrideArtifactName": "", "packaging": "" }, "secondaryArtifacts": [ { "type": "CODEPIPELINE" | "S3" | "NO_ARTIFACTS", "location": "", "path": "", "namespaceType": "", "name": "", "packaging": "", "artifactIdentifier": "" } ], "cache": { "type": "", "location": "", "mode": [ "" ] }, "environment": { "type": "LINUX_CONTAINER" | "LINUX_GPU_CONTAINER" | "ARM_CONTAINER" | "WINDOWS_SERVER_2019_CONTAINER" | "WINDOWS_SERVER_2022_CONTAINER", "image": "", "computeType": "BUILD_GENERAL1_SMALL" | "BUILD_GENERAL1_MEDIUM" | "BUILD_GENERAL1_LARGE" | "BUILD_GENERAL1_2XLARGE", "certificate": "", "environmentVariables": [ { "name": "", "value": "", "type": "" } ], "registryCredential": [ { "credential": "", "credentialProvider": "" } ], "imagePullCredentialsType": "CODEBUILD" | "SERVICE_ROLE", "privilegedMode": "" }, "serviceRole": "", "autoRetryLimit": , "timeoutInMinutes": , "queuedTimeoutInMinutes": , "encryptionKey": "", "tags": [ { "key": "", "value": "" } ], "vpcConfig": { "securityGroupIds": [ "" ], "subnets": [ "" ], "vpcId": "" }, "badgeEnabled": "", "logsConfig": { "cloudWatchLogs": { "status": "", "groupName": "", "streamName": "" }, "s3Logs": { "status": "", "location": "", "encryptionDisabled": "" } }, "fileSystemLocations": [ { "type": "EFS", "location": ":/", "mountPoint": "", "identifier": "", "mountOptions": "" } ], "buildBatchConfig": { "serviceRole": "", "combineArtifacts": , "restrictions": { "maximumBuildsAllowed": , "computeTypesAllowed": [ "" ], "fleetsAllowed": [ "" ] }, "timeoutInMins": , "batchReportMode": "REPORT_AGGREGATED_BATCH" | "REPORT_INDIVIDUAL_BUILDS" }, "concurrentBuildLimit": } ``` 替换以下内容： #### **.name** 必需。此构建项目的名称。此名称在您的 AWS 账户的所有构建项目中必须是唯一的。 #### **描述** 可选。此构建项目的描述。 #### **源** 必需。[ProjectSource](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html) 对象，其中包含有关此构建项目的源代码设置的信息。添加 `source` 对象后，可以使用 [**secondarySources**](#cli.secondarysources) 额外添加多达 12 个源。这些设置包括： source/**type** 必需。包含要构建的源代码的存储库的类型。有效值包括： + `CODECOMMIT` + `CODEPIPELINE` + `GITHUB` + `GITHUB_ENTERPRISE` + `GITLAB` + `GITLAB_SELF_MANAGED` + `BITBUCKET` + `S3` + `NO_SOURCE` 如果您使用 `NO_SOURCE`，则 buildspec 不能是一个文件，因为项目没有源。相反，您必须使用 `buildspec` 属性为 buildspec 指定 YAML 格式的字符串。有关更多信息，请参阅 [创建没有源的构建项目](no-source.md)。 source/**location** 必需（除非您将 ** 设置为 `CODEPIPELINE`）。指定存储库类型的源代码的位置。 + 对于 CodeCommit，则为指向包含源代码和 buildspec 文件的存储库的 HTTPS 克隆 URL（例如，`https://git-codecommit..amazonaws.com/v1/repos/`）。 + 对于 Amazon S3，是构建输入存储桶的名称，后附包含源代码和 buildspec 的 ZIP 文件的路径和名称。例如： + 对于位于输入存储桶根目录的 ZIP 文件：`/.zip`。 + 对于位于输入存储桶子文件夹中的 ZIP 文件：`//.zip`。 + 对于 GitHub，则为指向包含源代码和 buildspec 文件的存储库的 HTTPS 克隆 URL。该 URL 必须包含 github.com。您必须将您的 AWS 账户连接到您的 GitHub 账户。为此，请使用 CodeBuild 控制台创建构建项目。 + 选择**授权应用程序**。（连接到您的 GitHub 账户后，您不需要完成构建项目的创建。您可以离开 CodeBuild 控制台。） + 对于 GitHub Enterprise Server，则为指向包含源代码和 buildspec 文件的存储库的 HTTP 或 HTTPS 克隆 URL。您还必须将您的 AWS 账户连接到您的 GitHub Enterprise Server 账户。为此，请使用 CodeBuild 控制台创建构建项目。 1. 在 GitHub Enterprise Server 中创建个人访问令牌。 1. 将此令牌复制到您的剪贴板，以便在创建 CodeBuild 项目时使用。有关更多信息，请参阅 GitHub 帮助网站上的[为命令行创建个人访问令牌](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)。 1. 如果您使用控制台创建 CodeBuild 项目，请在**源**中为**源提供商**选择 **GitHub Enterprise**。 1. 对于**个人访问令牌**，请粘贴已复制到剪贴板中的令牌。选择**保存令牌**。您的 CodeBuild 账户现在已与您的 GitHub Enterprise Server 账户连接。 + 对于 GitLab 和 GitLab 自行管理，则为指向包含源代码和 buildspec 文件的存储库的 HTTPS 克隆 URL。请注意，如果使用 GitLab，则 URL 必须包含 gitlab.com。如果使用 GitLab 自行管理，则 URL 不必包含 gitlab.com。您必须将您的 AWS 账户与 GitLab 或 GitLab 自行管理账户关联。为此，请使用 CodeBuild 控制台创建构建项目。 + 在开发人员工具导航窗格中，依次选择**设置**、**连接**，然后选择**创建连接**。在此页面上，创建 GitLab 或 GitLab 自行管理连接，然后选择**连接到 GitLab**。 + 对于 Bitbucket，则为指向包含源代码和 buildspec 文件的存储库的 HTTPS 克隆 URL。该 URL 必须包含 bitbucket.org。您还必须将您的 AWS 账户连接到您的 Bitbucket 账户。为此，请使用 CodeBuild 控制台创建构建项目。 1. 当您使用控制台与 Bitbucket 连接（或重新连接）时，在 Bitbucket **确认对账户的访问**页面上，选择**授予访问权限**。（连接到您的 Bitbucket 账户后，您不需要完成构建项目的创建。您可以离开 CodeBuild 控制台。） + 对于 AWS CodePipeline，请勿为 `location` 指定 `source` 值。CodePipeline 会忽略该值，因为当您在 CodePipeline 中创建管道时，您会在管道的源阶段指定源代码位置。 source/**gitCloneDepth** 可选。要下载的历史记录深度。最小值为 0。如果此值为 0、大于 25 或未提供，则会下载每个构建项目的完整历史记录。如果您的源类型是 Amazon S3，则不支持此值。 source/**buildspec** 可选。要使用的构建规范定义或文件。如果此值未提供或设置为空字符串，源代码必须在其根目录中包含 `buildspec.yml` 文件。如果设置了该值，则它可以是内联 buildspec 定义，也可以是指向相对于主要源根目录的替代 buildspec 文件的路径，或者是指向 S3 存储桶的路径。存储桶必须与构建项目位于同一 AWS 区域中。使用其 ARN 指定 buildspec 文件（例如，`arn:aws:s3:::/buildspec.yml`）。有关更多信息，请参阅 [buildspec 文件名称和存储位置](build-spec-ref.md#build-spec-ref-name-storage)。 source/**auth** 包含有关授权设置的信息，该授权允许 CodeBuild 访问要构建的源代码。 source/auth/**type** 必需。要使用的授权类型。有效值为： + `OAUTH` + `CODECONNECTIONS` + `SECRETS_MANAGER` source/auth/**resource** 可选。适用于指定授权类型的资源值。这可以是 Secrets Manager ARN 或 CodeConnections ARN。 source/**reportBuildStatus** 指定是否向源提供商发送构建的开始和完成状态。如果使用源提供商而非 GitHub、GitHub Enterprise Server 或 Bitbucket 设置此项，则会引发 `invalidInputException`。 为了能够向源提供商报告构建状态，与源提供商关联的用户必须拥有对存储库的写入权限。如果用户没有写入权限，则无法更新构建状态。有关更多信息，请参阅[源提供商访问权限](access-tokens.md)。 source/**buildStatusConfig** 包含定义 CodeBuild 构建项目如何向源提供商报告构建状态的信息。此选项仅在源提供商为 `GITHUB`、`GITHUB_ENTERPRISE` 或 `BITBUCKET` 时使用。 source/buildStatusConfig/**context** 对于 Bitbucket 源，此参数用于处于 Bitbucket 提交状态的 `name` 参数。对于 GitHub 源，此参数用于处于 GitHub 提交状态的 `context` 参数。 例如，您可以使用 CodeBuild 环境变量让 `context` 包含内部版本号和 webhook 触发器： ``` AWS CodeBuild sample-project Build #$CODEBUILD_BUILD_NUMBER - $CODEBUILD_WEBHOOK_TRIGGER ``` 这会导致由 webhook 拉取请求事件触发的 build \$124 的上下文显示如下： ``` AWS CodeBuild sample-project Build #24 - pr/8 ``` source/buildStatusConfig/**targetUrl** 对于 Bitbucket 源，此参数用于处于 Bitbucket 提交状态的 `url` 参数。对于 GitHub 源，此参数用于处于 GitHub 提交状态的 `target_url` 参数。 例如，您可以将 `targetUrl` 设置为 `https://aws.amazon.com/codebuild/`，而提交状态将链接到此 URL。 您还可以将 CodeBuild 环境变量包含到 `targetUrl` 中，以便向此 URL 添加其他信息。例如，要将构建区域添加到此 URL，请将 `targetUrl` 设置为： ``` "targetUrl": "https://aws.amazon.com/codebuild/?region=$AWS_REGION" ``` 如果构建区域为 `us-east-2`，则会扩展为： ``` https://aws.amazon.com/codebuild/?region=us-east-2 ``` source/**gitSubmodulesConfig** 可选。有关 Git 子模块配置的信息。只能与 CodeCommit、GitHub、GitHub Enterprise Server 和 Bitbucket 一起使用。 source/gitSubmodulesConfig/**fetchSubmodules** 如果您希望将 Git 子模块包含到存储库中，请将 `fetchSubmodules` 设置为 `true`。包含的 Git 子模块必须配置为 HTTPS。 source/**InsecureSsl** 可选。仅与 GitHub Enterprise Server 一起使用。将此值设为 `true`，将在连接到您的 GitHub Enterprise Server 项目存储库时忽略 TLS 警告。默认值为 `false`。只应将 `InsecureSsl` 用于测试目的。它不应在生产环境中使用。 source/**sourceIdentifier** 用户定义的项目源标识符。对于主源来说，为可选项。对于辅助源，则为必选项。 #### **secondarySources** 可选。一组 [ProjectSource](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html) 对象，其中包含有关构建项目辅助源的信息。最多可以添加 12 个辅助源。这些 `secondarySources` 对象使用的属性与[**源**](#cli.source)对象使用的属性相同。在辅助源对象中，`sourceIdentifier` 是必需项。 #### **secondarySourceVersions** 可选。一组 [ProjectSourceVersion](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSourceVersion.html) 对象。如果在构建级别指定 `secondarySourceVersions`，则它们优先于此对象。 #### **sourceVersion** 可选。要为此项目构建的构建输入的版本。如果未指定，则使用最新版本。如果已指定，则它必须是下列项之一： + 对于 CodeCommit，为要使用的提交 ID、分支或 Git 标签。 + 对于 GitHub，为提交 ID、拉取请求 ID、分支名称或与您要构建的源代码版本相对应的标签名称。如果指定了拉取请求 ID，则必须使用格式 `pr/pull-request-ID`（例如，`pr/25`）。如果指定了分支名称，则将使用分支的 HEAD 提交 ID。如果未指定，则使用默认分支的 HEAD 提交 ID。 + 对于 GitLab，指定提交 ID、拉取请求 ID、分支名称、标签名称或引用。有关更多信息，请参阅 [源版本示例 AWS CodeBuild](sample-source-version.md)。 + 对于 Bitbucket，为提交 ID、分支名称或与您要构建的源代码版本相对应的标签名称。如果指定了分支名称，则将使用分支的 HEAD 提交 ID。如果未指定，则使用默认分支的 HEAD 提交 ID。 + 对于 Amazon S3，为表示要使用的构建输入 ZIP 文件的对象的版本 ID。 如果在构建级别指定 `sourceVersion`，则该版本将优先于此 `sourceVersion`（在项目级别）。有关更多信息，请参阅 [源版本示例 AWS CodeBuild](sample-source-version.md)。 #### **构件** 必需。[ProjectArtifacts](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectArtifacts.html) 对象，其中包含有关此构建项目的输出构件设置的信息。添加 `artifacts` 对象后，可以使用 [secondaryArtifacts](#cli.secondaryartifacts) 额外添加最多 12 个构件。这些设置包括： artifacts/**type** 必需。构建输出构件的类型。有效值为： + `CODEPIPELINE` + `NO_ARTIFACTS` + `S3` artifacts/**location** 仅与 `S3` 构件类型一起使用。不用于其他构件类型。 您在先决条件中创建或标识的输出存储桶的名称。 artifacts/**path** 仅与 `S3` 构件类型一起使用。不用于其他构件类型。 放置 ZIP 文件或文件夹的输出存储桶的路径。如果您没有为 `path` 指定值，那么 CodeBuild 将使用 `namespaceType`（如果指定）和 `name` 来决定构建输出 ZIP 文件或文件夹的路径和名称。例如，如果您为 `path` 指定 `MyPath`，并为 `name` 指定 `MyArtifact.zip`，那么路径和名称将为 `MyPath/MyArtifact.zip`。 artifacts/**namespaceType** 仅与 `S3` 构件类型一起使用。不用于其他构件类型。 构建输出 ZIP 文件或文件夹的命名空间。有效值包括 `BUILD_ID` 和 `NONE`。使用 `BUILD_ID` 将构建 ID 插入到构建输出 ZIP 文件或文件夹的路径中。否则，请使用 `NONE`。如果您没有为 `namespaceType` 指定值，那么 CodeBuild 将使用 `path`（如果指定）和 `name` 来决定构建输出 ZIP 文件或文件夹的路径和名称。例如，如果您为 `path` 指定 `MyPath`，为 `namespaceType` 指定 `BUILD_ID`，并为 `name` 指定 `MyArtifact.zip`，那么路径和名称将为 `MyPath/build-ID/MyArtifact.zip`。 artifacts/**name** 仅与 `S3` 构件类型一起使用。不用于其他构件类型。 `location` 中构建输出 ZIP 文件或文件夹的名称。例如，如果您为 `path` 指定 `MyPath`，并为 `name` 指定 `MyArtifact.zip`，那么路径和名称将为 `MyPath/MyArtifact.zip`。 artifacts/**overrideArtifactName** 仅与 S3 构件类型一起使用。不用于其他构件类型。 可选。如果设置为 `true`，在 buildspec 文件的 `artifacts` 块中指定的名称将覆盖 `name`。有关更多信息，请参阅 [的构建规范参考 CodeBuild](build-spec-ref.md)。 artifacts/**packaging** 仅与 `S3` 构件类型一起使用。不用于其他构件类型。 可选。指定如何打包构件。允许的值包括： NONE 创建包含构建构件的文件夹。这是默认值。 ZIP 创建包含构建构件的 ZIP 文件。 #### secondaryArtifacts 可选。一组 [ProjectArtifacts](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectArtifacts.html) 对象，其中包含有关构建项目辅助构件设置的信息。最多可以添加 12 个辅助构件。`secondaryArtifacts` 使用的许多设置与 [**构件**](#cli.artifacts) 对象相同。 #### cache 必需。[ProjectCache](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectCache.html) 对象，其中包含有关此构建项目的缓存设置的信息。有关更多信息，请参阅[缓存构建](build-caching.md)。 #### environment 必需。[ProjectEnvironment](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectEnvironment.html) 对象，其中包含有关此项目的构建环境设置的信息。这些设置包括： environment/**type** 必需。构建环境的类型。有关更多信息，请参阅 *CodeBuild API 参考*中的[类型](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectEnvironment.html#CodeBuild-Type-ProjectEnvironment-type)。 environment/**image** 必需。此构建环境使用的 Docker 映像标识符。通常，此标识符以 *image-name*:*tag* 的形式表示。例如，在 CodeBuild 用来管理其 Docker 映像的 Docker 存储库中，这将是 `aws/codebuild/standard:5.0`。在 Docker Hub 中，为 `maven:3.3.9-jdk-8`。在 Amazon ECR 中，为 `account-id.dkr.ecr.region-id.amazonaws.com/your-Amazon-ECR-repo-name:tag`。有关更多信息，请参阅 [提供的 Docker 镜像 CodeBuild](build-env-ref-available.md)。 environment/**computeType** 必需。指定此构建环境使用的计算资源。有关更多信息，请参阅 *CodeBuild API 参考*中的 [computeType](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectEnvironment.html#CodeBuild-Type-ProjectEnvironment-computeType)。 environment/**certificate** 可选。Amazon S3 存储桶的 ARN、路径前缀和包含 PEM 编码证书的对象键。对象键可以仅为 .pem 文件，也可以为包含 PEM 编码的证书的 .zip 文件。例如，如果 Amazon S3 存储桶名称为 ``，路径前缀为 ``，且对象键名称为 ``，则 `certificate` 可接受的格式为 `` 或 `arn:aws:s3:::`。 environment/**environmentVariables** 可选。一组 [EnvironmentVariable](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_EnvironmentVariable.html) 对象，其中包含要为此构建环境指定的环境变量。每个环境变量都表示为一个对象，其中包含 `name`、`value`，以及 `name` 和 `value` 的 `type`，还有 `type`。 控制台和 AWS CLI 用户可以查看所有环境变量。如果您不担心环境变量的可见性，请设置 `name` 和 `value`，并将 `type` 设置为 `PLAINTEXT`。 我们建议您将具有敏感值（例如 AWS 访问密钥 ID、AWS 秘密访问密钥或密码）的环境变量作为参数存储在 Amazon EC2 Systems Manager Parameter Store 或 AWS Secrets Manager 中。对于 `name`，针对存储的参数，设置标识符以供 CodeBuild 引用。 如果您使用 Amazon EC2 Systems Manager Parameter Store，针对 `value`，将参数名称设置为存储在 Parameter Store 中。将 `type` 设置为 `PARAMETER_STORE`。以名为 `/CodeBuild/dockerLoginPassword` 的参数为例，将 `name` 设置为 `LOGIN_PASSWORD`。将 `value` 设置为 `/CodeBuild/dockerLoginPassword`。将 `type` 设置为 `PARAMETER_STORE`。 如果您使用 Amazon EC2 Systems Manager Parameter Store，我们建议您使用以 `/CodeBuild/` 开头的参数名称（例如，`/CodeBuild/dockerLoginPassword`）来存储参数。您可以使用 CodeBuild 控制台在 Amazon EC2 Systems Manager 中创建参数。选择**创建参数**，然后按照对话框中的说明操作。（在该对话框中，对于 **KMS 密钥**，您可以指定您账户中的 AWS KMS 密钥的 ARN。Amazon EC2 Systems Manager 使用此密钥在存储过程中加密参数的值并在检索过程中解密参数的值。） 如果您使用 CodeBuild 控制台创建参数，控制台将在参数名称被存储时以 `/CodeBuild/` 作为它的开头。有关更多信息，请参阅《Amazon EC2 Systems Manager 用户指南》**中的 [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) 和 [Systems Manager Parameter Store 控制台演练](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-walk.html#sysman-paramstore-console)。 如果您的构建项目引用了 Amazon EC2 Systems Manager Parameter Store 中存储的参数，则构建项目的服务角色必须允许 `ssm:GetParameters` 操作。如果您之前选择了**新建服务角色**，CodeBuild 将在您的构建项目的默认服务角色中包含此操作。但是，如果您选择了**现有服务角色**，必须单独将此操作添加到您的服务角色中。 如果您的构建项目引用了 Amazon EC2 Systems Manager Parameter Store 中存储的但参数名称不以 `/CodeBuild/` 开头的参数，且您选择了**新建服务角色**，您必须更新该服务角色以允许访问不以 `/CodeBuild/` 开头的参数名称。这是因为该服务角色仅允许访问以 `/CodeBuild/` 开头的参数名称。 如果您选择**新建服务角色**，服务角色将拥有解密 Amazon EC2 Systems Manager Parameter Store 中 `/CodeBuild/` 命名空间下的所有参数的权限。 您设置的环境变量将替换现有的环境变量。例如，如果 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_` 打头的名称设置任何环境变量。此前缀是专为内部使用预留的。 如果具有相同名称的环境变量在多处都有定义，则应按照如下方式确定其值： + 构建操作调用开始时的值优先级最高。 + 构建项目定义中的值优先级次之。 + buildspec 声明中的值优先级最低。 如果您使用 Secrets Manager，针对 `value`，请将参数的名称设置为存储在 Secrets Manager 中。将 `type` 设置为 `SECRETS_MANAGER`。以名为 `/CodeBuild/dockerLoginPassword` 的密钥为例，将 `name` 设置为 `LOGIN_PASSWORD`。将 `value` 设置为 `/CodeBuild/dockerLoginPassword`。将 `type` 设置为 `SECRETS_MANAGER`。 如果您使用 Secrets Manager，我们建议您存储名称以 `/CodeBuild/`（例如 `/CodeBuild/dockerLoginPassword`）开头的密钥。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[什么是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。 如果您的构建项目引用了 Secrets Manager 中存储的密钥，则构建项目的服务角色必须允许 `secretsmanager:GetSecretValue` 操作。如果您之前选择了**新建服务角色**，CodeBuild 将在您的构建项目的默认服务角色中包含此操作。但是，如果您选择了**现有服务角色**，必须单独将此操作添加到您的服务角色中。 如果您的构建项目引用了 Secrets Manager 中存储的但密钥名称不以 `/CodeBuild/` 开头的密钥，且您选择了**新建服务角色**，您必须更新该服务角色以允许访问不以 `/CodeBuild/` 开头的密钥名称。这是因为该服务角色仅允许访问以 `/CodeBuild/` 开头的密钥名称。 如果您选择**新建服务角色**，该服务角色将拥有解密 Secrets Manager 中 `/CodeBuild/` 命名空间下的所有密钥的权限。 environment/**registryCredential** 可选。[RegistryCredential](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_RegistryCredential.html) 对象，用于指定提供对私有 Docker 注册表的访问权限的凭证。 environment/registryCredential/**credential** 指定使用 AWS Managed Services 创建的凭证的 ARN 或名称。仅当凭证存在于您当前的区域中时，您才能使用凭证的名称。 environment/registryCredential/**credentialProvider** 唯一有效值为 `SECRETS_MANAGER`。 当设置此属性时： + `imagePullCredentials`必须将 / 设置为 `SERVICE_ROLE`。 + 映像不能为辅助映像或 Amazon ECR 映像。 environment/**imagePullCredentialsType** 可选。CodeBuild 用于在您的构建中拉取映像的凭证类型。有两个有效值： CODEBUILD `CODEBUILD` 指定 CodeBuild 使用其自己的凭证。您必须编辑 Amazon ECR 存储库策略以信任 CodeBuild 服务主体。 SERVICE\$1ROLE 指定 CodeBuild 使用您的构建项目的服务角色。 当您使用跨账户或私有注册表映像时，必须使用 `SERVICE_ROLE` 凭证。当您使用 CodeBuild 辅助映像时，必须使用 `CODEBUILD` 凭证。 environment/**privilegedMode** 仅在使用此构建项目来构建 Docker 映像时，才设置为 `true`。否则，尝试与 Docker 守护程序交互的所有关联的构建都将失败。您还必须启动 Docker 守护程序，以便您的构建与其交互。执行此操作的一种方法是通过运行以下构建命令在您的 buildspec 文件的 `install` 阶段初始化 Docker 进程守护程序。如果您指定了由具有 Docker 支持的 CodeBuild 提供的构建环境映像，请不要运行这些命令。 默认情况下，为非 VPC 构建启用 Docker 进程守护程序。如果您想使用 Docker 容器进行 VPC 构建，请参阅 Docker 文档网站上的[运行时权限和 Linux 功能](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)并启用特权模式。此外，Windows 不支持特权模式。 ``` - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & - timeout 15 sh -c "until docker info; do echo .; sleep 1; done" ``` #### serviceRole 必需。CodeBuild 代表用户用来与服务进行交互的服务角色 ARN（例如，`arn:aws:iam::account-id:role/role-name`）。 #### autoRetryLimit 可选。构建失败后额外的自动重试次数。例如，如果自动重试限制设置为 2，则 CodeBuild 将调用 `RetryBuild` API 来自动重试您的构建，最多再重试 2 次。 #### timeoutInMinutes 可选。5 到 2160 分钟（36 个小时）之间的一个分钟数，在此时间后，如果构建未完成，CodeBuild 会将其停止。如果未指定，则使用默认值 60。要确定 CodeBuild 是否以及何时因超时而停止生成，请运行 `batch-get-builds` 命令。要确定构建是否已停止，请在输出中查看 `buildStatus` 的值是否为 `FAILED`。要确定构建何时超时，请在输出中查看与 `TIMED_OUT` 的 `phaseStatus` 值关联的 `endTime` 值。 #### queuedTimeoutInMinutes 可选。5 到 480 分钟 (8 个小时) 之间的一个分钟数，在此时间后，如果构建仍在排队状态，CodeBuild 会将其停止。如果未指定，则使用默认值 60。 #### encryptionKey 可选。CodeBuild 用于加密构建输出的 AWS KMS key 的别名或 ARN。如果您指定别名，请使用格式 `arn:aws:kms:region-ID:account-ID:key/key-ID`，或者，如果存在别名，请使用格式 `alias/key-alias`。如果未指定，则会使用 Amazon S3 的 AWS 托管 KMS 密钥。 #### tags 可选。一组 [Tag](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_Tag.html) 对象，提供您要与此构建项目关联的标签。您最多可指定 50 个标签。这些标签可由支持 CodeBuild 构建项目标签的任何 AWS 服务使用。每个标签都表示为带有 `key` 和 `value` 的对象。 #### vpcConfig 可选。[VpcConfig](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_VpcConfig.html) 对象，其中包含有关您的项目 VPC 配置的信息。有关更多信息，请参阅[AWS CodeBuild 与亚马逊 Virtual Private Cloud 一起使用](vpc-support.md)。 这些属性包括： vpcId 必需。CodeBuild 使用的 VPC ID。运行此命令获取您的区域中的所有 VPC ID 的列表： ``` aws ec2 describe-vpcs --region ``` subnets 必需。一组子网 ID，包括 CodeBuild 使用的资源。运行此命令，以获取这些 ID： ``` aws ec2 describe-subnets --filters "Name=vpc-id,Values=" --region ``` securityGroupIds 必需。一组安全组 ID，CodeBuild 用来提供 VPC 中资源的访问权限。运行此命令，以获取这些 ID： ``` aws ec2 describe-security-groups --filters "Name=vpc-id,Values=" -- ``` #### badgeEnabled 可选。指定是否在 CodeBuild 项目中包含构建徽章。设置为 `true` 可启用构建徽章；设置为 `false` 可将其禁用。有关更多信息，请参阅 [使用以下方法制作徽章示例 CodeBuild](sample-build-badges.md)。 #### logsConfig [LogsConfig](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_LogsConfig.html) 对象，其中包含有关此构建日志所在位置的信息。 logsConfig/**cloudWatchLogs** [CloudWatchLogsConfig](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_CloudWatchLogsConfig.html) 对象，其中包含有关将日志推送到 CloudWatch Logs 的信息。 logsConfig/**s3Logs** [S3LogsConfig](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_S3LogsConfig.html) 对象，其中包含有关将日志推送到 Amazon S3 的信息。 #### fileSystemLocations 可选。一组 [ProjectFileSystemsLocation](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectFileSystemLocation.html) 对象，其中包含有关 Amazon EFS 配置的信息。 #### buildBatchConfig 可选。`buildBatchConfig` 对象采用 [ProjectBuildBatchConfig](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectBuildBatchConfig.html) 结构，其中包含项目的批量构建配置信息。 buildBatchConfig/**serviceRole** 批量构建项目的服务角色 ARN。 buildBatchConfig/**combineArtifacts** 布尔值，用于指定是否将批量构建的构建构件合并到单个构件位置。 buildBatchConfig/restrictions/**maximumBuildsAllowed** 允许的最大构建数。 buildBatchConfig/restrictions/**computeTypesAllowed** 一组字符串，用于指定批量构建允许的计算类型。请参阅[构建环境计算类型](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html)以了解这些值。 buildBatchConfig/restrictions/**fleetsAllowed** 一组字符串，用于指定批量构建支持的实例集。有关更多信息，请参阅[在预留容量实例集上运行构建](https://docs.aws.amazon.com/codebuild/latest/userguide/fleets.html)。 buildBatchConfig/**timeoutInMinutes** 必须完成批量构建的最长时间（以分钟为单位）。 buildBatchConfig/**batchReportMode** 指定如何将构建状态报告发送到源提供商以进行批量构建。有效值包括： `REPORT_AGGREGATED_BATCH` （默认）将所有构建状态聚合到单个状态报告中。 `REPORT_INDIVIDUAL_BUILDS` 为每个单独的构建发送单独的状态报告。 #### concurrentBuildLimit 此项目允许的并发构建的最大数量。 仅当当前构建数量小于或等于此限值时，才会启动新构建。如果当前构建计数达到此限值，则新构建将受到限制且不会运行。 ### 创建项目 要创建项目，请再次运行 **[https://docs.aws.amazon.com/cli/latest/reference/codebuild/create-project.html](https://docs.aws.amazon.com/cli/latest/reference/codebuild/create-project.html)** 命令，传递您的 JSON 文件： ``` aws codebuild create-project --cli-input-json file:// ``` 如果成功，[项目](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_Project.html)对象的 JSON 表示形式将显示在控制台输出中。有关此数据的示例，请参阅 [CreateProject 响应语法](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_CreateProject.html#API_CreateProject_ResponseSyntax)。 您稍后可以更改构建项目的任何设置，但构建项目名称除外。有关更多信息，请参阅[更改构建项目的设置 (AWS CLI)](change-project.md#change-project-cli)。 要开始运行构建，请参阅[运行构建 (AWS CLI)](run-build-cli.md)。 如果您的源代码存储在 GitHub 存储库中，并且您希望 CodeBuild 在每次代码更改被推送到存储库时重建源代码，请参阅[开始自动运行构建（AWS CLI）](run-build-cli-auto-start.md)。 ## 创建构建项目（AWS 开发工具包） 有关将 AWS CodeBuild 与 AWS 开发工具包结合使用的信息，请参阅 [AWS SDKs 和工具参考](sdk-ref.md)。 ## 创建构建项目 (CloudFormation) 有关将 AWS CodeBuild 与 CloudFormation 结合使用的信息，请参阅《AWS CloudFormation 用户指南》**中的 [CodeBuild 的 CloudFormation 模板](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codebuild-project.html)。