本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# GitHub Webhook 事件
<a name="github-webhook"></a>

您可以使用 Webhook 篩選群組來指定哪些 GitHub Webhook 事件會觸發組建。例如，您可以指定僅針對特定分支的變更觸發組建。

您可以建立一或多個 Webhook 篩選條件群組，以指定哪些 Webhook 事件觸發組建。如果任何篩選條件群組評估為 true，則會觸發組建，這會在群組中的所有篩選條件評估為 true 時發生。當您建立篩選條件群組時，您可以指定：

**事件**  
對於 GitHub，您可以選擇下列一或多個事件：`PUSH`、`PULL_REQUEST_CREATED`、`PULL_REQUEST_UPDATED`、`PULL_REQUEST_REOPENED`、`PULL_REQUEST_MERGED`、`PULL_REQUEST_CLOSED``RELEASED`、 `PRERELEASED`和 `WORKFLOW_JOB_QUEUED`。Webhook 事件類型位在 Webhook 承載的 `X-GitHub-Event` 標頭中。在 `X-GitHub-Event` 標頭中，您可能會看到 `pull_request` 或 `push`。若為提取請求事件，類型位在 Webhook 事件承載的 `action` 欄位中。下表顯示 `X-GitHub-Event` 標頭值和 Webhook 提取請求承載 `action` 欄位值如何映射到可用的事件類型。      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/github-webhook.html)
 `PULL_REQUEST_REOPENED` 事件類型僅能搭配 GitHub 和 GitHub Enterprise Server 使用。`RELEASED` 和 `PRERELEASED`事件類型只能與 GitHub 搭配使用。如需 `WORKFLOW_JOB_QUEUED` 的詳細資訊，請參閱[教學課程：設定 CodeBuild 託管的 GitHub 動作執行器](action-runner.md)。

**一或多個選用篩選條件**  
使用規則表達式來指定篩選條件。若要讓事件觸發組建，與其相關聯的群組中的每個篩選條件都必須評估為 true。    
`ACTOR_ACCOUNT_ID` (`ACTOR_ID` 主控台中的 )  
當 GitHub 或 GitHub Enterprise Server 帳戶 ID 符合規則表達式模式時，Webhook 事件會觸發組建。此值位於 Webhook 承載之 `sender` 物件的 `id` 屬性中。  
`HEAD_REF`  
當頭部參考符合規則表達式模式 （例如， `refs/heads/branch-name`或 ) 時，Webhook 事件會觸發組建`refs/tags/tag-name`。若為推送事件，參考名稱位在 Webhook 承載的 `ref` 屬性中。若為提取請求事件，分支名稱位在 Webhook 承載之 `head` 物件的 `ref` 屬性中。  
`BASE_REF`  
當基本參考符合規則表達式模式 （例如，) 時，Webhook 事件會觸發組建`refs/heads/branch-name`。`BASE_REF` 篩選條件僅可搭配提取請求事件使用。分支名稱位在 Webhook 承載之 `base` 物件的 `ref` 屬性中。  
`FILE_PATH`  
當變更的檔案路徑符合規則表達式模式時，Webhook 會觸發組建。`FILE_PATH` 篩選條件可以用於 GitHub 推送和提取請求事件和 GitHub Enterprise Server 推送事件。它不能與 GitHub Enterprise Server 提取請求事件一起使用。  
`COMMIT_MESSAGE`  
當前端遞交訊息符合規則表達式模式時，Webhook 會觸發組建。`COMMIT_MESSAGE` 篩選條件可以用於 GitHub 推送和提取請求事件和 GitHub Enterprise Server 推送事件。它不能與 GitHub Enterprise Server 提取請求事件一起使用。  
`TAG_NAME`  
當版本的標籤名稱符合規則表達式模式時，Webhook 會觸發組建。`TAG_NAME` 篩選條件可與 GitHub 發行和預先發行的請求事件搭配使用。  
`RELEASE_NAME`  
當版本名稱符合規則表達式模式時，Webhook 會觸發組建。`RELEASE_NAME` 篩選條件可與 GitHub 發行和預先發行的請求事件搭配使用。  
`REPOSITORY_NAME`  
當儲存庫名稱符合規則表達式模式時，Webhook 會觸發組建。`REPOSITORY_NAME` 篩選條件只能與 GitHub 全域或組織 Webhook 搭配使用。  
`ORGANIZATION_NAME`  
當組織名稱符合規則表達式模式時，Webhook 會觸發組建。`ORGANIZATION_NAME` 篩選條件只能與 GitHub 全域 Webhook 搭配使用。  
`WORKFLOW_NAME`  
當工作流程名稱符合規則表達式模式時，Webhook 會觸發組建。`WORKFLOW_NAME` 篩選條件可與 GitHub Actions 工作流程任務佇列請求事件搭配使用。

**注意**  
您可以在您 GitHub 儲存庫的 Webhook 設定中找到 Webhook 承載。

**Topics**
+ [

# 篩選 GitHub Webhook 事件 (主控台)
](github-webhook-events-console.md)
+ [

# 篩選 GitHub Webhook 事件 (開發套件)
](github-webhook-events-sdk.md)
+ [

# 篩選 GitHub Webhook 事件 (CloudFormation)
](github-webhook-events-cfn.md)

# 篩選 GitHub Webhook 事件 (主控台)
<a name="github-webhook-events-console"></a>

使用以下指示，使用 篩選 GitHub Webhook 事件 AWS 管理主控台。如需 GitHub Webhook 事件的詳細資訊，請參閱 [GitHub Webhook 事件](github-webhook.md)。

在**主要來源 Webhook 事件**中，選取下列項目。只有當您在**我的 GitHub 帳戶中為來源儲存庫**選擇儲存庫時，才能使用本節。

1. 當您建立專案時，請選取 **Rebuild every time a code change is pushed to this repository (在每次將程式碼變更推送至此儲存庫時重建)**。

1. 從 **Event type (事件類型)**，選擇一或多個事件。

1. 若要篩選事件觸發組建的時間，請在 **Start a build under these conditions (在這些情況下開始組建)** 下新增一或多個選用的篩選條件。

1. 若要篩選何時不觸發事件，請在 **Don't start a build under these conditions (在這些情況下不開始組建)** 下新增一或多個選用的篩選條件。

1. 如有需要，請選擇**新增篩選條件群組**以新增另一個篩選條件群組。

 如需詳細資訊，請參閱《 *AWS CodeBuild API 參考*》中的 [建立組建專案 (主控台)](create-project.md#create-project-console)和 [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html)。

在這個範例中，Webhook 篩選群組僅針對提取請求觸發組建：

![\[僅針對提取請求觸發組建的 Webhook 篩選群組。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/pull-request-webhook-filter.png)


在有兩個 Webhook 篩選群組的範例中，當一個或兩個篩選群組評估為 true 時，就會觸發組建：
+ 第一個篩選群組指定在分支上建立、更新或重新開啟的提取請求，並且這些分支的 Git 參考名稱符合規則表達式 `^refs/heads/main$`，而標頭參考符合 `^refs/heads/branch1$`。
+ 第二個篩選群組在分支上指定推送請求，並且這些分支的 Git 參考名稱符合規則表達式 `^refs/heads/branch1$`。

![\[兩個篩選群組的範例。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/pull-request-webhook-filter-head-base-regexes.png)


在這個範例中，Webhook 篩選群組針對所有請求 (標籤事件除外) 觸發組建。

![\[Webhook 篩選條件群組，可針對標籤事件以外的所有請求觸發組建。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/pull-request-webhook-filter-exclude.png)


在這個範例中，只有在檔案名稱符合規則表達式 `^buildspec.*` 的檔案變更時，Webhook 篩選群組才會觸發組建。

![\[只有當檔案的名稱符合指定的規則表達式時，才會觸發組建的 Webhook 篩選條件群組。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-regex.png)


在此範例中，Webhook 篩選群組只會在 `src`或 `test` 資料夾中變更檔案時觸發組建。

![\[只有在指定資料夾中變更檔案時，才會觸發組建的 Webhook 篩選群組。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-combined-regex.png)


在這個範例中，只有當指定的 GitHub 或 GitHub Enterprise Server 使用者進行變更，而且其帳戶 ID 符合規則表達式 `actor-account-id` 時，Webhook 篩選群組才會觸發建置。

**注意**  
 有關如何尋找您的 GitHub 帳戶 ID 的資訊，請參閱 https://api.github.com/users/*user-name*，其中 *user-name* 是您的 GitHub 使用者名稱。

![\[只有當指定的 GitHub 使用者使用符合規則表達式的帳戶 ID 進行變更時，才會觸發組建的 Webhook 篩選群組。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/pull-request-webhook-filter-actor.png)


在此範例中，當 head 提交訊息符合規則運算式 `\[CodeBuild\]` 時，webhook 篩選群組會觸發推送事件的建置。

![\[當前端遞交訊息符合規則表達式時，觸發推送事件建置的 Webhook 篩選條件群組。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/pull-request-webhook-filter-commit-message.png)


在此範例中，Webhook 篩選群組只會觸發 GitHub Actions 工作流程任務事件的組建。

**注意**  
CodeBuild 只有在 Webhook 具有包含 **WORKFLOW\$1JOB\$1QUEUED** 事件篩選條件的篩選條件群組時，才會處理 GitHub Actions 工作流程任務。

![\[Webhook 篩選群組只會觸發 GitHub Actions 工作流程任務事件的組建。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/github-actions-workflow-job-queued-no-highlight.png)


在此範例中，Webhook 篩選群組會為符合規則表達式 的工作流程名稱觸發組建`CI-CodeBuild`。

![\[Webhook 篩選條件群組會為符合規則表達式的工作流程名稱觸發組建。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/github-actions-workflow-job-specific.png)


# 篩選 GitHub Webhook 事件 (開發套件)
<a name="github-webhook-events-sdk"></a>

若要使用 AWS CodeBuild SDK 篩選 Webhook 事件，請使用 `CreateWebhook`或 `UpdateWebhook` API 方法請求語法中的 `filterGroups` 欄位。如需詳細資訊，請參閱 *CodeBuild API 參考*中的 [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html)。

如需 GitHub Webhook 事件的詳細資訊，請參閱 [GitHub Webhook 事件](github-webhook.md)。

 若要建立 Webhook 篩選條件來只針對提取請求觸發組建，請在請求語法插入以下程式碼：

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

 若要建立 Webhook 篩選條件來只針對指定的分支觸發組建，請使用 `pattern` 參數指定規則表達式來篩選分支名稱。在有兩個篩選群組的範例中，當一個或兩個篩選群組評估為 true 時，就會觸發組建：
+ 第一個篩選群組指定在分支上建立、更新或重新開啟的提取請求，並且這些分支的 Git 參考名稱符合規則表達式 `^refs/heads/main$`，而標頭參考符合 `^refs/heads/myBranch$`。
+ 第二個篩選群組在分支上指定推送請求，並且這些分支的 Git 參考名稱符合規則表達式 `^refs/heads/myBranch$`。

```
"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/main$"
        }
    ],
    [
        {
            "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, PULL_REQUEST_CLOSED"
        },
        {
            "type": "HEAD_REF", 
            "pattern": "^refs/tags/.*", 
            "excludeMatchedPattern": true
        }
    ]
]
```

您可以建立篩選條件來指定只有在檔案名稱符合 `pattern` 引數中的規則表達式的檔案變更時，才觸發組建。在這個範例中，篩選群組指定只有在檔案名稱符合規則表達式 `^buildspec.*` 的檔案變更時，才觸發組建。

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

在此範例中，篩選條件群組指定只有在 `src`或 `test` 資料夾中變更檔案時，才會觸發組建。

```
"filterGroups": [
    [
        {
            "type": "EVENT", 
            "pattern": "PUSH"
        },
        {
            "type": "FILE_PATH", 
            "pattern": "^src/.+|^test/.+"
        }
    ]
]
```

您可以建立篩選條件來指定只有在指定的 GitHub 或 GitHub Enterprise Server 使用者進行變更，並且其帳戶 ID 為 `actor-account-id` 時，才觸發組建。

**注意**  
 有關如何尋找您的 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, PULL_REQUEST_CLOSED"
        },
        {
            "type": "ACTOR_ACCOUNT_ID", 
            "pattern": "actor-account-id"
        }
    ]
]
```

您可以建立篩選條件，只有在 head 提交訊息符合模式引數中的規則運算式時，才觸發組建。在這個範例中，篩選群組指定只有在推送事件的 head 遞交訊息符合規則表達式 `\[CodeBuild\]` 時，才觸發組建。

```
"filterGroups": [
    [
        {
            "type": "EVENT",
            "pattern": "PUSH"
        },
        {
            "type": "COMMIT_MESSAGE",
            "pattern": "\[CodeBuild\]"
        }
    ]
]
```

若要建立僅觸發 GitHub 動作工作流程任務建置的 Webhook 篩選條件，請將以下內容插入請求語法中：

```
"filterGroups": [
   [
        {
            "type": "EVENT", 
            "pattern": "WORKFLOW_JOB_QUEUED"
        }
    ]
]
```

# 篩選 GitHub Webhook 事件 (CloudFormation)
<a name="github-webhook-events-cfn"></a>

 若要使用 CloudFormation 範本篩選 Webhook 事件，請使用 AWS CodeBuild 專案的 `FilterGroups` 屬性。

如需 GitHub Webhook 事件的詳細資訊，請參閱 [GitHub Webhook 事件](github-webhook.md)。

在 CloudFormation 範本中，以下 YAML 格式的部分建立兩個篩選群組。當其中一個或兩個評估為 true 時，它們會一起觸發組建：
+  第一個篩選群組指定在分支上建立或更新的提取請求，並且這些分支的 Git 參考名稱符合規則表達式 `^refs/heads/main$`，而且是由帳戶 ID 不是 `12345` 的 GitHub 使用者所建立或更新。
+  第二個篩選群組指定在分支中的檔案上建立的推送請求，並且這些檔案的名稱符合規則表達式 `READ_ME`，而分支的 Git 參考名稱符合規則表達式 `^refs/heads/.*`。
+ 第三個篩選群組會指定其 head 提交訊息符合規則運算式 `\[CodeBuild\]` 的推送請求。
+ 第四個篩選條件群組會指定工作流程名稱符合規則表達式 的 GitHub Actions 工作流程任務請求`\[CI-CodeBuild\]`。

```
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:5.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/main$
            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
        - - Type: EVENT
            Pattern: PUSH
          - Type: COMMIT_MESSAGE
            Pattern: \[CodeBuild\]
          - Type: FILE_PATH
            Pattern: ^src/.+|^test/.+
        - - Type: EVENT
            Pattern: WORKFLOW_JOB_QUEUED
          - Type: WORKFLOW_NAME
            Pattern: \[CI-CodeBuild\]
```