创建构建项目 (控制台) - AWS CodeBuild
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

创建构建项目 (控制台)

Open the AWS CodeBuild console at https://console.amazonaws.cn/codesuite/codebuild/home.

If a CodeBuild information page is displayed, choose Create build project. Otherwise, on the navigation pane, expand Build, choose Build projects, and then choose Create build project.

选择 Create build project (创建构建项目)

填写以下部分。完成后,选择页面底部的 Create build project (创建构建项目)

项目配置

项目名称

输入此构建项目的名称。构建项目名称在您的各个 AWS 账户内必须是唯一的。

Description

输入构建项目的可选描述,以帮助其他用户了解此项目的用途。

构建徽章

选择此项可使您的项目的构建状态可见且可嵌入。有关更多信息,请参阅 构建徽章示例

注意

如果您的源提供程序是 Amazon S3,则构建徽章不适用。

其他信息

(可选)对于 Tags (标签),输入您希望支持 AWS 服务使用的任何标签的名称和值。使用 Add row 添加标签。您最多可以添加 50 个标签。

Source

源提供商

选择源代码提供商类型。使用以下列表为您的源提供商选择适当的选项:

注意

CodeBuild does not support Bitbucket Server.

Amazon S3
Bucket

选择包含源代码的输入存储桶的名称。

S3 对象键或 S3 文件夹

输入 ZIP 文件的名称或包含源代码的文件夹的路径。

源版本

输入表示输入文件构建的对象的版本 ID。有关更多信息,请参阅使用 AWS CodeBuild 的源版本示例

CodeCommit
Repository

选择要使用的存储库。

参考类型

选择 Branch (分支)Git tag (Git 标签)Commit ID (提交 ID) 以指定源代码的版本。有关更多信息,请参阅使用 AWS CodeBuild 的源版本示例

Git clone 深度

选择创建一个浅克隆,其历史记录会截断至指定数量的提交。如果您需要完整克隆,请选择 Full (完整)

使用 Git 子模块

如果您希望在存储库中包含 Git 子模块,请选择它。

Bitbucket
Repository

选择使用 OAuth 连接使用 Bitbucket 应用程序密码连接 并按照说明连接到 Bitbucket。

选择您账户中的公有 存储库或 存储库。

源版本

输入分支、提交 ID、标签或引用和提交 ID。有关更多信息,请参阅使用 AWS CodeBuild 的源版本示例

Git clone 深度

选择 Git clone depth (Git 克隆深度) 以创建一个浅克隆,其历史记录会截断至指定数量的提交。如果您需要完整克隆,请选择 Full (完整)

使用 Git 子模块

如果您希望在存储库中包含 Git 子模块,请选择它。

如果您希望向源提供商报告构建的开始和完成状态,请选择 Report build status to source provider when your builds start and finish

注意

由 Webhook 触发的构建的状态将始终报告给您的源提供商。

如果您希望 每次将代码更改推送到此存储库时都构建源代码,请选择 Rebuild every time a code change is pushed to this repository (每次将代码更改推送到此存储库时都会重新构建)CodeBuild。Webhook 仅允许在您自己的 Bitbucket、GitHub 或 GitHub Enterprise 存储库中使用。

对于 Status context (状态上下文),输入要用于 Bitbucket 提交状态中的 name 参数的值。有关更多信息,请参阅 Bitbucket API 文档中的构建

对于 Target URL (目标 URL),输入要用于 Bitbucket 提交状态中的 url 参数的值。有关更多信息,请参阅 Bitbucket API 文档中的构建

如果您选择了 Rebuild every time a code change is pushed to this repository (每次将代码更改推送到此存储库时都会重新构建),则在 Event type (事件类型) 中,选择要触发构建的事件。使用正则表达式创建筛选条件。如果未指定筛选条件,则所有更新和创建拉取请求及所有推送事件都会触发构建。有关更多信息,请参阅 GitHub Webhook 事件Bitbucket Webhook 事件

GitHub
Repository

选择使用 OAuth 连接使用 GitHub 个人访问令牌连接,然后按照说明连接到(或重新连接) GitHub 并授权访问 AWS CodeBuild。

选择您账户中的公有 存储库或 存储库。

源版本

输入分支、提交 ID、标签或引用和提交 ID。有关更多信息,请参阅使用 AWS CodeBuild 的源版本示例

Git clone 深度

选择 Git clone depth (Git 克隆深度) 以创建一个浅克隆,其历史记录会截断至指定数量的提交。如果您需要完整克隆,请选择 Full (完整)

使用 Git 子模块

如果您希望在存储库中包含 Git 子模块,请选择它。

如果您希望向源提供商报告构建的开始和完成状态,请选择 Report build status to source provider when your builds start and finish

注意

由 Webhook 触发的构建的状态将始终报告给您的源提供商。

如果您希望 在每次将代码更改推送到此存储库时构建源代码,请选择 Rebuild every time a code change is pushed to this repository (每次将代码更改推送到此存储库时都会重新构建)CodeBuild。Webhook 仅适用于您自己的 Bitbucket、GitHub 或 GitHub Enterprise 存储库。

对于 Status context (状态上下文),输入要用于 context 提交状态中的 GitHub 参数的值。有关更多信息,请参阅 开发人员指南中的创建提交状态GitHub。

对于 Target URL (目标 URL),输入要用于 target_url 提交状态中的 GitHub 参数的值。有关更多信息,请参阅 开发人员指南中的创建提交状态GitHub。

如果您选择了 Rebuild every time a code change is pushed to this repository (每次将代码更改推送到此存储库时都会重新构建),则在 Event type (事件类型) 中,选择要触发构建的事件。使用正则表达式创建筛选条件。如果未指定筛选条件,则所有更新和创建拉取请求及所有推送事件都会触发构建。有关更多信息,请参阅 GitHub Webhook 事件Bitbucket Webhook 事件

GitHub Enterprise Server
GitHub 企业个人访问令牌

有关如何将个人访问令牌复制到剪贴板的信息,请参阅GitHub Enterprise Server 示例。在文本字段中粘贴令牌,然后选择 Save Token (保存令牌)

注意

您只需输入并保存一次个人访问令牌。CodeBuild 将在所有未来项目中使用此令牌。

源版本

输入拉取请求、分支、提交 ID、标签或引用和提交 ID。有关更多信息,请参阅使用 AWS CodeBuild 的源版本示例

Git clone 深度

选择 Git clone depth (Git 克隆深度) 以创建一个浅克隆,其历史记录会截断至指定数量的提交。如果您需要完整克隆,请选择 Full (完整)

使用 Git 子模块

如果您希望在存储库中包含 Git 子模块,请选择它。

生成包状态

如果您希望向源提供商报告构建的开始和完成状态,请选择 Report build status to source provider when your builds start and finish

注意

由 Webhook 触发的构建的状态将始终报告给您的源提供商。

不安全的 SSL

选择在连接到您的 GitHub Enterprise 项目存储库时忽略 SSL 警告。

如果您希望 在每次将代码更改推送到此存储库时构建源代码,请选择 Rebuild every time a code change is pushed to this repository (每次将代码更改推送到此存储库时都会重新构建)CodeBuild。Webhook 仅适用于您自己的 Bitbucket、GitHub 或 GitHub Enterprise 存储库。

对于 Status context (状态上下文),输入要用于 context 提交状态中的 GitHub 参数的值。有关更多信息,请参阅 开发人员指南中的创建提交状态GitHub。

对于 Target URL (目标 URL),输入要用于 target_url 提交状态中的 GitHub 参数的值。有关更多信息,请参阅《 开发人员指南》中的创建提交状态GitHub。

如果您选择了 Rebuild every time a code change is pushed to this repository (每次将代码更改推送到此存储库时都会重新构建),则在 Event type (事件类型) 中,选择要触发构建的事件。使用正则表达式创建筛选条件。如果未指定筛选条件,则所有更新和创建拉取请求及所有推送事件都会触发构建。有关更多信息,请参阅 GitHub Webhook 事件Bitbucket Webhook 事件

Environment

环境映像

执行下列操作之一:

  • 要使用由 AWS CodeBuild 托管的 Docker 映像,请选择 Managed image (托管映像),然后从 Operating system (操作系统)Runtime(s) (运行时)Image (映像) 以及 Image version (映像版本) 中进行相应选择。从 Environment type (环境类型) 中进行选择(如果可用)。

  • 要使用其他 Docker 映像,请选择 Custom image (自定义映像)。对于 Environment type (环境类型),选择 ARMLinuxLinux GPUWindows。如果您针对 External registry URL (外部注册表 URL) 选择 Other registry (其他注册表),请在 Docker Hub 中按照格式 docker repository/docker image name 输入 Docker 映像的名称和标签。如果您选择 Amazon ECR,请使用 Amazon ECR repository (Amazon ECR 存储库)Amazon ECR image (Amazon ECR 映像) 在您的 AWS 账户中选择 Docker 映像。

  • 要使用私有 Docker 映像,请选择自定义映像。对于 Environment type (环境类型),选择 ARMLinuxLinux GPUWindows。对于 Image registry (映像注册表),选择 Other registry (其他注册表),然后输入您的私有 Docker 映像的凭证的 ARN。凭证必须由 Secrets Manager 创建。有关更多信息,请参阅 AWS Secrets Manager 用户指南 中的什么是 AWS Secrets Manager?

Privileged

(可选)仅当您计划使用此构建项目来构建 Docker 映像且您选择的构建环境映像不是由具有 Docker 支持的 CodeBuild 提供时,才选择 Privileged (特权)。否则,尝试与 Docker 守护程序交互的所有关联的构建都将失败。您还必须启动 Docker 守护程序,以便您的构建与其交互。执行此操作的一种方法是,通过运行以下构建命令在您的构建规范的 install 阶段初始化 Docker 守护程序。如果您选择了由具有 Docker 支持的 CodeBuild 提供的构建环境映像,请不要运行这些命令。

注意

By default, Docker containers do not allow access to any devices. Privileged mode grants a build project's Docker container access to all devices. For more information, see Runtime Privilege and Linux Capabilities on the Docker Docs website.

- nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done"
服务 角色

执行下列操作之一:

  • 如果您没有 CodeBuild 服务角色,请选择 New service role (新建服务角色)。在 Role name 中,为新角色输入名称。

  • 如果您有 CodeBuild 服务角色,请选择 Existing service role (现有服务角色)。在 Role ARN (角色 ARN) 中,选择服务角色。

注意

当您使用控制台创建构建项目时,您可以同时创建 CodeBuild 服务角色。默认情况下,这个角色仅能与该构建项目配合使用。如果您使用控制台将此服务角色与另一个构建项目关联,则此角色将更新以便与关联的构建项目结合使用。一个服务角色最多可与 10 个构建项目结合使用。

其他配置
超时

指定 5 到 480 分钟 (8 个小时) 之间的值,在此时间后,如果构建未完成,CodeBuild 会将其停止。如果 hoursminutes 都留空,则将使用 60 分钟的默认值。

VPC

If you want CodeBuild to work with your VPC:

  • For VPC, choose the VPC ID that CodeBuild uses.

  • For VPC Subnets, choose the subnets that include resources that CodeBuild uses.

  • For VPC Security groups, choose the security groups that CodeBuild uses to allow access to resources in the VPCs.

For more information, see 将 AWS CodeBuild 与 Amazon Virtual Private Cloud 结合使用.

计算

选择可用选项之一。

环境变量

输入名称和值,然后选择每个环境变量的类型以供构建使用。

注意

CodeBuild 会自动为您的 AWS 区域设置环境变量。如果您尚未将以下环境变量添加到 buildspec.yml 中,则必须设置这些变量:

  • AWS_ACCOUNT_ID

  • IMAGE_REPO_NAME

  • IMAGE_TAG

控制台和 AWS CLI 用户可以查看环境变量。如果您不担心环境变量的可见性,请设置 NameValue 字段,然后将 Type 设置为 Plaintext

我们建议您将具有敏感值(例如 AWS 访问密钥 ID、AWS 秘密访问密钥或密码)的环境变量作为参数存储在 Amazon EC2 Systems Manager Parameter Store 或 AWS Secrets Manager 中。

如果您使用的是 Amazon EC2 Systems Manager Parameter Store,则对于 Type (类型),选择 Parameter (参数)。对于 Name (名称),输入标识符供 CodeBuild 引用。对于 Value (值),按照 Amazon EC2 Systems Manager Parameter Store 中存储的参数名称输入参数名称。使用名为 /CodeBuild/dockerLoginPassword 的参数作为示例,对于 Type (类型),选择 Parameter (参数)。对于 Name (名称),输入 LOGIN_PASSWORD。 对于 Value (值),输入 /CodeBuild/dockerLoginPassword

重要

If you use Amazon EC2 Systems Manager Parameter Store, we recommend that you store parameters with parameter names that start with /CodeBuild/ (for example, /CodeBuild/dockerLoginPassword). You can use the CodeBuild console to create a parameter in Amazon EC2 Systems Manager. Choose Create parameter, and then follow the instructions in the dialog box. (In that dialog box, for KMS key, you can specify the ARN of an AWS KMS key in your account. Amazon EC2 Systems Manager uses this key to encrypt the parameter's value during storage and decrypt it during retrieval.) If you use the CodeBuild console to create a parameter, the console starts the parameter name with /CodeBuild/ as it is being stored. For more information, see Systems Manager Parameter Store and Systems Manager Parameter Store Console Walkthrough in the Amazon EC2 Systems Manager User Guide.

If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store, the build project's service role must allow the ssm:GetParameters action. If you chose New service role earlier, CodeBuild includes this action in the default service role for your build project. However, if you chose Existing service role, you must include this action to your service role separately.

If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store with parameter names that do not start with /CodeBuild/, and you chose New service role, you must update that service role to allow access to parameter names that do not start with /CodeBuild/. This is because that service role allows access only to parameter names that start with /CodeBuild/.

If you choose New service role, the service role includes permission to decrypt all parameters under the /CodeBuild/ namespace in the Amazon EC2 Systems Manager Parameter Store.

Environment variables you set replace existing environment variables. For example, if the Docker image already contains an environment variable named MY_VAR with a value of my_value, and you set an environment variable named MY_VAR with a value of other_value, then my_value is replaced by other_value. Similarly, if the Docker image already contains an environment variable named PATH with a value of /usr/local/sbin:/usr/local/bin, and you set an environment variable named PATH with a value of $PATH:/usr/share/ant/bin, then /usr/local/sbin:/usr/local/bin is replaced by the literal value $PATH:/usr/share/ant/bin.

Do not set any environment variable with a name that begins with CODEBUILD_. This prefix is reserved for internal use.

If an environment variable with the same name is defined in multiple places, the value is determined as follows:

  • The value in the start build operation call takes highest precedence.

  • The value in the build project definition takes next precedence.

  • The value in the buildspec declaration takes lowest precedence.

如果您使用 Secrets Manager,对于 Type (类型),请选择 Secrets Manager。对于 Name (名称),输入标识符供 CodeBuild 引用。对于 Value (值),请使用模式 reference-key 输入 secret-id:json-key:version-stage:version-id。 有关信息,请参阅Secrets Manager reference-key in the buildspec file

重要

If you use Secrets Manager, we recommend that you store secrets with names that start with /CodeBuild/ (for example, /CodeBuild/dockerLoginPassword). For more information, see What Is AWS Secrets Manager? in the AWS Secrets Manager User Guide.

If your build project refers to secrets stored in Secrets Manager, the build project's service role must allow the secretsmanager:GetSecretValue action. If you chose New service role earlier, CodeBuild includes this action in the default service role for your build project. However, if you chose Existing service role, you must include this action to your service role separately.

If your build project refers to secrets stored in Secrets Manager with secret names that do not start with /CodeBuild/, and you chose New service role, you must update the service role to allow access to secret names that do not start with /CodeBuild/. This is because the service role allows access only to secret names that start with /CodeBuild/.

If you choose New service role, the service role includes permission to decrypt all secrets under the /CodeBuild/ namespace in the Secrets Manager.

Buildspec

构建规范

执行下列操作之一:

  • 如果您的源代码包括构建规范文件,请选择 Use a buildspec file (使用构建规范文件)。默认情况下,CodeBuild 在源代码根目录中查找名为 buildspec.yml 的文件。如果您的构建规范文件使用不同的名称或位置,请在 Buildspec name (构建规范名称) 中输入源根目录的路径(例如,buildspec-two.ymlconfiguration/buildspec.yml)。 如果 buildspec 文件位于 S3 存储桶中,则它必须与构建项目位于同一 AWS 区域中。使用其 ARN 指定构建规范文件(例如,arn:aws:s3:::my-codebuild-sample2/buildspec.yml)。

  • 如果您的源代码不包括构建规范文件,或者如果您要从在源代码根目录的 buildspec.yml 文件中为 build 阶段指定的一个构建规范文件中运行构建命令,则选择 Insert build commands (插入构建命令)。对于 Build commands (构建命令),请输入您要在 build 阶段运行的命令。对于多个命令,使用 && 分开各个命令 (例如 mvn test && mvn package)。要在其他阶段运行命令,或者,如果 build 阶段对应的命令列表特别长,请将 buildspec.yml 文件添加到源代码根目录,将命令添加到该文件中,然后选择 Use the buildspec.yml in the source code root directory (在源代码根目录中使用 buildspec.yml)

有关更多信息,请参阅构建规范参考

批处理配置

您可以将一组构建作为单个操作运行。有关更多信息,请参阅 中的批量构建AWS CodeBuild

定义批处理配置

选择此项可允许此项目中的批处理构建。

批处理服务角色

为 批处理构建提供服务角色。

选择以下选项之一:

  • 如果您没有批处理服务角色,请选择 New service role (新建服务角色)。在 Service role (服务角色) 中,输入新角色的名称。

  • 如果您有批处理服务角色,请选择 Existing service role (现有服务角色)。在 Service role (服务角色) 中,选择服务角色。

批处理构建在批处理配置中引入了新的安全角色。此新角色是必需的,因为 CodeBuild 必须能够代表您调用 StartBuildStopBuildRetryBuild 操作,才能将构建作为批处理的一部分运行。客户应使用新的角色,而不是他们在构建中使用的相同角色,有两个原因:

  • 授予构建角色 StartBuildStopBuildRetryBuild 权限将允许单个构建通过 buildspec 启动更多构建。

  • CodeBuild 批处理构建提供了一些限制,用于限制可用于批处理中的构建的构建和计算类型数量。如果构建角色具有这些权限,则构建本身可能会绕过这些限制。

批处理允许的计算类型

选择批处理允许的计算类型。选择所有适用的选项。

批处理中允许的最大构建数

输入批处理中允许的最大构建数。如果某个批次超过此限制,则该批次将失败。

批处理超时

输入批量生成要完成的最长时间。

组合构件

选择 Combine all artifacts from batch to a single location (将所有构件从批处理合并到一个位置) 以将批处理中的所有构件合并到一个位置。

Artifacts

Type

执行下列操作之一:

  • 如果您不想创建任何构建输出构件,请选择 No artifacts (无构件)。如果您只运行构建测试,或者您要将 Docker 映像推送到 Amazon ECR 存储库,建议执行此操作。

  • 要将构建输出存储在 S3 存储桶中,请选择 Amazon S3,然后执行以下操作:

    • 如果要将项目名称用于构建输出 ZIP 文件或文件夹,请将 Name (名称) 留空。否则,请输入名称。(如果您要输出 ZIP 文件,并且要让 ZIP 文件包含文件扩展名,请务必在 ZIP 文件名之后添加扩展名。)

    • 如果希望构建规范文件中指定的名称覆盖控制台中指定的任何名称,请选择 Enable semantic versioning (启用语义版本控制)。构建规范文件中的名称是构建时计算得出的,使用 Shell 命令语言。例如,您可以将日期和时间附加到您的构件名称后面,以便它始终是唯一的。构件名称唯一防止覆盖构件。有关更多信息,请参阅 构建规范语法

    • 对于 Bucket name (存储桶名称),请选择输出存储桶的名称。

    • 如果您在此过程的前面部分选择了 Insert build commands (插入构建命令),那么对于 Output files (输出文件),请输入构建(该构建要放到构建输出 ZIP 文件或文件夹中)中的文件位置。对于多个位置,使用逗号分开各个位置(例如 appspec.yml, target/my-app.jar)。有关更多信息,请参阅 构建规范语法files 的描述。

    • 如果不想加密构建构件,请选择 Remove artifacts encryption (删除构件加密)

对于所需的每个辅助构件集:

  1. 对于 Artifact identifier (构件标识符),输入少于 128 个字符且仅包含字母数字字符和下划线的值。

  2. 选择 Add artifact (添加构件)

  3. 按照前面步骤的说明配置辅助构件。

  4. 选择 Save artifact (保存构件)

其他配置
加密密钥

(可选)执行以下操作之一:

  • 要使用您的账户中适用于 Amazon S3 的 AWS 托管的客户托管密钥 (CMK) 加密构建输出构件,请将 Encryption key (加密密钥) 留空。这是默认模式。

  • 要使用客户托管 CMK 加密生成输出项目,请在 Encryption key (加密密钥) 中输入 CMK 的 ARN。采用格式 arn:aws:kms:region-ID:account-ID:key/key-ID

缓存类型

For Cache type, choose one of the following:

  • If you do not want to use a cache, choose No cache.

  • If you want to use an Amazon S3 cache, choose Amazon S3, and then do the following:

    • For Bucket, choose the name of the S3 bucket where the cache is stored.

    • (Optional) For Cache path prefix, enter an Amazon S3 path prefix. The Cache path prefix value is similar to a directory name. It makes it possible for you to store the cache under the same directory in a bucket.

      重要

      Do not append a trailing slash (/) to the end of the path prefix.

  • If you want to use a local cache, choose Local, and then choose one or more local cache modes.

    注意

    Docker layer cache mode is available for Linux only. If you choose it, your project must run in privileged mode. The ARM_CONTAINER and LINUX_GPU_CONTAINER environment types and the BUILD_GENERAL1_2XLARGE compute type do not support the use of a local cache.

Using a cache saves considerable build time because reusable pieces of the build environment are stored in the cache and used across builds. For information about specifying a cache in the buildspec file, see 构建规范语法. For more information about caching, see 在 AWS CodeBuild 中构建缓存.

Logs

选择要创建的日志。您可以创建 Amazon CloudWatch Logs 和/或 Amazon S3 日志。

CloudWatch

如果要创建 Amazon CloudWatch Logs 日志:

CloudWatch 日志

选择 CloudWatch logs (CloudWatch 日志)

Group name

输入您的 Amazon CloudWatch Logs 日志组的名称。

流名称

输入您的 Amazon CloudWatch Logs 日志流名称。

S3

如果要创建 Amazon S3 日志:

S3 日志

选择 S3 logs (S3 日志)

存储桶

选择日志的 S3 存储桶的名称。

路径前缀

输入日志的前缀。

禁用 S3 日志加密

如果您不希望加密 S3 日志,请选择 。