AWS CodeBuild
用户指南 (API 版本 2016-10-06)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

在 CodeBuild 中创建构建项目

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

先决条件

回答 规划构建 中的问题。

创建构建项目 (控制台)

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

  2. 如果显示 CodeBuild 信息页面,请选择 Create build project (创建构建项目)。否则,请在导航窗格上展开 Build (构建),然后依次选择 Build projects (构建项目)Create build project (创建构建项目)

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

  4. Project configuration (项目配置) 中:

    Create build project (创建构建项目) 页面上的 Project configuration (项目配置) 中,对于 Project name (项目名称),输入此构建项目的名称。构建项目名称在您的各个 AWS 账户内必须是唯一的。您也可以包含构建项目的可选描述来帮助其他用户了解此项目的用途。

    Description (描述) 中,输入项目的可选描述。

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

    注意

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

    展开 Additional configuration (其他配置)

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

  5. Source (源) 中:

    对于 Source provider (源提供商),选择源代码提供商类型。使用下表为您的源提供商选择适当的选项:

    注意

    CodeBuild 不支持 Bitbucket 服务器。

    源提供商 Amazon S3 CodeCommit Bitbucket GitHub GitHub Enterprise

    对于 Bucket (存储桶),选择包含源代码的输入存储桶的名称。

    X

    对于 S3 object key or S3 folder (S3 对象键或 S3 文件夹),输入 ZIP 文件的名称或包含源代码的文件夹的路径。

    X

    选择 Connect using OAuth (使用 OAuth 进行连接)Connect with a Bitbucket app password (使用 Bitbucket 应用程序密码进行连接) 并按照说明与 Bitbucket 连接或重新连接。

    X

    选择 Connect using OAuth (使用 OAuth 进行连接)Connect with a GitHub personal access token (使用 GitHub 个人访问令牌进行连接) 并按照说明与 GitHub 连接(或重新连接)且授予对 AWS CodeBuild 的访问权限。

    X

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

    注意

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

    X

    Repository (存储库) 中,选择要使用的存储库。

    X

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

    X

    对于 Repository (存储库),选择是使用公共存储库还是您账户中的存储库。

    X X

    仅当您使用公共存储库时才使用 Repository URL (存储库 URL)。输入其 URL。URL 必须包含源提供商的名称。例如,Bitbucket URL 必须包含“bitbucket.org”。

    X X

    如果您的源提供商是 Amazon S3,对于 Source version (源版本),请输入代表您输入文件构建的对象的版本 ID。如果您的源提供商是 GitHub 或 GitHub Enterprise,请输入拉取请求、分支、提交 ID、标签或参考和提交 ID。如果您的源提供商是 Bitbucket,请输入分支、提交 ID、标签或参考和提交 ID。有关更多信息,请参阅 使用 CodeBuild 的源版本示例

    X X X X

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

    X X X X

    如果您希望在存储库中包含 Git 子模块,请选择 Use Git submodules (使用 Git 子模块)

    X X X X

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

    注意

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

    X X X

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

    X X X

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

    X X X

    选择 Insecure SSL (不安全的 SSL),在连接到您的 GitHub Enterprise 项目存储库时忽略 SSL 警告。

    X

    对于所需的每个辅助源:

    1. 选择 Add source (添加源)

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

    3. 对于 Source provider (源提供商),选择源代码提供商类型。使用此步骤中前面的表对辅助源提供商进行相应的选择。

  6. Environment (环境) 中:

    对于 Environment image (环境映像),执行下列操作之一:

    • 要使用由 AWS CodeBuild 托管的 Docker 映像,请选择 Managed image (托管映像),然后从 Operating system (操作系统)Runtime (运行时)Runtime version (运行时版本) 中进行相应选择。

    • 要使用其他 Docker 映像,请选择 Custom image (自定义映像)。对于 Environment type (环境类型),选择 LinuxWindows。对于 Custom image type (自定义映像类型),选择 Amazon ECROther location (其他位置)。如果您选择 Other location (其他位置),请在 Docker Hub 中按照格式 docker repository/docker image name 输入 Docker 映像的名称和标签。如果您选择 Amazon ECR,请使用 Amazon ECR repository (Amazon ECR 存储库)Amazon ECR image (Amazon ECR 映像) 在您的 AWS 账户中选择 Docker 映像。

    • 要使用私有 Docker 映像,请选择 Custom image (自定义映像)。对于 Environment type (环境类型),选择 LinuxWindows。对于 Custom image type (自定义映像类型),选择 Other location (其他位置),然后输入您私有 Docker 映像的凭证的 Amazon 资源名称 (ARN)。凭证必须由 AWS Secrets Manager 创建。有关更多信息,请参阅什么是 AWS Secrets Manager?

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

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

    Service role (服务角色) 中,执行下列操作之一:

    • 如果您没有 CodeBuild 服务角色,请选择 New service role (新建服务角色)。在 Role name (角色名称) 中,接受默认名称或输入您自己的名称。

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

    注意

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

    展开 Additional configuration (其他配置)

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

    VPC 中,执行下列操作之一:

    • 如果您没有将 VPC 用于项目,请选择 No VPC (无 VPC)

    • 如果要将 CodeBuild 与您的 VPC 结合使用:

      • 对于 VPC,选择 CodeBuild 使用的 VPC ID。

      • 对于 VPC Subnets (VPC 子网),选择包含 CodeBuild 使用的资源的子网。

      • 对于 VPC Security groups (VPC 安全组),选择 CodeBuild 用来支持对 VPC 中资源的访问的安全组。

    有关更多信息,请参阅 将 CodeBuild 与 Amazon Virtual Private Cloud 结合使用

    对于 Compute (计算),请选择一个可用选项。

    对于 Environment variables (环境变量),键入每个环境变量的名称和值,然后选择类型,以供构建使用。使用 Add environment variable (添加环境变量) 添加环境变量。

    注意

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

    • AWS_ACCOUNT_ID

    • IMAGE_REPO_NAME

    • IMAGE_TAG

    其他人可以使用 CodeBuild 控制台和 AWS CLI 查看环境变量。如果您不担心环境变量的可见性,请设置 NameValue 字段,然后将 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 parameter (创建参数),然后按照对话框中的说明操作。(在该对话框中,对于KMS key (KMS 密钥),您可以选择指定您的账户中的 AWS KMS 密钥的 ARN。Amazon EC2 Systems Manager 使用此密钥在存储过程中加密参数的值并在检索过程中解密参数的值。) 如果您使用 CodeBuild 控制台创建了一个参数,控制台将在参数名称被存储时以 /CodeBuild/ 作为它的开头。有关更多信息,请参阅 Amazon EC2 Systems Manager 用户指南中的 Systems Manager Parameter StoreSystems Manager Parameter Store 控制台演练

    如果您的构建项目引用了 Amazon EC2 Systems Manager Parameter Store 中存储的参数,则构建项目的服务角色必须允许 ssm:GetParameters 操作。如果您之前选择了 New service role (新建服务角色),则 CodeBuild 将自动在您的构建项目的默认服务角色中包含此操作。但是,如果您选择了 Existing service role (现有服务角色),则必须单独此将操作添加到您的服务角色中。

    如果您的构建项目引用了 Amazon EC2 Systems Manager Parameter Store 中存储的名称不以 /CodeBuild/ 开头的参数,且您选择了 New service role (新建服务角色),则您必须更新该服务角色以允许访问不以 /CodeBuild/ 开头的参数名称。这是因为该服务角色仅允许访问以 /CodeBuild/ 开头的参数名称。

    如果您选择 Create a service role in your account (在账户中创建服务角色),创建的服务角色将包含解密 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_ 打头的名称设置任何环境变量。此前缀是专为内部使用预留的。

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

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

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

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

  7. Buildspec (生成规范) 中:

    对于 Build specifications (生成规范),执行下列操作之一:

    • 如果您的源代码包括构建规范文件,请选择 Use a buildspec file (使用构建规范文件)

    • 如果您的源代码不包括构建规范文件,或者如果您要从在源代码根目录的 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)

    有关更多信息,请参阅 生成规范参考

  8. Artifacts (构件) 中:

    Type (类型) 中,执行下列操作之一:

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

    • 要将构建输出存储在 Amazon 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 (保存构件)

    展开 Additional configuration (其他配置)

    (可选) 对于 Encryption key,执行下列操作之一:

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

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

    对于 Cache type (缓存类型),请选择下列选项之一:

    • 如果您不想使用缓存,请选择 No cache (无缓存)

    • 如果要使用 Amazon S3 缓存,请选择 Amazon S3,然后执行以下操作:

      • 对于 Bucket (存储桶),选择存储缓存的 Amazon S3 存储桶的名称。

      • (可选)对于 Cache path prefix (缓存路径前缀),输入 Amazon S3 路径前缀。Cache path prefix (缓存路径前缀)值类似于目录名称。它使您能够在存储桶的同一目录下存储缓存。

        重要

        请勿将一个尾斜杆 (/) 附加到路径前缀后面。

    • 如果想要使用本地缓存,请选择 Local (本地),然后选择一个或多个本地缓存模式。

      注意

      Docker layer cache (Docker 层缓存) 模式仅适用于 Linux。如果您选择该模式,您的项目必须在特权模式下运行。

    使用缓存可节省大量构建时间,因为构建环境的可重用部分被存储在缓存中,并且可跨构建使用。有关在构建规范文件中指定缓存的信息,请参阅生成规范语法。有关缓存的更多信息,请参阅在 CodeBuild 中构建缓存

  9. Logs (日志) 中,选择要创建的日志。您可以创建 Amazon CloudWatch Logs 和/或 Amazon S3 日志。

    如果要创建 Amazon CloudWatch Logs 日志:

    • 选择 CloudWatch logs (CloudWatch 日志)

    • Group name (组名称) 中,输入您的 Amazon CloudWatch Logs 日志组的名称。

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

    如果要创建 Amazon S3 日志:

    • 选择 S3 logs (S3 日志)

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

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

    (可选)如果您在此过程前面的 Artifacts (构件) 部分为 Type (类型) 选择了 Amazon S3,那么对于 Artifacts packaging (构件打包),执行下列操作之一:

    • 要让 CodeBuild 创建一个包含构建输出的 ZIP 文件,请选择 Zip

    • 要让 CodeBuild 创建一个包含构建输出的文件夹,请选择 None (无)。(这是默认值。)

    • 如果您不希望加密您的 S3 日志,请选择 Remove S3 log encryption (删除 S3 日志加密)

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

  11. Review (审核) 页面上,选择 Start build (开始生成 )

创建构建项目 (AWS CLI)

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

  1. 运行 create-project 命令:

    aws codebuild create-project --generate-cli-skeleton

    输出中将显示 JSON 格式的数据。将数据复制到本地计算机上或安装 AWS CLI 的实例上某位置处的文件(如 create-project.json)中。按照下面所示修改复制的数据,并保存您的结果。

    { "name": "project-name", "description": "description", "source": { "type": "source-type", "location": "source-location", "gitCloneDepth": "gitCloneDepth", "buildspec": "buildspec", "InsecureSsl": "InsecureSsl", "reportBuildStatus": reportBuildStatus", "gitSubmodulesConfig": { "fetchSubmodules": "fetchSubmodules" }, "auth": { "type": "auth-type", "resource": "resource" } }, ”sourceVersion”: “source-version”, “secondarySourceVersions”: { “sourceIdentifier”: ”secondary-source-identifier”, “sourceVersion”: ”secondary-source-version” }, "artifacts": { "type": "artifacts-type", "location": "artifacts-location", "path": "path", "namespaceType": "namespaceType", "name": "artifacts-name", "overrideArtifactName": "override-artifact-name", "packaging": "packaging" }, "cache": { "type": "cache-type", "location": "cache-location", "mode": [ "cache-mode" ] }, "logsConfig": { "cloudWatchLogs": { "status": "cloudwatch-logs-status", "groupName": "group-name", "streamName": "stream-name" } "s3Logs": { "status": "s3-logs-status", "location": "s3-logs-location", "encryptionDisabled": "s3-logs-encryptionDisabled" } } "secondaryArtifacts": [ { "type": "artifacts-type", "location": "artifacts-location", "path": "path", "namespaceType": "namespaceType", "name": "artifacts-name", "packaging": "packaging", "artifactIdentifier": "artifact-identifier" } ] , "secondarySources": [ { "type": "source-type", "location": "source-location", "gitCloneDepth": "gitCloneDepth", "buildspec": "buildspec", "InsecureSsl": "InsecureSsl", "reportBuildStatus": "reportBuildStatus", "auth": { "type": "auth-type", "resource": "resource" }, "sourceIdentifier": "source-identifier" } ], "serviceRole": "serviceRole", "vpcConfig": { "securityGroupIds": [ "security-group-id" ], "subnets": [ "subnet-id" ], "vpcId": "vpc-id" }, "timeoutInMinutes": timeoutInMinutes, "encryptionKey": "encryptionKey", "tags": [ { "key": "tag-key", "value": "tag-value" } ], "environment": { "type": "environment-type", "image": "image", "computeType": "computeType", "certificate": "certificate", "environmentVariables": [ { "name": "environmentVariable-name", "value": "environmentVariable-value", "type": "environmentVariable-type" } ], "registryCredential": [ { "credential": "credential-arn-or-name", "credentialProvider": "credential-provider" } ], "imagePullCredentialsType": "imagePullCredentialsType-value, "privilegedMode": "privilegedMode" }, "badgeEnabled": "badgeEnabled" }

    替换以下内容:

    • project-name:必填值。此构建项目的名称。此名称在您的 AWS 账户的所有构建项目中必须是唯一的。

    • description:可选值。此构建项目的描述。

    • 对于必填的 source 对象,则为有关此构建项目的源代码设置的信息。添加 source 对象后,可以使用 CodeBuild secondarySources 对象添加最多 12 个源。这些设置包括:

      • source-type:必填值。包含要构建的源代码的存储库的类型。有效值包括 CODECOMMITCODEPIPELINEGITHUBGITHUB_ENTERPRISEBITBUCKETS3NO_SOURCE。如果您使用 NO_SOURCE,则 buildspec 不能是文件,因为项目没有源。相反,您必须使用 buildspec 属性为 buildspec 指定 YAML 格式的字符串。有关更多信息,请参阅 无源项目示例

      • source-location:必填值 (除非您将 source-type 设置为 CODEPIPELINE)。指定存储库类型的源代码的位置。

        • 对于 CodeCommit,则为指向包含源代码和生成规范的存储库的 HTTPS 克隆 URL(例如,https://git-codecommit.region-id.amazonaws.com/v1/repos/repo-name)。

        • 对于 Amazon S3,则为生成输入存储桶名称,后跟正斜杠 (/),再加上包含源代码和生成规范的 ZIP 文件的名称(例如,bucket-name/object-name.zip)。此时假定 ZIP 文件在构建输入存储桶的根目录中。(如果 ZIP 文件在存储桶内的文件夹中,请改用 bucket-name/path/to/object-name.zip。)

        • 对于 GitHub,则为指向包含源代码和生成规范的存储库的 HTTPS 克隆 URL。该 URL 必须包含“github.com”。 您必须将您的 AWS 账户连接到您的 GitHub 账户。为此,请使用 CodeBuild 控制台创建构建项目。

          1. 当您使用控制台与 GitHub 连接(或重新连接)时,在 Authorize application (授权应用程序) 页面上,对于 Organization access (组织访问权限),选择您希望 CodeBuild 能够访问的每个存储库旁边的 Request access (请求访问权限)

          2. 选择 Authorize application。(在连接到您的 GitHub 账户后,您不需要完成构建项目的创建。可以关闭 CodeBuild 控制台。)

        • 对于 GitHub Enterprise,则为指向包含源代码和生成规范的存储库的 HTTP 或 HTTPS 克隆 URL。您还必须将您的 AWS 账户连接到您的 GitHub Enterprise 账户。为此,请使用 CodeBuild 控制台创建构建项目。

          1. 在 GitHub Enterprise 中创建个人访问令牌。

          2. 将此令牌复制到您的剪贴板,以便在创建 CodeBuild 项目时使用。有关更多信息,请参阅 GitHub 帮助网站上的在 GitHub Enterprise 中创建个人访问令牌

          3. 如果您使用控制台创建 CodeBuild 项目,请在 Source (源) 中为 Source provider (源提供商) 选择 GitHub Enterprise

          4. 对于 Personal Access Token,请粘贴已复制到剪贴板中的令牌。选择 Save Token。您的 CodeBuild 账户现在已与您的 GitHub Enterprise 账户连接。

        • 对于 Bitbucket,则为指向包含源代码和生成规范的存储库的 HTTPS 克隆 URL。该 URL 必须包含“bitbucket.org”。 您还必须将您的 AWS 账户连接到您的 Bitbucket 账户。为此,请使用 CodeBuild 控制台创建构建项目。

          1. 当您使用控制台与 Bitbucket 连接 (或重新连接) 时,在 Bitbucket Confirm access to your account 页面上,选择 Grant access。(在连接到您的 Bitbucket 账户后,您不需要完成构建项目的创建。可以关闭 CodeBuild 控制台。)

        • 对于 AWS CodePipeline,请勿为 source 指定 location 值。CodePipeline 会忽略该值,因为当您在 CodePipeline 中创建管道时,您会在管道的源阶段指定源代码位置。

      • gitCloneDepth:可选值。要下载的历史记录深度。最小值为 0。如果此值为 0、大于 25 或未提供,则会下载每个构建项目的完整历史记录。如果您的源类型是 Amazon S3,则不支持此值。

      • buildspec:可选值。要使用的生成规范定义或文件。如果设置了该值,则它可以是内联生成规范定义,也可以是指向相对于内置 CODEBUILD_SRC_DIR 环境变量的值的替代构建规范文件的路径。如果此值未提供,或设置为空字符串,则源代码必须在其根目录中添加 buildspec.yml 文件。有关更多信息,请参阅构建规范文件名称和存储位置

      • auth:此对象仅由 CodeBuild 控制台使用。不要为 auth-type(除非 source-type 设置为 GITHUB)或 resource 指定值。

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

      • gitSubmodulesConfig:可选值。有关 Git 子模块配置的信息。只能与 CodeCommit、GitHub、GitHub Enterprise 和 Bitbucket 一起使用。如果您希望在存储库中包含 Git 子模块,请将 fetchSubmodules 设置为 true。包含的 Git 子模块必须配置为 HTTPS。

      • InsecureSsl:可选值。仅用于 GitHub Enterprise。将此值设为 true,将在连接到您的 GitHub Enterprise 项目存储库时忽略 SSL 警告。默认值为 falseInsecureSsl 应当仅用于测试目的。它不应在生产环境中使用。

    • source-version:可选值。要为此项目构建的构建输入的版本。如果未指定,则使用最新版本。如果已指定,则它必须是下列项之一:

      • 对于 CodeCommit:要使用的提交 ID。

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

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

      • 对于 Amazon Simple Storage Service (Amazon S3):表示要使用的构建输入 ZIP 文件的对象的版本 ID。

      如果在构建级别指定 sourceVersion,则该版本将优先于此 sourceVersion(在对象级别)。有关更多信息,请参阅 使用 CodeBuild 的源版本示例

    • secondarySourceVersions:可选值。projectSourceVersion 数据元数组。如果在构建级别指定 secondarySourceVersions,则它们优先于此对象。

      • secondary-source-identifier:构建项目中源的标识符。

      • secondary-source-version:一个 sourceVersion 对象。

    • 对于必填的 artifacts 对象,则为有关此构建项目的输出项目设置的信息。添加 artifacts 对象后,可以使用 CodeBuild secondaryArtifacts 对象添加最多 12 个构件。这些设置包括:

      • artifacts-type:必填值。生成输出项目的类型。有效值包括 CODEPIPELINENO_ARTIFACTSS3

      • artifacts-location:必填值 (除非您将 artifacts-type 设置为 CODEPIPELINENO_ARTIFACTS)。构建输出项目的位置:

        • 如果您为 artifacts-type 指定了 CODEPIPELINE,请勿为 artifacts 指定 location

        • 如果您为 artifacts-type 指定了 NO_ARTIFACTS,请勿为 artifacts 指定 location

        • 如果您为 artifacts-type 指定了 S3,那么这就是您在先决条件中创建或标识的输出存储桶的名称。

      • path:可选值。构建输出 ZIP 文件或文件夹的路径和名称:

        • 如果您为 artifacts-type 指定了 CODEPIPELINE,那么请勿为 artifacts 指定 path

        • 如果您为 artifacts-type 指定了 NO_ARTIFACTS,请勿为 artifacts 指定 path

        • 如果您为 artifacts-type 指定了 S3,那么这就是 artifacts-location 内指向构建输出 ZIP 文件或文件夹的路径。如果您没有为 path 指定值,那么 CodeBuild 将使用 namespaceType(如果指定)和 artifacts-name 来决定构建输出 ZIP 文件或文件夹的路径和名称。例如,如果您为 path 指定 MyPath,并为 artifacts-name 指定 MyArtifact.zip,那么路径和名称将为 MyPath/MyArtifact.zip

      • namespaceType:可选值。构建输出 ZIP 文件或文件夹的路径和名称:

        • 如果您为 artifacts-type 指定了 CODEPIPELINE,请勿为 artifacts 指定 namespaceType

        • 如果您为 artifacts-type 指定了 NO_ARTIFACTS,请勿为 artifacts 指定 namespaceType

        • 如果您为 artifacts-type 指定了 S3,则有效值包括 BUILD_IDNONE。使用 BUILD_ID 将构建 ID 插入到构建输出 ZIP 文件或文件夹的路径中。否则,请使用 NONE。如果您没有为 namespaceType 指定值,那么 CodeBuild 将使用 path(如果指定)和 artifacts-name 来决定构建输出 ZIP 文件或文件夹的路径和名称。例如,如果您为 path 指定 MyPath,为 namespaceType 指定 BUILD_ID,并为 artifacts-name 指定 MyArtifact.zip,那么路径和名称将为 MyPath/build-ID/MyArtifact.zip

      • artifacts-name:必填值 (除非您将 artifacts-type 设置为 CODEPIPELINENO_ARTIFACTS)。构建输出 ZIP 文件或文件夹的路径和名称:

        • 如果您为 artifacts-type 指定了 CODEPIPELINE,请勿为 artifacts 指定 name

        • 如果您为 artifacts-type 指定了 NO_ARTIFACTS,请勿为 artifacts 指定 name

        • 如果您为 artifacts-type 指定了 S3,那么这就是 artifacts-location 内构建输出 ZIP 文件或文件夹的名称。例如,如果您为 path 指定 MyPath,并为 artifacts-name 指定 MyArtifact.zip,那么路径和名称将为 MyPath/MyArtifact.zip

      • override-artifact-name:可选的布尔值。如果设置为 true,在构建规范文件的 artifacts 块中指定的名称将覆盖 artifacts-name。有关更多信息,请参阅适用于 CodeBuild 的生成规范参考

      • packaging:可选值。要创建的构建输出项目的类型:

        • 如果您为 artifacts-type 指定了 CODEPIPELINE,请勿为 artifacts 指定 packaging

        • 如果您为 artifacts-type 指定了 NO_ARTIFACTS,请勿为 artifacts 指定 packaging

        • 如果您为 artifacts-type 指定了 S3,则有效值包括 ZIPNONE。要创建包含构建输出的 ZIP 文件,请使用 ZIP。要创建包含构建输出的文件夹,请使用 NONE。默认值为 NONE

    • 对于必填的 cache 对象,则为有关此构建项目的缓存设置的信息。有关信息,请参阅构建缓存。这些设置包括:

      • cache-type:必填值。有效值为 S3NO_CACHELOCAL_CACHE

      • cache-location:仅当您将 CacheType 设置为 S3 时为必填值。如果您为 CacheType 指定了 Amazon S3,则这是 Amazon S3 存储桶的 ARN 以及路径前缀。例如,如果您的 Amazon S3 存储桶名称为 my-bucket,且您的路径前缀为 build-cache,则您的 CacheLocation可接受的格式为 my-bucket/build-cachearn:aws:s3:::my-bucket/build-cache

      • cache-mode:您将 CacheType 设置为 LOCAL 时的必需值。您可以指定以下一种或多种本地缓存模式:LOCAL_SOURCE_CACHELOCAL_DOCKER_LAYER_CACHELOCAL_CUSTOM_CACHE

        注意

        LOCAL_DOCKER_LAYER_CACHE 模式仅适用于 Linux。如果您选择该模式,您的项目必须在特权模式下运行。

    • 对于 logsConfig 对象,则为有关此构建的日志所在位置的信息:

      • cloudwatch-logs-status:必填值。有效值为 ENABLEDDISABLED。如果其值为 ENABLED,则以下值是必需的。有关更多信息,请参阅使用日志组和日志流

      • group-name:CloudWatch Logs 组的名称。

      • stream-name:CloudWatch Logs 流的名称。

      • s3-logs-status:必填值。有效值为 ENABLEDDISABLED

      • s3-logs-location:如果 s3-logs-statusENABLED,则为必填值。这是 ARN 和路径前缀的 S3 存储桶。例如,如果您的 Amazon S3 存储桶名称为 my-bucket,且您的路径前缀为 build-log,则您的 s3-logs-location 可接受的格式为 my-bucket/build-logarn:aws:s3:::my-bucket/build-log

      • s3-logs-encryptionDisabled:可选的布尔值。如果设置为 true,则您的 S3 构建日志输出将不会加密。默认情况下,S3 构建日志将会加密。

    • 对于可选的 secondaryArtifacts 对象,则为构建项目的辅助构件的设置信息。最多可以添加 12 个辅助构件。secondaryArtifacts 使用的许多设置与 CodeBuild 构件对象 对象相同。设置为:

    • 对于可选的 secondarySources 对象,则为构建项目的辅助源的设置信息。最多可以添加 12 个 secondarySourcessecondarySources 对象使用的许多设置与 CodeBuild 源对象相同。它们包括:

    • serviceRole:必填值。CodeBuild 代表 IAM 用户用来与服务进行交互的服务角色 ARN(例如,arn:aws:iam::account-id:role/role-name)。

    • 对于可选的 vpcConfig 对象,则为有关 VPC 配置的信息。这些设置包括:

      • vpcId:必填值。CodeBuild 使用的 VPC ID。运行以下命令获取您的区域中所有 Amazon VPC ID 的列表:

        aws ec2 describe-vpcs
      • subnets:必填值。包含 CodeBuild 使用的资源的子网 ID。运行以下命令获取这些 ID:

        aws ec2 describe-subnets --filters "Name=vpc-id,Values=<vpc-id>" --region us-east-1

        注意

        如果您使用的是 us-east-1 以外的区域,请确保在运行命令时使用它。

      • securityGroupIds:必填值。CodeBuild 用来支持对 VPC 中的资源的访问的安全组 ID。运行以下命令获取这些 ID:

        aws ec2 describe-security-groups --filters "Name=vpc-id,Values=<vpc-id>" --region us-east-1

        注意

        如果您使用的是 us-east-1 以外的区域,请确保在运行命令时使用它。

    • 对于必填的 environment 对象,则为有关此项目的构建环境设置的信息。这些设置包括:

      • environment-type:必填值。构建环境的类型。有效值为 LINUX_CONTAINERWINDOWS_CONTAINER

      • image:必填值。此构建环境使用的 Docker 镜像标识符。通常,此标识符以 image-name:tag 的形式表示。例如,在 CodeBuild 用来管理其 Docker 镜像的 Docker 存储库中,这可能是 aws/codebuild/standard:2.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。有关更多信息,请参阅 CodeBuild 提供的 Docker 镜像

      • computeType:必填值。与此构建环境使用的 CPU 内核数和内存容量相对应的类别。允许的值包括 BUILD_GENERAL1_SMALLBUILD_GENERAL1_MEDIUMBUILD_GENERAL1_LARGE

      • certificate:可选值。S3 存储桶的 ARN、路径前缀和包含 PEM 编码证书的对象键。对象键可以仅为 .pem 文件,也可以为包含 pem 编码证书的 .zip 文件。例如,如果您的 Amazon S3 存储桶名称是 my-bucket,路径前缀是 cert,对象键名称是 certificate.pem,则您的证书的可接受格式为 my-bucket/cert/certificate.pem 或 arn:aws:s3:::my-bucket/cert/certificate.pem。

      • 对于可选 environmentVariables 数组,则为有关您要为此构建环境指定的任何环境变量的信息。每个环境变量都以包含 environmentVariable-nameenvironmentVariable-valueenvironmentVariable-typenamevaluetype 的对象形式表示。

        其他人可以使用 CodeBuild 控制台和 AWS CLI 查看环境变量。如果您不担心环境变量的可见性,请设置 environmentVariable-nameenvironmentVariable-value,然后将 environmentVariable-type 设置为 PLAINTEXT

        我们建议您将具有敏感值(例如 AWS 访问密钥 ID、AWS 秘密访问密钥或密码)的环境变量作为参数存储在 Amazon EC2 Systems Manager Parameter Store 中。对于 environmentVariable-name,请为该存储的参数设置一个标识符以供 CodeBuild 引用。对于 environmentVariable-value,按照 Amazon EC2 Systems Manager Parameter Store 中存储的参数名称设置参数名称。将 environmentVariable-type 设置为 PARAMETER_STORE。使用名为 /CodeBuild/dockerLoginPassword 的参数作为示例,将 environmentVariable-name 设置为 LOGIN_PASSWORD。将 environmentVariable-value 设置为 /CodeBuild/dockerLoginPassword。将 environmentVariable-type 设置为 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_ 打头的名称设置任何环境变量。此前缀是专为内部使用预留的。

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

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

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

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

      • 使用可选的 registryCredential 来指定有关提供私有 Docer 镜像仓库访问权的凭证的信息。

        • credential-arn-or-name:指定使用 AWS Managed Services 创建的凭证的 ARN 或名称。​仅当凭证存在于您的当前区域中时,您才能使用凭证的名称。

        • credential-provider:目前唯一有效的值是 SECRETS_MANAGER

        当设置此属性时:

        • imagePullCredentials 必须设置为 SERVICE_ROLE

        • 映像不能为辅助映像或 Amazon ECR 映像。

      • imagePullCredentialsType-value:可选值。CodeBuild 用于在您的生成中拉取映像的凭证的类型。有两个有效值:

        • CODEBUILD 指定 CodeBuild 使用其自己的证书。这要求您修改您的 Amazon ECR 存储库策略以信任 CodeBuild 服务委托人。

        • SERVICE_ROLE 指定 CodeBuild 使用您的生成项目的服务角色。

        当您使用跨账户或专用镜像仓库镜像时,必须使用 SERVICE_ROLE 凭证。当您使用 CodeBuild 精选镜像时,必须使用 CODEBUILD 凭证。

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

        - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay& - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done"
    • badgeEnabled:可选值。要在您的 CodeBuild 项目中包含构建徽章,您必须指定值为 truebadgeEnabled。有关更多信息,请参阅使用 CodeBuild 构建徽章示例

    • timeoutInMinutes:可选值。5 到 480 分钟 (8 个小时) 之间的一个分钟数,在此时间后,如果构建未完成,CodeBuild 会将其停止。如果未指定,则使用默认值 60。要确定 CodeBuild 是否以及何时因超时而停止生成,请运行 batch-get-builds 命令。要确定构建是否已停止,请在输出中查看 buildStatus 的值是否为 FAILED。要确定构建何时超时,请在输出中查看与 TIMED_OUTphaseStatus 值关联的 endTime 值。

    • encryptionKey:可选值。CodeBuild 用来加密构建输出的 AWS KMS 客户主密钥 (CMK) 的别名或 ARN。如果您指定别名,请使用格式 arn:aws:kms:region-ID:account-ID:key/key-ID,或者,如果存在别名,请使用格式 alias/key-alias。如果未指定,则会使用适用于 Amazon S3 的 AWS 托管 CMK。

    • 对于可选的 tags 数组,则为有关您希望与此构建项目关联的任何标签的信息。您最多可指定 50 个标签。这些标签可由支持 CodeBuild生成项目标签的任何 AWS 服务使用。每个标签都以包含 tag-keytag-valuekeyvalue 值的对象形式表示。

    有关示例,请参阅创建构建项目 (AWS CLI)

  2. 切换到包含您刚才保存的文件的目录,然后再次运行 create-project 命令:

    aws codebuild create-project --cli-input-json file://create-project.json
  3. 如果成功,输出中将显示与以下内容类似的数据:

    { "project": { "name": "project-name", "description": "description", "serviceRole": "serviceRole", "tags": [ { "key": "tags-key", "value": "tags-value" } ], "artifacts": { "namespaceType": "namespaceType", "packaging": "packaging", "path": "path", "type": "artifacts-type", "location": "artifacts-location", "name": "artifacts-name" }, "lastModified": lastModified, "timeoutInMinutes": timeoutInMinutes, "created": created, "environment": { "computeType": "computeType", "image": "image", "type": "environment-type", "environmentVariables": [ { "name": "environmentVariable-name", "value": "environmentVariable-value", "type": "environmentVariable-type" } ] }, "source": { "type": "source-type", "location": "source-location", "buildspec": "buildspec", "auth": { "type": "auth-type", "resource": "resource" } }, "encryptionKey": "encryptionKey", "arn": "arn" } }
    • project 对象包含有关新构建项目的信息:

      • lastModified 值表示有关构建项目的信息上次更改的时间,采用 Unix 时间格式。

      • created 值表示构建项目的创建时间,采用 Unix 时间格式。

      • arn 值表示构建项目的 ARN。

注意

您稍后可以更改构建项目的任何设置,但构建项目名称除外。有关更多信息,请参阅更改构建项目的设置 (AWS CLI)

要开始运行构建,请参阅 运行构建项目 (AWS CLI)

如果您的源代码存储在 GitHub 存储库中,并且您希望 CodeBuild 在每次代码更改被推送到存储库时重建源代码,请参阅开始自动运行构建 (AWS CLI)

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

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

创建构建项目 (AWS CloudFormation)

有关将 AWS CodeBuild 与 AWS CloudFormation 结合使用的信息,请参阅 AWS CloudFormation 用户指南中的 CodeBuild 的 AWS CloudFormation 模板