AWS CodeBuild

用户指南 (API 版本 2016-10-06)

AWS 文档 » AWS CodeBuild » 用户指南 » 使用 CodeBuild 中的构建项目和构建 » 使用 CodeBuild 中的构建 » 在 CodeBuild 中运行构建

在 CodeBuild 中运行构建

您可以使用 AWS CodeBuild 控制台、AWS CLI 或 AWS 开发工具包运行 CodeBuild 中的构建项目。

运行构建项目 (控制台)

要使用 AWS CodePipeline 运行 CodeBuild 中的构建项目，可跳过这些步骤并按照将 AWS CodePipeline 与 CodeBuild 结合使用中的说明操作。

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

2. 执行以下操作之一：

   • 如果您刚创建完构建项目，则应显示 Build project: project-name 页面。选择 Start build。

   • 如果您之前创建了构建项目，则应在导航窗格中选择 Build projects。选择构建项目，然后选择 Start build。

3. 在 Start build (启动构建) 页面上，执行下列操作之一：

   • 对于 Amazon S3，键入与您需要生成的输入项目的版本相对应的版本 ID，作为可选的 Source version (源版本) 值。如果 Source version (源版本) 留空，则使用最新版本。

   • 对于 CodeCommit，为 Reference type (参考类型) 选择 Branch (分支)、Git tag (Git 标签) 或 Commit ID (提交 ID)。接下来，选择分支、Git 标签，也可以输入提交 ID 来指定源代码的版本。有关更多信息，请参阅 使用 CodeBuild 的源版本示例。更改 Git clone depth 的值。这会创建一个浅克隆，其历史记录会截断至指定数量的提交。如果您需要完整克隆，请选择 Full。

   • 对于 GitHub 或 GitHub Enterprise，请输入提交 ID、拉取请求 ID、分支名称或您要生成的源代码版本的标签名称，作为可选 Source version (源版本) 值。如果您要指定拉取请求 ID，则必须使用格式 pr/pull-request-ID (例如，pr/25)。如果您要指定分支名称，则将使用分支的 HEAD 提交 ID。如果 Source version 留空，则将使用默认分支的 HEAD 提交 ID。更改 Git clone depth 的值。这会创建一个浅克隆，其历史记录会截断至指定数量的提交。如果您需要完整克隆，请选择 Full。

   • 对于 Bitbucket，请输入提交 ID、分支名称或您要生成的源代码版本的标签名称作为可选 Source version (源版本) 值。如果您要指定分支名称，则将使用分支的 HEAD 提交 ID。如果 Source version 留空，则将使用默认分支的 HEAD 提交 ID。更改 Git clone depth 的值。这会创建一个浅克隆，其历史记录会截断至指定数量的提交。如果您需要完整克隆，请选择 Full。

   • 要仅对此构建使用不同的源提供商，请选择 Advanced build options (高级构建选项)。有关源提供商选项和设置的更多信息，请参阅选择源提供商。

4. 选择 Advanced build overrides (高级构建覆盖)。

   在这里，您可以仅为此构建更改设置。此部分中的设置是可选的。

   在 Source (源) 下，您可以：

   • 选择 Add source (添加源) 以添加辅助源。

   • 选择 Remove source (删除源) 以删除辅助源。

   • 使用 Source provider (源提供商) 和 Source version (源版本) 修改源的设置。

   在 Environment (环境) 下，您可以：

   • 覆盖 Environment image (环境映像)、Operating system (操作系统)、Runtime (运行时) 和 Runtime version (运行时版本) 的设置。

   • 选中或清除 Privileged (特权)。

   • 在 Service role (服务角色) 中，您可以更改 CodeBuild 用来调用从属 AWS 服务的服务角色。选择 New service role (新建服务角色) 以让 CodeBuild 为您创建服务角色。

   • 选择 Override build specification (覆盖生成规范) 来使用不同的生成规范。

   • 更改 Timeout (超时) 的值。

   • 更改 Compute (计算) 的值。

   • 从 Certificate (证书)中选择一种不同设置。

   在 Buildspec (生成规范) 下，您可以：

   • 选择 Use a buildspec file (使用构建规范文件) 以在源代码根目录中使用 buildspec.yml。

   • 选择 Insert build commands (插入生成命令) 以输入要在生成阶段运行的命令。

   在 Build Artifacts (构建构件) 下，您可以：

   • 从 Type (类型) 中，选择不同的构件类型。

   • 在 Name (名称) 中，键入不同的输出构件名称。

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

   • 在 Path (路径) 中，键入不同的输出构件路径。

   • 在 Namespace type (命名空间类型) 中，选择不同的类型。选择 Build ID (构建 ID) 将构建 ID 插入构建输出文件的路径（例如，My-Path/Build-ID/My-Artifact.zip）。否则，选择 None (无)。

   • 从 Bucket name (存储桶名称) 中，为您的输出构件选择不同的 Amazon S3 存储桶。

   • 如果不想加密构建构件，请选择 Disable artifacts encryption (禁用构件加密)。

   • 选择 Artifacts packaging (构件打包)，然后选择 Zip 以将生成构件文件放入一个压缩文件中。要将构建构件文件分别放入指定 Amazon S3 存储桶中（不压缩），则选择 None (无)。

   • 在 Cache (缓存) 下，从 Type (类型) 中，选择不同的缓存设置。

   • 仅覆盖此构建的辅助构件：

     • 要删除辅助构件，请在 Secondary artifacts (辅助构件) 中，选择辅助构件行中的 X。

     • 要添加辅助构件，请选择 Add artifact (添加构件)，然后输入辅助构件的信息。有关更多信息，请参阅创建构建项目 (控制台)中的步骤 8。

   在 Logs (日志) 下，您可以通过选中或清除 CloudWatch Logs 和 S3 logs (S3 日志) 来覆盖日志设置。

   • 如果您启用 CloudWatch logs (CloudWatch 日志)：

     • 在 Group name (组名称) 中，输入您的 Amazon CloudWatch Logs 组的名称。

     • 在 Stream name (流名称) 中，输入您的 Amazon CloudWatch Logs 流名称。

   • 如果您启用 S3 logs (S3 日志)：

     • 从 Bucket (存储桶) 中，选择您的日志的 S3 存储桶的名称。

     • 在 Path prefix (路径前缀) 中，输入您的日志的前缀。

   在 Service role (服务角色) 下，您可以更改 CodeBuild 用来调用从属 AWS 服务的服务角色。选择 Create a role (创建角色)，让 CodeBuild 为您创建一个服务角色。

5. 展开 Environment variables override (环境变量覆盖)。

   如果您需要更改环境变量 (仅针对此构建项目)，请更改 Name、Value 和 Type 的值。选择 Add environment variable (添加环境变量) 以仅为此构建添加新环境变量。选择 Remove environment variable (删除环境变量) 以删除您不想在此构建中使用的环境变量。

   其他人可以使用 CodeBuild 控制台和 AWS CLI 查看环境变量。如果您不担心环境变量的可见性，请设置 Name 和 Value 字段，然后将 Type 设置为 Plaintext。

   我们建议您将具有敏感值 (例如 AWS 访问密钥 ID、AWS 秘密访问密钥或密码) 的环境变量作为参数存储在 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。

   重要

   我们建议您将名称以 /CodeBuild/ 开头的参数（例如，/CodeBuild/dockerLoginPassword）存储在 Amazon EC2 Systems Manager Parameter Store 中。可以使用 CodeBuild 控制台在 Amazon EC2 Systems Manager 中创建参数。选择 Create a parameter (创建参数)，然后按照说明操作。（在该对话框中，对于KMS key (KMS 密钥)，您可以选择指定您的账户中的 AWS KMS 密钥的 ARN。Amazon EC2 Systems Manager 使用此密钥在存储过程中加密参数的值并在检索过程中解密参数的值。） 如果您使用 CodeBuild 控制台创建参数，控制台将在参数被存储时以 /CodeBuild/ 作为它的开头。有关更多信息，请参阅 Amazon EC2 Systems Manager 用户指南中的 Systems Manager Parameter Store 和 Systems Manager Parameter Store 控制台演练。

   如果您的构建项目引用了 Amazon EC2 Systems Manager Parameter Store 中存储的参数，则构建项目的服务角色必须允许 ssm:GetParameters 操作。如果您之前选择了 Create a service role in your account (在账户中创建服务角色)，则 CodeBuild 将自动在您的构建项目的默认服务角色中包含此操作。但是，如果您选择了 Choose an existing service role from your account，则必须将此操作单独包含在您的服务角色中。

   如果您的构建项目引用了 Amazon EC2 Systems Manager Parameter Store 中存储的名称不以 /CodeBuild/ 开头的参数，且您选择了 Create a service role in your account (在账户中创建服务角色)，则您必须更新该服务角色以允许访问不以 /CodeBuild/ 开头的参数名称。这是因为该服务角色仅允许访问以 /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_ 打头的名称设置任何环境变量。此前缀是专为内部使用预留的。

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

   • 构建操作调用开始时的值优先级最高。

   • 构建项目定义中的值优先级次之。

   • 构建规范声明中的值优先级最低。

6. 选择 Start build。

   有关此构建项目的详细信息，请参阅查看构建详细信息 (控制台)。

运行构建项目 (AWS CLI)

1. 使用以下方法之一运行 start-build 命令：

   aws codebuild start-build --project-name project-name

   如果您要运行的构建项目使用的是最新版本的构建输入项目和构建项目现有设置，请使用此方法。

   aws codebuild start-build --generate-cli-skeleton

   如果您要运行的构建项目具有早期版本的构建输入项目，或者如果您要覆盖构建输出项目、环境变量、生成规范或默认构建超时期限的设置，请使用此方法。

2. 如果您运行具有 --project-name 选项的 start-build 命令，请将 project-name 替换为构建项目的名称，然后跳至此过程中的第 6 步。要获取构建项目的列表，请参阅查看生成项目名称的列表。

3. 如果您运行带 --idempotency-token 选项的 start-build 命令，则 start-build 请求将附带区分大小写的唯一标识符或令牌。令牌在发出请求后的 12 小时内有效。如果您重复发出带相同令牌的 start-build 请求，但更改了参数，则 CodeBuild 会返回“参数不匹配”错误。

4. 如果您运行具有 --generate-cli-skeleton 选项的 start-build 命令，则采用 JSON 格式的数据将出现在输出中。将数据复制到本地计算机上或安装 AWS CLI 的实例上某位置处的文件（如 start-build.json）中。修改所复制的数据，使其符合以下格式，然后保存结果：

   {
     "projectName": "projectName",
     "sourceVersion": "sourceVersion",
     "artifactsOverride": {
       "type": "type",
       "location": "location",
       "path": "path",
       "namespaceType": "namespaceType",
       "name": "artifactsOverride-name",
       "packaging": "packaging"    
     },
     "buildspecOverride": "buildspecOverride",
     "cacheOverride": {
         "location": "cacheOverride-location",
         "type": "cacheOverride-type"
    },
     "certificateOverride": "certificateOverride",
     "computeTypeOverride": "computeTypeOverride",
     "environmentTypeOverride": "environmentTypeOverride",
     "environmentVariablesOverride": {
         "name": "environmentVariablesOverride-name",
         "value": "environmentVariablesValue",
         "type": "environmentVariablesOverride-type"
     },  
     "gitCloneDepthOverride": "gitCloneDepthOverride",
     "imageOverride": "imageOverride",
     "idempotencyToken": "idempotencyToken",
     "insecureSslOverride": "insecureSslOverride",
     "privilegedModeOverride": "privilegedModeOverride",
     "queuedTimeoutInMinutesOverride": "queuedTimeoutInMinutesOverride",           
     "reportBuildStatusOverride": "reportBuildStatusOverride",
     "timeoutInMinutesOverride": "timeoutInMinutesOverride",
     "sourceAuthOverride": "sourceAuthOverride",
     "sourceLocationOverride": "sourceLocationOverride",
     "serviceRoleOverride": "serviceRoleOverride",
     "sourceTypeOverride": "sourceTypeOverride"
   }

   替换以下占位符：

   • projectName：必需的字符串。用于此构建项目的构建项目名称。

   • sourceVersion：可选字符串。要构建的源代码版本，如下所示：

     • 对于 Amazon S3，与您需要构建的输入 ZIP 文件的版本相对应的版本 ID。如果未指定 sourceVersion，则将使用最新版本。

     • 对于 CodeCommit，与您需要构建的源代码版本相对应的提交 ID。如果未指定 sourceVersion，则将使用分支的 HEAD 提交 ID。(您无法指定 sourceVersion 标签名称，但您可以指定标签提交 ID。)

     • 对于 GitHub，指定提交 ID、拉取请求 ID、分支名称或与您要构建的源代码版本相对应的标签名称。如果指定了拉取请求 ID，则必须使用格式 pr/pull-request-ID (例如，pr/25)。如果指定了分支名称，则将使用分支的 HEAD 提交 ID。如果未指定 sourceVersion，则将使用分支的 HEAD 提交 ID。

     • 对于 Bitbucket，指定提交 ID、分支名称或与您要构建的源代码版本相对应的标签名称。如果指定了分支名称，则将使用分支的 HEAD 提交 ID。如果未指定 sourceVersion，则将使用分支的 HEAD 提交 ID。

   • 以下占位符适用于 artifactsOveride。

     • type：可选字符串。构建项目中定义覆盖此构建项目的构建输出项目类型。

     • location：可选字符串。构建项目中定义覆盖此构建项目的构建输出项目位置。

     • path：可选字符串。构建项目中定义覆盖此构建项目的构建输出项目路径。

     • namespaceType：可选字符串。构建项目中定义覆盖此构建项目的构建输出项目路径类型。

     • name：可选字符串。构建项目中定义覆盖此构建项目的构建输出项目名称。

     • packaging：可选字符串。构建项目中定义覆盖此构建项目的构建输出项目打包类型。

   • buildspecOverride：可选字符串。构建项目中定义覆盖此构建项目的生成规范声明。如果设置了该值，则它可以是内联生成规范定义，也可以是指向相对于内置 CODEBUILD_SRC_DIR 环境变量的值的替代构建规范文件的路径。

   • 以下占位符适用于 cacheOveride。

     • cacheOverride-location：可选字符串。此构建的 ProjectCache 对象的位置，该对象将覆盖构建项目中指定的 ProjectCache 对象。cacheOverride 是可选的，它采用 ProjectCache 对象。location 在 ProjectCache 对象中是必需的。

     • cacheOverride-type：可选字符串。此构建的 ProjectCache 对象的类型，该对象将覆盖构建项目中指定的 ProjectCache 对象。cacheOverride 是可选的，它采用 ProjectCache 对象。type 在 ProjectCache 对象中是必需的。

   • certificateOverride：可选字符串。此构建的证书的名称，该证书将覆盖构建项目中指定的证书。

   • environmentTypeOverride：可选字符串。此构建的容器类型，该容器类型将覆盖构建项目中指定的容器类型。当前的有效字符串为 LINUX_CONTAINER。

   • 以下占位符适用于 environmentVariablesOveride。

     • environmentVariablesOverride-name：可选字符串。构建项目中的环境变量名称，其值将会覆盖此构建项目中的相应值。

     • environmentVariablesOverride-type：可选字符串。构建项目中的环境变量类型，其值将会覆盖此构建项目中的相应值。

     • environmentVariablesValue：可选字符串。构建项目中定义的环境变量值，其值将会覆盖此构建项目中的相应值。

   • gitCloneDepthOverride：可选字符串。构建项目中 Git clone depth 的值，您希望此构建项目会覆盖其值。如果您的源类型是 Amazon S3，则不支持此值。

   • imageOverride：可选字符串。此构建的映像的名称，该映像将覆盖构建项目中指定的映像。

   • idempotencyToken：可选字符串。一个字符串，该字符串用作令牌来指定构建请求是幂等的。您可以选择任何包含 64 个或更少字符的字符串。令牌在发出 start-build 请求后的 12 小时内有效。如果您重复发出带相同令牌的 start-build 请求，但更改了参数，则 CodeBuild 会返回“参数不匹配”错误。

   • insecureSslOverride：可选的布尔值，该值指定是否覆盖构建项目中指定的不安全的 SSL 设置。不安全的 SSL 设置确定是否忽略 SSL 警告，并连接到项目源代码。此覆盖仅在构建的源为 GitHub Enterprise 时适用。

   • privilegedModeOverride：可选的布尔值。如果设置为 true，则构建将覆盖构建项目中的特权模式。

   • queuedTimeoutInMinutesOverride：可选整数，用于指定在超时前允许构建排队的分钟数。最小值为 5 分钟，最大值为 480 分钟（8 个小时）。

   • reportBuildStatusOverride：可选布尔值，指定是否向源提供商发送构建的开始和完成状态。如果使用源提供商而非 GitHub、GitHub Enterprise 或 Bitbucket 设置此项，则会引发 invalidInputException。

   • sourceAuthOverride：可选字符串。此构建的授权类型，该授权类型将覆盖构建项目中定义的授权类型。此覆盖仅在构建项目的源为 BitBucket 或 GitHub 时适用。

   • sourceLocationOverride：可选字符串。此构建的源位置，该源位置将覆盖构建项目中定义的源位置。

   • serviceRoleOverride：可选字符串。此构建的服务角色的名称，该角色将覆盖构建项目中指定的角色。

   • sourceTypeOverride：可选字符串。此构建的源输入类型，该源输入将覆盖构建项目中定义的源输入。有效字符串包括：NO_SOURCE、CODECOMMIT、CODEPIPELINE、GITHUB、S3、BITBUCKET 和 GITHUB_ENTERPRISE。

   • timeoutInMinutesOverride：可选的编号。构建项目中定义覆盖此构建项目的构建超时分钟数。

   重要

   我们建议您将具有敏感值（例如 AWS 访问密钥 ID、AWS 秘密访问密钥或密码）的环境变量作为参数存储在 Amazon EC2 Systems Manager Parameter Store 中。如果 Amazon EC2 Systems Manager Parameter Store 中存储的参数的名称以 /CodeBuild/ 开头（例如，/CodeBuild/dockerLoginPassword），则 CodeBuild 可以使用该参数。可以使用 CodeBuild 控制台在 Amazon EC2 Systems Manager 中创建参数。选择 Create a parameter (创建参数)，然后按照说明操作。（在该对话框中，对于KMS key (KMS 密钥)，您可以选择指定您的账户中的 AWS KMS 密钥的 ARN。Amazon EC2 Systems Manager 使用此密钥在存储过程中加密参数的值并在检索过程中解密参数的值。） 如果您使用 CodeBuild 控制台创建参数，控制台将在参数被存储时以 /CodeBuild/ 作为它的开头。但是，如果您使用 Amazon EC2 Systems Manager Parameter Store 控制台创建参数，则必须使用以 /CodeBuild/ 开头的参数名称，且必须将 Type (类型) 设置为 Secure String (安全字符串)。有关更多信息，请参阅 Amazon EC2 Systems Manager 用户指南中的 Systems Manager Parameter Store 和 Systems Manager Parameter Store 控制台演练。

   如果您的构建项目引用了 Amazon EC2 Systems Manager Parameter Store 中存储的参数，则构建项目的服务角色必须允许 ssm:GetParameters 操作。如果您之前选择了 Create a new service role in your account (在账户中创建新服务角色)，则 CodeBuild 将自动在您的构建项目的默认服务角色中包含此操作。但是，如果您选择了 Choose an existing service role from your account，则必须将此操作单独包含在您的服务角色中。

   您设置的环境变量将替换现有的环境变量。例如，如果 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_ 打头的名称设置任何环境变量。此前缀是专为内部使用预留的。

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

   • 构建操作调用开始时的值优先级最高。

   • 构建项目定义中的值优先级次之。

   • 构建规范声明中的值优先级最低。

   有关这些占位符的有效值的信息，请参阅创建构建项目 (AWS CLI)。有关构建项目的最新设置列表，请参阅查看生成项目的详细信息。

5. 切换到包含您刚才保存的文件的目录，然后再次运行 start-build 命令。

   aws codebuild start-build --cli-input-json file://start-build.json

6. 如果成功，与运行构建 (AWS CLI) 过程中所述内容类似的数据将出现在输出中。

要了解有关此构建项目的详细信息，请记下输出中的 id 值，然后查看查看构建详细信息 (AWS CLI)。

开始自动运行构建 (AWS CLI)

如果您的源代码存储在 GitHub 或 GitHub Enterprise 存储库中，则您可以使用 GitHub Webhook，让 AWS CodeBuild 在代码更改每次被推送到存储库时重建源代码。

运行 create-webhook 命令，如下所示：

aws codebuild create-webhook --project-name 

对于 GitHub，与以下内容类似的信息将显示在输出中：

{
  "webhook": {
    "url": "url"
  }
}

对于 GitHub Enterprise，与以下内容类似的信息将显示在输出中：

停止自动运行构建 (AWS CLI)

如果您的源代码存储在 GitHub 或 GitHub Enterprise 存储库中，则您可以设置 GitHub Webhook，让 AWS CodeBuild 在每次代码更改被推送到存储库时重建源代码。有关更多信息，请参阅开始自动运行构建 (AWS CLI)。

如果您已启用了此行为，则可以通过运行 delete-webhook 命令将其关闭，如下所示：

aws codebuild delete-webhook --project-name  

如果此命令成功，则输出中不会出现任何信息和错误。

运行构建项目 (AWS 开发工具包)

要使用 CodePipeline 运行 AWS CodeBuild 中的构建项目，可跳过这些步骤并按照将 CodePipeline 与 CodeBuild 结合使用以测试代码和运行生成中的说明操作。

有关将 CodeBuild 与 AWS 开发工具包结合使用的信息，请参阅AWS 开发工具包和工具参考。

本页内容：

• 运行构建项目 (控制台)
• 运行构建项目 (AWS CLI)
• 开始自动运行构建 (AWS CLI)
• 停止自动运行构建 (AWS CLI)
• 运行构建项目 (AWS 开发工具包)