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

# GitLab Webhook 事件
<a name="gitlab-webhook"></a>

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

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

**事件**  
對於 GitLab，您可以選擇下列一或多個事件：`PUSH`、`PULL_REQUEST_CREATED`、`PULL_REQUEST_UPDATED`、`PULL_REQUEST_MERGED`、`PULL_REQUEST_REOPENED`、`PULL_REQUEST_CLOSED`、 `RELEASED`和 `WORKFLOW_JOB_QUEUED`。  
Webhook 的事件類型位在 `X-GitLab-Event` 欄位的標頭中。下表顯示 `X-GitLab-Event` 標頭值如何映射到事件類型。對於 `Merge Request Hook` Webhook 事件，承載`object_atttributes.action`將包含合併請求類型的其他資訊。      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/gitlab-webhook.html)
對於 `PULL_REQUEST_MERGED`，如果提取請求與 squash 策略合併，且提取請求分支已關閉，則原始提取請求遞交不再存在。在此情況下，`CODEBUILD_WEBHOOK_MERGE_COMMIT`環境變數會包含壓縮合併遞交的識別符。

**一或多個選用篩選條件**  
使用規則表達式來指定篩選條件。若要讓事件觸發組建，與其相關聯的群組中的每個篩選條件都必須評估為 true。    
`ACTOR_ACCOUNT_ID` (`ACTOR_ID` 主控台中的 )  
當 GitLab 帳戶 ID 符合規則表達式模式時，Webhook 事件會觸發組建。這個值會出現在 Webhook 篩選條件承載之 `actor` 物件的 `account_id` 屬性中。  
`HEAD_REF`  
當頭部參考符合規則表達式模式 （例如， `refs/heads/branch-name`和 ) 時，Webhook 事件會觸發組建`refs/tags/tag-name`。`HEAD_REF` 篩選條件會評估分支或標籤的 Git 參考名稱。分支或標籤名稱會出現在 Webhook 承載 `push` 物件之 `new` 物件的 `name` 欄位中。針對提取請求事件，分支名稱會出現在 Webhook 承載 `source` 物件之 `branch` 物件的 `name` 欄位中。  
`BASE_REF`  
當基本參考符合規則表達式模式時，Webhook 事件會觸發組建。`BASE_REF` 篩選條件僅適用於提取請求事件 (例如 `refs/heads/branch-name`)。`BASE_REF` 篩選條件會評估分支的 Git 參考名稱。分支名稱會出現在 Webhook 承載 `destination` 物件之 `branch` 物件的 `name` 欄位中。  
`FILE_PATH`  
當變更的檔案路徑符合規則表達式模式時，Webhook 會觸發組建。  
`COMMIT_MESSAGE`  
當前端遞交訊息符合規則表達式模式時，Webhook 會觸發組建。  
`WORKFLOW_NAME`  
當工作流程名稱符合規則表達式模式時，Webhook 會觸發組建。

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

**Topics**
+ [Filter GitLab Webhook 事件 （主控台）](gitlab-webhook-events-console.md)
+ [Filter GitLab Webhook 事件 (SDK)](gitlab-webhook-events-sdk.md)
+ [篩選 GitLab Webhook 事件 (CloudFormation)](gitlab-webhook-events-cfn.md)

# Filter GitLab Webhook 事件 （主控台）
<a name="gitlab-webhook-events-console"></a>

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

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.  選擇 **Add filter group (新增篩選群組)** 新增另一個篩選群組。

 如需詳細資訊，請參閱《 *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-gitlab.png)


在有兩個篩選群組的範例中，當一個或兩個篩選群組評估為 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-gitlab.png)


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

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


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

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


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

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


在此範例中，Webhook 篩選條件群組只會在 GitLab 使用者所做的變更中觸發組建，而該使用者的帳戶 ID 不符合規則表達式 `actor-account-id`。

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

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


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

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


# Filter GitLab Webhook 事件 (SDK)
<a name="gitlab-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)。

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

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

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

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

```
"filterGroups": [
  [
    {
      "type": "EVENT",
      "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED"
    },
    {
      "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_MERGED"
    },
    {
      "type": "HEAD_REF",
      "pattern": "^refs/tags/.*",
      "excludeMatchedPattern": true
    }
  ]
]
```

您可以建立篩選條件，只有在帳戶 ID 為 的 GitLab 使用者進行變更時，才會觸發組建`actor-account-id`。

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

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

您可以建立篩選條件來指定只有在檔案名稱符合 `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/.+"
        }
    ]
]
```

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

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

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

 若要使用 CloudFormation 範本篩選 Webhook 事件，請使用 AWS CodeBuild 專案的 `FilterGroups` 屬性。如需 GitLab Webhook 事件的詳細資訊，請參閱 [GitLab Webhook 事件](gitlab-webhook.md)。

在 CloudFormation 範本中，以下 YAML 格式的部分建立兩個篩選群組。當其中一個或兩個評估為 true 時，它們會一起觸發組建：
+  第一個篩選條件群組指定在分支上建立或更新提取請求，其 Git 參考名稱符合沒有帳戶 ID 的 `^refs/heads/main$` GitLab 使用者的規則表達式`12345`。
+  第二個篩選群組指定分支上建立的推送請求，並且這些分支的 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: GITLAB
      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: EVENT
            Pattern: PUSH
          - Type: COMMIT_MESSAGE
            Pattern: \[CodeBuild\]
        - - Type: EVENT
            Pattern: WORKFLOW_JOB_QUEUED
          - Type: WORKFLOW_NAME
            Pattern: \[CI-CodeBuild\]
```