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

CodeBuild 的 GitHub 拉取请求和 Webhook 筛选示例

当源存储库为 GitHub 时,AWS CodeBuild 支持 Webhook。这意味着,对于将源代码存储在 GitHub 存储库中的 CodeBuild 构建项目,Webhook 使 CodeBuild 能够在每次代码更改推送到该存储库时重新构建源代码。

注意

我们建议您使用筛选条件组来指定哪些 GitHub 用户可以在公共存储库中触发构建。这可以防止用户触发意外的构建。有关更多信息,请参阅 筛选 GitHub Webhook 事件

创建将 GitHub 作为源存储库的构建项目并启用 Webhooks (控制台)

  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 账户内必须是唯一的。您也可以包含构建项目的可选描述来帮助其他用户了解此项目的用途。

  5. Source (源) 中,对于 Source provider (源提供商),选择 GitHub。按照说明与 GitHub 连接(或重新连接),然后选择 Authorize (授权)

    选择 Repository in my GitHub account (我的 GitHub 账户中的存储库)

    GitHub repository (GitHub 存储库) 中输入您的 GitHub 存储库的 URL。

  6. Primary source webhook events (主要源 Webhook 事件) 中,选择 Rebuild every time a code change is pushed to this repository (每次将代码更改推送到此存储库时都会重新生成)。仅当您已选中 Repository in my account (我的账户中的存储库) 时才选中此复选框。

  7. 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?

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

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

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

    注意

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

  9. 对于 Buildspec,执行以下操作之一:

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

    • 选择 Insert build commands (插入构建命令) 以使用控制台插入构建命令。

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

  10. Artifacts (构件) 中,对于 Type (类型),执行以下操作之一:

    • 如果您不想创建任何构建输出项目,请选择 No artifacts (无构件)

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

      • 如果要将项目名称用于构建输出 ZIP 文件或文件夹,请将 Name (名称) 留空。否则,请输入名称。默认情况下,构件名称是项目名称。如果您要使用其他名称,请在构件名称框中输入该名称。如果您要输出 ZIP 文件,请包含 zip 扩展名。

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

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

  11. 展开 Additional configuration (其他配置) 并根据需要设置选项。

  12. 选择 Create build project (创建构建项目)。在 Review (审核) 页面上,选择 Start build (启动构建) 以运行构建。

验证检查

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

  2. 在导航窗格中,选择 Build projects

  3. 执行以下操作之一:

    • 选择带有要验证的 Webhook 的构建项目的链接,然后选择 Build details (构建详细信息)

    • 选择带有要验证的 Webhook 的构建项目旁边的按钮,选择 View details (查看详细信息),然后选择 Build details (构建详细信息)

  4. Source (源) 中,选择 Webhook URL 链接。

  5. 在您的 GitHub 存储库中,在 Settings (设置) 页面上的 Webhooks 下,确认已选中 Pull Requests (拉取请求)Pushes (推送)

  6. 在您的 GitHub 配置文件设置中的 Personal settings (个人设置)Applications (应用程序)Authorized OAuth Apps (已授权 OAuth 应用程序) 下,您应该会看到已获得授权的 AWS CodeBuild 区域。

筛选 GitHub Webhook 事件

您可以使用 Webhook 筛选条件组来指定哪些 GitHub Webhook 事件将触发构建。例如,您可以指定仅为指定的分支触发构建。

注意

筛选条件组在 GitHub 和 GitHub Enterprise 中的工作方式相同。

您可以创建一个或多个 Webhook 筛选条件组,以指定哪些 Webhook 事件触发构建。如果一个或多个筛选条件组上的所有筛选条件都评估为 True,则会触发构建。创建筛选条件组时,应指定:

  • 事件。对于 GitHub,您可以选择以下一个或多个事件:PUSHPULL_REQUEST_CREATEDPULL_REQUEST_UPDATEDPULL_REQUEST_REOPENEDPULL_REQUEST_MERGED。webhook 事件类型在 webhook 负载中的 X-GitHub-Event 标头中。在 X-GitHub-Event 标头中,您可能会看到 pull_requestpush。对于拉取请求事件,类型在 webhook 事件负载的 action 字段中。下表显示了 X-GitHub-Event 标头值和 webhook 拉取请求负载 action 字段值如何映射到可用的事件类型。

    X-GitHub-Event 标头值 Webhook 事件负载 action Event type
    pull_request opened PULL_REQUEST_CREATED
    pull_request reopened PULL_REQUEST_REOPENED
    pull_request synchronize PULL_REQUEST_UPDATED
    pull_request closed,并且 merged 字段为 true PULL_REQUEST_MERGED
    push 不适用 PUSH

    注意

    PULL_REQUEST_REOPENED 事件类型可与 GitHub 和 GitHub Enterprise 结合使用。

  • 一个或多个可选筛选条件。使用正则表达式来指定筛选条件。对于触发构建的事件,与其关联的每个筛选条件都必须评估为 True。

    • ACTOR_ACCOUNT_ID(控制台中的 ACTOR_ID):当 GitHub 或 GitHub Enterprise 账户 ID 与正则表达式模式匹配时,Webhook 事件会触发构建。此值在 webhook 负载中的 sender 对象的 id 属性中。

    • HEAD_REF:当头部引用与正则表达式模式(例如 refs/heads/branch-namerefs/tags/tag-name)匹配时,Webhook 事件会触发构建。对于推送事件,引用名称在 Webhook 负载中的 ref 属性中。对于拉取请求事件,分支名称在 Webhook 负载中的 head 对象的 ref 属性中。

    • BASE_REF:当基本引用与正则表达式模式(例如 refs/heads/branch-name)匹配时,Webhook 事件会触发构建。BASE_REF 筛选器只能与拉取请求事件一起使用。分支名称在 webhook 负载中的 base 对象的 ref 属性中。

    • FILE_PATH:当更改的文件的路径与正则表达式模式匹配时,Webhook 会触发构建。FILE_PATH 筛选器只能与 GitHub 和 GitHub Enterprise 推送事件一起使用。

注意

您可以在 GitHub 存储库的 webhook 设置中找到 webhook 负载。

筛选 GitHub Webhook 事件(控制台)

使用 AWS Management Console 筛选 Webhook 事件:

  1. 创建项目时,选择 Rebuild every time a code change is pushed to this repository (每次将代码更改推送到此存储库时都会重新生成)

  2. Event type (事件类型) 中,选择一个或多个事件。

  3. 要在事件触发构建时进行筛选,请在 Start a build under these conditions (在这些条件下启动构建) 下,添加一个或多个可选筛选条件。

  4. 要在未触发事件时进行筛选,请在 Start a build under these conditions (在这些条件下不启动构建) 下,添加一个或多个可选筛选条件。

  5. 选择 Add filter group (添加筛选条件组) 以添加另一个筛选条件组。

有关更多信息,请参阅 AWS CodeBuild API 参考 中的创建构建项目 (控制台)WebhookFilter

在此示例中,Webhook 筛选条件组仅针对拉取请求触发构建:

以两个 Webhook 筛选条件组为例,当一个或两个筛选条件评估为 True 时触发构建:

  • 第一个筛选条件组使用与正则表达式 ^refs/heads/master$ 匹配的 Git 引用名称以及与 ^refs/heads/branch1$ 匹配的头部引用,指定在分支上创建、更新或重新打开的拉取请求。

  • 第二个筛选条件组使用与正则表达式 ^refs/heads/branch1$ 匹配的 Git 引用名称,指定分支上的推送请求。

在此示例中,Webhook 筛选条件组会针对除标记事件之外的所有请求触发构建。

在此示例中,仅当名称与正则表达式 ^buildspec.* 匹配的文件发生更改时,Webhook 筛选条件组才会触发构建。

在此示例中,只有当其账户 ID 与正则表达式 actor-account-id 匹配的指定 GitHub 或 GitHub Enterprise 用户进行更改时,Webhook 筛选条件组才会触发构建。

注意

有关如何查找您的 GitHub 账户 ID 的信息,请参阅 https://api.github.com/users/user-name,其中 user-name 是您的 GitHub 用户名。

筛选 GitHub Webhook 事件(开发工具包)

要使用 AWS CodeBuild 开发工具包筛选 Webhook 事件,请使用 CreateWebhookUpdateWebhook API 方法的请求语法中的 filterGroups 字段。有关更多信息,请参阅 CodeBuild API 参考 中的 WebhookFilter

要创建仅针对拉取请求触发构建的 Webhook 筛选条件,请在请求语法中插入以下内容:

"filterGroups": [ [ { "type": "EVENT", "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED" } ] ]

要创建仅针对指定分支触发构建的 Webhook 筛选条件,请使用 pattern 参数指定用于过滤分支名称的正则表达式。以两个筛选条件组为例,当一个或两个筛选条件评估为 True 时触发构建:

  • 第一个筛选条件组使用与正则表达式 ^refs/heads/master$ 匹配的 Git 引用名称以及与 ^refs/heads/myBranch$ 匹配的头部引用,指定在分支上创建、更新或重新打开的拉取请求。

  • 第二个筛选条件组使用与正则表达式 ^refs/heads/myBranch$ 匹配的 Git 引用名称,指定分支上的推送请求。

"filterGroups": [ [ { "type": "EVENT", "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED" }, { "type": "HEAD_REF", "pattern": "^refs/heads/myBranch$" }, { "type": "BASE_REF", "pattern": "^refs/heads/master$" } ], [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "HEAD_REF", "pattern": "^refs/heads/myBranch$" } ] ]

您可以使用 excludeMatchedPattern 参数指定不触发构建的事件。例如,在此示例中,将针对除标记事件之外的所有请求触发构建。

"filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED" }, { "type": "HEAD_REF", "pattern": "^refs/tags/.*", "excludeMatchedPattern": true } ] ]

您可以创建只有当名称与 pattern 参数中的正则表达式匹配的文件发生更改时,才触发构建的筛选条件。在此示例中,筛选条件组指定仅当名称与正则表达式 ^buildspec.* 匹配的文件更改时才触发构建。

"filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "FILE_PATH", "pattern": "^buildspec.*" } ] ]

您可以创建仅当账户 ID 为 actor-account-id 的指定 GitHub 或 GitHub Enterprise 用户进行更改时,才触发构建的筛选条件。

注意

有关如何查找您的 GitHub 账户 ID 的信息,请参阅 https://api.github.com/users/user-name,其中 user-name 是您的 GitHub 用户名。

"filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED" }, { "type": "ACTOR_ACCOUNT_ID", "pattern": "actor-account-id" } ] ]

筛选 GitHub Webhook 事件 (AWS CloudFormation)

要使用 AWS CloudFormation 模板来筛选 Webhook 事件,请使用 AWS CodeBuild 项目的 FilterGroups 属性。AWS CloudFormation 模板以下 YAML 格式的部分创建两个筛选条件组。当这两个筛选条件的其中一个或两个评估为 True 时触发构建:

  • 第一个筛选条件组使用与正则表达式 ^refs/heads/master$ 匹配的 Git 引用名称,指定由账户 ID 不为 12345 的 GitHub 用户在分支上创建或更新的拉取请求。

  • 第二个筛选条件组使用与正则表达式 ^refs/heads/.* 匹配的 Git 引用名称,指定在名称与正则表达式 READ_ME 匹配的文件上创建的推送请求。

CodeBuildProject: Type: AWS::CodeBuild::Project Properties: Name: MyProject ServiceRole: service-role Artifacts: Type: NO_ARTIFACTS Environment: Type: LINUX_CONTAINER ComputeType: BUILD_GENERAL1_SMALL Image: aws/codebuild/standard:2.0 Source: Type: GITHUB Location: source-location Triggers: Webhook: true FilterGroups: - - Type: EVENT Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED - Type: BASE_REF Pattern: ^refs/heads/master$ ExcludeMatchedPattern: false - Type: ACTOR_ACCOUNT_ID Pattern: 12345 ExcludeMatchedPattern: true - - Type: EVENT Pattern: PUSH - Type: HEAD_REF Pattern: ^refs/heads/.* - Type: FILE_PATH Pattern: READ_ME ExcludeMatchedPattern: true