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

运行构建 (AWS CLI)

注意

要使用 CodePipeline 运行 AWS CodeBuild 中的构建项目,可跳过这些步骤并按照创建使用 CodeBuild 的管道 (AWS CLI)中的说明操作。

有关将 AWS CLI 与 CodeBuild 结合使用的更多信息,请参阅命令行参考

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

    aws codebuild start-build --project-name <project-name>

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

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

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

  2. 如果您运行带 start-build 选项的 --project-name 命令,请替换 <project-name> 替换为构建项目的名称,然后跳到此过程的步骤 6。要获取构建项目的列表,请参阅 查看构建项目名称的列表

  3. 如果您运行带 start-build 选项的 --idempotency-token 命令,则 start-build 请求将附带区分大小写的唯一标识符或令牌。令牌在发出 请求后的 5 分钟内有效。如果您重复发出带相同令牌的 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 环境变量的值的替代构建规范文件的路径,或者是指向 S3 存储桶的路径。S3 存储桶必须与构建项目位于同一 AWS 区域中。使用其 ARN 指定构建规范文件(例如,arn:aws:s3:::my-codebuild-sample2/buildspec.yml)。如果此值未提供或设置为空字符串,源代码必须在其根目录中包含 buildspec.yml 文件。有关更多信息,请参阅构建规范文件名称和存储位置

    • 以下占位符适用于 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 请求后的 5 分钟内有效。如果您重复发出带相同令牌的 start-build 请求,但更改了参数,则 CodeBuild 会返回“参数不匹配”错误。

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

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

    • queuedTimeoutInMinutesOverride:可选整数,指定允许构建在超时前排队的分钟数。最小值为 5 分钟,最大值为 480 分钟(8 个小时)。

    • reportBuildStatusOverride:可选的布尔值,指定是否向源提供商发送构建的开始和完成状态。如果您使用 GitHub、GitHub Enterprise Server 或 Bitbucket 以外的源提供程序设置此项,则会引发 invalidInputException。

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

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

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

    • sourceTypeOverride:可选字符串。此构建的源输入类型,该源输入将覆盖构建项目中定义的源输入。有效字符串为 NO_SOURCECODECOMMITCODEPIPELINEGITHUBS3BITBUCKETGITHUB_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 (安全字符串)。有关更多信息,请参阅 AWS Systems Manager Parameter StoreWalkthrough:。 用户指南 中的创建并测试字符串参数(控制台)Amazon EC2 Systems Manager。

    如果您的构建项目引用了 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. 如果成功,与运行构建 过程中所述内容类似的数据将出现在输出中。

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