# GitLab group webhooks
<a name="gitlab-group-webhook"></a>

You can use CodeBuild GitLab group webhooks to start builds on webhook events from any repository within a GitLab group. Group webhooks work with any of the existing GitLab webhook event types, and can be configured by adding a scope configuration when creating a CodeBuild webhook. You can also use group webhooks to [set up self-hosted GitLab runners within CodeBuild](gitlab-runner.md) in order to receive `WORKFLOW_JOB_QUEUED` events from multiple repositories within a single project.

**Topics**
+ [Set up a group GitLab webhook](gitlab-group-webhook-setup.md)
+ [Filter GitLab group webhook events (console)](gitlab-group-webhook-events-console.md)
+ [Filter GitLab group webhook events (CloudFormation)](gitlab-group-webhook-events-cfn.md)

# Set up a group GitLab webhook
<a name="gitlab-group-webhook-setup"></a>

The high-level steps to set up a group GitLab webhook are as follows. For more information about group GitLab webhooks, see [GitLab group webhooks](gitlab-group-webhook.md).

1. Set your project's source location to `CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION`.

1. In the webhook's scope configuration, set the scope to `GITLAB_GROUP`.

1. Specify a name as part of the webhook's scope configuration. For group webhooks, this is the group name.
**Note**  
If the project's source type is `GITLAB_SELF_MANAGED`, you will also need to specify a domain as part of the webhook scope configuration.

1. (Optional) If you would only like to receive webhook events for specific repositories within your organization or enterprise, you can specify `REPOSITORY_NAME` as a filter when creating the webhook.

1. When creating a group webhook, ensure that CodeBuild has permissions to create group level webhooks within GitLab. To do so, you can use CodeBuild OAuth though CodeConnections. For more information, see [GitLab access in CodeBuild](access-tokens-gitlab-overview.md).

   Note that group webhooks work with any of the existing GitLab webhook event types.

# Filter GitLab group webhook events (console)
<a name="gitlab-group-webhook-events-console"></a>

When creating a GitLab project through the console, select the following options to create a GitLab group webhook within the project. For more information about group GitLab webhooks, see [GitLab group webhooks](gitlab-group-webhook.md).

1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).

1. Create a build project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md).
   +  In **Source**: 
     +  For **Source provider**, choose **GitLab** or **GitLab Self Managed**.
     +  For **Repository**, choose **GitLab scoped webhook**. 

        The GitLab repository will automatically be set to `CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION`, which is the required source location for group webhooks. 
**Note**  
When using group webhooks, make sure that CodeBuild has permissions to create group level webhooks within GitLab. If you're using an [existing OAuth connection](access-tokens-gitlab-overview.md#connections-gitlab), you may need to regenerate the connection in order to grant CodeBuild this permission.  
![\[The configuration of GitLab scoped webhook.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/gitlab-group-source.png)
   +  In **Primary source webhook events**: 
     +  For **Group name**, enter the group name.

       If the project's source type is `GITLAB_SELF_MANAGED`, you also need to specify a domain as part of the webhook group configuration. For example, if the URL of your group is **https://domain.com/group/group-name**, then the domain is **https://domain.com**.
**Note**  
 This name cannot be changed after the webhook has been created. To change the name, you can delete and re-create the webhook. If you want to remove the webhook entirely, you can also update the project source location to a GitLab repository.   
![\[The configuration of group webhooks.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/gitlab-group-webhook-primary-events.png)
     +  (Optional) In **Webhook event filter groups**, you can specify which [events you would like to trigger a new build](gitlab-webhook.md). You can also specify `REPOSITORY_NAME` as a filter to only trigger builds on webhook events from specific repositories.  
![\[A filter that only triggers builds on webhook events from specific repositories.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-organization-webhook-filter-groups.png)

       You can also set the event type to `WORKFLOW_JOB_QUEUED` to set up self-hosted GitLab runners. For more information, see [Self-managed GitLab runners in AWS CodeBuild](gitlab-runner.md).

1. Continue with the default values and then choose **Create build project**.

# Filter GitLab group webhook events (CloudFormation)
<a name="gitlab-group-webhook-events-cfn"></a>

 To use an CloudFormation template to filter group webhook events, use the AWS CodeBuild project's `ScopeConfiguration` property. For more information about group GitLab webhooks, see [GitLab group webhooks](gitlab-group-webhook.md).

 The following YAML-formatted portion of an CloudFormation template creates four filter groups. Together, they trigger a build when one or all evaluate to true: 
+  The first filter group specifies pull requests are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` by a GitLab user who does not have account ID `12345`. 
+  The second filter group specifies push requests are created on files with names that match the regular expression `READ_ME` in branches with Git reference names that match the regular expression `^refs/heads/.*`. 
+ The third filter group specifies a push request with a head commit message matching the regular expression `\[CodeBuild\]`.
+ The fourth filter group specifies a GitLab CI/CD pipeline job request with a CI/CD pipeline name matching the regular expression `\[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
      ScopeConfiguration:
        Name: group-name
        Scope: GITLAB_GROUP
      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\]
```