使用 GitLab Event Triggers

概述

GitLab Event Triggers 可让你通过 GitLab 的 Webhook 事件自动触发 Tekton pipelines。它支持多种事件类型,包括代码推送、Merge Request、评论等,帮助你构建完整的 CI/CD 自动化工作流。

核心功能

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

支持的事件类型

基本事件信息

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

基础变量(适用于所有事件)

Variable NameDescriptionExample Value
project-idGitLab Project ID1234
project-nameProject Namemy-project
project-pathProject Full Pathgroup/my-project
project-web-urlProject 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-nameRepository Namemy-project
user-nameUser Full NameJohn Doe
user-usernameUsernamejohndoe
user-emailUser Emailjohn@example.com

1. Push Event

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

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

Push 事件变量

Variable NameDescriptionExample Value
git-revisionGit revisionrefs/heads/main
git-commit-shaCommitted SHA8a1b3c4d5e6f...
git-commit-messageCommit MessageUpdate README.md
git-commit-timestampCommit Timestamp2025-01-26T10:30:00Z

2. Merge Request Event

当 Merge Request 被创建、更新或关闭时触发。适用于:

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

Merge Request 事件变量

Variable NameDescriptionExample Value
mergereq-shaLast Commit SHA8a1b3c4d5e6f...
mergereq-actionMerge Request Actionopen, reopen, update, close, merge
mergereq-stateMerge Request Stateopened, closed, merged
mergereq-numberMerge Request Number42
mergereq-urlMerge Request URLhttps://gitlab.com/group/project/-/merge_requests/42
mergereq-titleMerge Request TitleAdd new feature
mergereq-descriptionMerge Request DescriptionThis PR adds...
mergereq-merge-statusMerge Statuscan_be_merged
mergereq-source-branchSource Branchfeature/new-feature
mergereq-target-branchTarget Branchmain
mergereq-source-pathSource Repository Pathgroup/my-project
mergereq-target-pathTarget Repository Pathgroup/my-project
TIP

请参考你的 GitLab 实例的 webhook 文档,或 GitLab's official merge request event documentation

3. Comment Events

支持以下类型的评论:

  • Merge Request 评论
  • Commit 评论

适用于:

  • ChatOps 评论自动化

基础评论事件变量(适用于所有评论事件)

Variable NameDescriptionExample Value
commentComment ContentLGTM 👍
comment-urlComment URLhttps://gitlab.com/group/project/-/merge_requests/42#note_123

3.1 Merge Request 评论变量

Variable NameDescriptionExample Value
mergereq-shaLast Commit SHA8a1b3c4d5e6f...
mergereq-actionMerge Request Actionopen, reopen, update, close, merge
mergereq-stateMerge Request Stateopened, closed, merged
mergereq-numberMerge Request Number42
mergereq-urlMerge Request URLhttps://gitlab.com/group/project/-/merge_requests/42
mergereq-titleMerge Request TitleAdd new feature
mergereq-descriptionMerge Request DescriptionThis PR adds...
mergereq-merge-statusMerge Statuscan_be_merged
mergereq-source-branchSource Branchfeature/new-feature
mergereq-target-branchTarget Branchmain
mergereq-source-pathSource Repository Pathgroup/my-project
mergereq-target-pathTarget Repository Pathgroup/my-project

3.2 Commit 评论变量

Variable NameDescriptionExample Value
git-commit-shaCommit SHA8a1b3c4d5e6f...
git-commit-messageCommit MessageUpdate README.md
git-commit-timestampCommit Timestamp2025-01-26T10:30:00Z
git-commit-urlCommit 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 events
    • Merge request events
    • Comments
  5. (可选)配置 Secret Token。
  6. 点击 "Add webhook"。

Pipeline Trigger 配置示例

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

  • 在代码提交后自动触发自动化 CI 功能。
  • 当 Merge Request 打开时自动触发 CI pipeline。

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

Parameter NameDescriptionExample Value
git-revisionGit revision for executing the target pipelinerefs/heads/main
git-repo-urlGit Repository URLhttps://gitlab.com/group/project.git
TIP

请替换为你的实际 pipeline 信息。

InformationDescription
my-namespaceNamespace Name
my-pipelinePipeline Name
workspacesWorkspace 配置,请根据实际 pipeline workspace 配置和要求进行修改

接下来,我们只需要配置下面两个 trigger:

创建 Push Trigger

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

apiVersion: triggers.tekton.dev/v1alpha1
kind: Trigger
metadata:
    name: my-pipeline-push   # 建议根据 pipeline 名称修改前缀
    namespace: my-namespace  # 修改为实际 namespace
spec:
    bindings:
    - ref:
        kind: ClusterTriggerBinding
        name: gitlab-push
    template:
      spec:
        params:
        - name: git-revision
        - name: git-repo-url
        resourcetemplates:
        - apiVersion: tekton.dev/v1
          kind: PipelineRun
          metadata:
              generateName: my-pipeline-push- # 建议根据 pipeline 名称修改前缀
          spec:
              pipelineRef:
                name: my-pipeline  # 修改为实际 pipeline 名称
              params:
              - name: git-revision
                value: $(tt.params.git-revision)
              - name: git-repo-url
                value: $(tt.params.git-repo-url)
              workspaces: # Workspaces 需要根据 pipeline 要求和环境配置进行修改
              - name: source
                volumeClaimTemplate:
                  spec:
                    accessModes:
                    - ReadWriteMany
                    resources:
                      requests:
                        storage: 1Gi

在环境中创建资源:

kubectl apply -f gitlab-push-trigger.yaml

创建 Merge Request Trigger

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

apiVersion: triggers.tekton.dev/v1alpha1
kind: Trigger
metadata:
  name: my-pipeline-merge-request # 建议根据 pipeline 名称修改前缀
  namespace: my-namespace # 修改为实际 namespace
spec:
  bindings:
    - ref:
        kind: ClusterTriggerBinding
        name: gitlab-merge-request
  interceptors: # 添加 Interceptor 以过滤打开的 MR 事件,暂时忽略其他事件
  - 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- # 建议根据 pipeline 名称修改前缀
        spec:
          pipelineRef:
            name: my-pipeline # 根据 pipeline 名称修改
          params:
            - name: git-revision
              value: $(tt.params.mergereq-sha)
            - name: git-repo-url
              value: $(tt.params.git-repo-url)
          workspaces: # Workspaces 需要根据 pipeline 要求和环境配置进行修改
            - name: source
              volumeClaimTemplate:
                spec:
                  accessModes:
                    - ReadWriteMany
                  resources:
                    requests:
                      storage: 1Gi
TIP

请根据需要调整 Interceptor 配置。

在环境中创建资源:

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

验证 Triggers

通过提交代码和创建 Merge Request 来验证。

CLI:

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

Console:

访问 Pipelines > PipelineRuns 查看触发的 pipelines。