使用 GitLab 事件触发器

概述

GitLab 事件触发器允许你通过 GitLab 的 Webhook 事件自动触发 Tekton 流水线。它支持多种事件类型,包括代码推送、合并请求、评论等,帮助你构建完整的 CI/CD 自动化工作流。

核心功能

  • 多事件类型支持:支持 Push、Merge Request、评论等多种 GitLab 事件。
  • 标准化触发器绑定:提供标准化的 ClusterTriggerBindings,确保跨平台一致性。
  • 灵活的参数映射:自动从 GitLab 事件中提取关键信息,用于流水线参数。
  • 安全的 Webhook 集成:支持 Webhook 安全验证。

支持的事件类型

基本事件信息

所有输出变量都可用于流水线参数映射。你可以使用 $(tt.params.<param name>) 访问参数值。

基本变量(所有事件通用)

变量名称描述示例值
project-idGitLab 项目 ID1234
project-name项目名称my-project
project-path项目完整路径group/my-project
project-web-url项目 Web URLhttps://gitlab.com/group/my-project
git-repo-urlGit HTTP URLhttps://gitlab.com/group/my-project.git
git-repo-ssh-urlGit SSH URLgit@gitlab.com:group/my-project.git
git-repo-name仓库名称my-project
user-name用户全名John Doe
user-username用户名johndoe
user-email用户电子邮件john@example.com

1. Push 事件

当开发人员向 GitLab 仓库推送代码时触发。适用于:

  • 持续集成构建
  • 自动部署
  • 代码质量检查

Push 事件变量

变量名称描述示例值
git-revisionGit 修订版本refs/heads/main
git-commit-sha提交 SHA8a1b3c4d5e6f...
git-commit-message提交消息Update README.md
git-commit-timestamp提交时间戳2025-01-26T10:30:00Z

2. Merge Request 事件

当创建、更新或关闭合并请求时触发。适用于:

  • 自动化代码审查
  • 预发布环境部署
  • 自动化测试

Merge Request 事件变量

变量名称描述示例值
mergereq-sha最新提交 SHA8a1b3c4d5e6f...
mergereq-action合并请求操作open、reopen、update、close、merge
mergereq-state合并请求状态opened、closed、merged
mergereq-number合并请求编号42
mergereq-url合并请求 URLhttps://gitlab.com/group/project/-/merge_requests/42
mergereq-title合并请求标题Add new feature
mergereq-description合并请求描述This PR adds...
mergereq-merge-status合并状态can_be_merged
mergereq-source-branch源分支feature/new-feature
mergereq-target-branch目标分支main
mergereq-source-path源仓库路径group/my-project
mergereq-target-path目标仓库路径group/my-project
TIP

请参阅你的 GitLab 实例的 webhook 文档,或参阅 GitLab 官方合并请求事件文档

3. 评论事件

支持以下评论类型:

  • 合并请求评论
  • 提交评论

适用于:

  • ChatOps 评论自动化

基本评论事件变量(所有评论事件通用)

变量名称描述示例值
comment评论内容LGTM 👍
comment-url评论 URLhttps://gitlab.com/group/project/-/merge_requests/42#note_123

3.1 合并请求评论变量

变量名称描述示例值
mergereq-sha最新提交 SHA8a1b3c4d5e6f...
mergereq-action合并请求操作open、reopen、update、close、merge
mergereq-state合并请求状态opened、closed、merged
mergereq-number合并请求编号42
mergereq-url合并请求 URLhttps://gitlab.com/group/project/-/merge_requests/42
mergereq-title合并请求标题Add new feature
mergereq-description合并请求描述This PR adds...
mergereq-merge-status合并状态can_be_merged
mergereq-source-branch源分支feature/new-feature
mergereq-target-branch目标分支main
mergereq-source-path源仓库路径group/my-project
mergereq-target-path目标仓库路径group/my-project

3.2 提交评论变量

变量名称描述示例值
git-commit-sha提交 SHA8a1b3c4d5e6f...
git-commit-message提交消息Update README.md
git-commit-timestamp提交时间戳2025-01-26T10:30:00Z
git-commit-url提交 URLhttps://gitlab.com/group/project/-/commit/8a1b3c4d

配置指南

前置条件

  1. 环境中已创建 EventListener,并且能够在目标命名空间中处理 Trigger。更多信息请联系平台管理员。
  2. GitLab 可以访问上述 EventListener。
  3. 已创建所需的 Pipeline 以及必要的运行配置。
  4. 你拥有修改 GitLab 项目 Webhook 设置的权限。

通过 GitLab UI 配置 Webhook

  1. 访问 GitLab 项目设置。
  2. 导航至 Settings > Webhooks。
  3. 根据 EventListener 的部署模式添加 Webhook URL,例如使用 https 模式:
    https://<your-eventlistener-url>
  4. 根据需要选择事件类型:
    • Push 事件
    • 合并请求事件
    • 评论
  5. (可选)配置 Secret Token。
  6. 点击“Add webhook”。

Pipeline 触发器配置示例

如果目标是通过触发器实现持续集成,并满足以下要求:

  • 提交代码时自动触发自动化 CI 功能。
  • 创建合并请求时自动触发 CI Pipeline。

为简化本文档,我们假设 Pipeline 已准备就绪,并提供了以下参数:

参数名称描述示例值
git-revision执行目标 Pipeline 的 Git 修订版本refs/heads/main
git-repo-urlGit 仓库 URLhttps://gitlab.com/group/project.git
TIP

请替换为实际的 Pipeline 信息。

信息描述
my-namespace命名空间名称
my-pipelinePipeline 名称
workspaces工作区配置,根据实际的 Pipeline 工作区配置和需求进行修改

接下来,我们只需要配置以下两个触发器:

创建 Push 触发器

将以下 YAML 保存为 gitlab-push-trigger.yaml:

apiVersion: triggers.tekton.dev/v1alpha1
kind: Trigger
metadata:
    name: my-pipeline-push   # It is suggested to modify the prefix based on the pipeline name
    namespace: my-namespace  # Change to actual namespace
spec:
    bindings:
    - kind: ClusterTriggerBinding
      ref: gitlab-push
    template:
      spec:
        params:
        - name: git-revision
        - name: git-repo-url
        resourcetemplates:
        - apiVersion: tekton.dev/v1
          kind: PipelineRun
          metadata:
              generateName: my-pipeline-push- # It is suggested to modify the prefix based on the pipeline name
          spec:
              pipelineRef:
                name: my-pipeline  # Change to actual pipeline name
              params:
              - name: git-revision
                value: $(tt.params.git-revision)
              - name: git-repo-url
                value: $(tt.params.git-repo-url)
              workspaces: # Workspaces need to be modified based on pipeline requirements and environment configuration
              - name: source
                volumeClaimTemplate:
                  spec:
                    accessModes:
                    - ReadWriteMany
                    resources:
                      requests:
                        storage: 1Gi

在环境中创建资源:

kubectl apply -f gitlab-push-trigger.yaml

创建合并请求触发器

将以下 YAML 保存为 gitlab-merge-request-trigger.yaml:

apiVersion: triggers.tekton.dev/v1alpha1
kind: Trigger
metadata:
  name: my-pipeline-merge-request # It is suggested to modify the prefix based on the pipeline name
  namespace: my-namespace # Change to actual namespace
spec:
  bindings:
    - kind: ClusterTriggerBinding
      ref: gitlab-mergerequest
  interceptors: # Add Interceptor to filter opened MR events, ignore others for now
  - ref:
      kind: ClusterInterceptor
      name: cel
    params:
    - name: filter
      value: |
        body.object_attributes.state == "opened" &&  body.object_attributes.action == "open"
  template:
    spec:
      params:
        - name: mergereq-sha
        - name: git-repo-url
      resourcetemplates:
      - apiVersion: tekton.dev/v1
        kind: PipelineRun
        metadata:
          generateName: my-pipeline-mr- # It is suggested to modify the prefix based on the pipeline name
        spec:
          pipelineRef:
            name: my-pipeline # Modify based on the pipeline name
          params:
            - name: git-revision
              value: $(tt.params.mergereq-sha)
            - name: git-repo-url
              value: $(tt.params.git-repo-url)
          workspaces: # Workspaces need to be modified based on pipeline requirements and environment configuration
            - name: source
              volumeClaimTemplate:
                spec:
                  accessModes:
                    - ReadWriteMany
                  resources:
                    requests:
                      storage: 1Gi
TIP

请根据需要调整 Interceptor 配置。

在环境中创建资源:

kubectl apply -f gitlab-merge-request-trigger.yaml

验证触发器

通过提交代码并创建合并请求进行验证。

CLI:

可以使用 kubectl -n <namespace> get pipelinerun 获取 Pipeline 执行状态。

控制台:

访问 Pipelines > PipelineRuns 查看已触发的 Pipeline。