3. 使用事件自动化 CI

将 GitLab 推送事件连接到你已经测试过的两个 Run Template。完成本教程后,向组件的 main 分支推送代码时,只会启动该组件的 CI Pipeline。

前提条件:手动运行和 构建并运行组件 CI 中的 Run Template 均可正常工作。管理员还必须准备 Tekton Triggers、监听器身份,以及 GitLab 可以访问的内部 TLS webhook 端点。

1. 了解事件到运行的路径

GitLab webhook -> EventListener -> authentication -> repository/branch filter
                                                        |
                                                  TriggerBinding
                                                revision + image-tag
                                                        |
                                                   Run Template
                                                        |
                                                   PipelineRun
资源本教程中的职责
EventListener接收 webhook 请求,并将其分派给组件 Trigger。
Trigger选择身份验证、过滤器、参数绑定和 Run Template。
TriggerBinding将 GitLab 的 checkout_sha 映射到 revision 和 image-tag。
TriggerTemplate存储 Run Template 的固定配置,并使用事件值创建 PipelineRun。

传入事件提供的是提交 SHA,而不是克隆 URL、Connector 或服务账户。这些内容在 Run Template 中保持固定。身份验证和过滤解决的是不同的问题:匹配的仓库名称并不能证明请求确实由 GitLab 发送。

2. 管理员:配置 webhook 身份验证

在 Pipeline 命名空间中创建名为 application-cicd-gitlab-webhook 的 Secret,并使用平台的 Secret 管理 工作流设置键 secretToken。使用强度足够的生成值。将 GitLab 配置为通过 webhook Secret token 发送该值;不要将其放入 URL 或示例 YAML 中。

为 <code-events-service-account> 提供读取 Trigger 资源和创建 PipelineRun 所需的命名空间范围权限。 根据 EventListener 身份验证指南 为已安装的拦截器服务配置 Secret 访问权限。 不要向 webhook 发送方授予部署权限。

仅通过经过批准的内部 TLS 端点公开监听器。将网络访问限制为指定的 webhook 发送方。在 GitLab 中保持证书验证启用。

3. 创建 GitLab Triggers

将以下资源粘贴到 YAML 编辑器中,或在替换占位符后将其保存到本地,文件名为 code-triggers.yaml:

Complete GitLab Trigger and EventListener YAML
apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerBinding
metadata:
  name: application-cicd-git-push
  namespace: <pipeline-namespace>
  labels:
    app.kubernetes.io/part-of: application-cicd-demo
spec:
  params:
    - name: revision
      value: $(body.checkout_sha)
    - name: image-tag
      value: $(body.checkout_sha)
---
apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
  name: application-cicd-frontend-git
  namespace: <pipeline-namespace>
  labels:
    app.kubernetes.io/part-of: application-cicd-demo
spec:
  bindings:
    - ref: application-cicd-git-push
  interceptors:
    - ref:
        name: gitlab
        kind: ClusterInterceptor
      params:
        - name: secretRef
          value:
            secretName: application-cicd-gitlab-webhook
            secretKey: secretToken
        - name: eventTypes
          value: [Push Hook]
    - ref:
        name: cel
        kind: ClusterInterceptor
      params:
        - name: filter
          value: >-
            body.project.path_with_namespace == '<frontend-project-path>' &&
            body.ref == 'refs/heads/main' &&
            body.checkout_sha != null &&
            body.checkout_sha.matches('^[0-9a-f]{40}$') &&
            body.checkout_sha != '0000000000000000000000000000000000000000'
  template:
    ref: application-cicd-frontend-run
---
apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
  name: application-cicd-backend-git
  namespace: <pipeline-namespace>
  labels:
    app.kubernetes.io/part-of: application-cicd-demo
spec:
  bindings:
    - ref: application-cicd-git-push
  interceptors:
    - ref:
        name: gitlab
        kind: ClusterInterceptor
      params:
        - name: secretRef
          value:
            secretName: application-cicd-gitlab-webhook
            secretKey: secretToken
        - name: eventTypes
          value: [Push Hook]
    - ref:
        name: cel
        kind: ClusterInterceptor
      params:
        - name: filter
          value: >-
            body.project.path_with_namespace == '<backend-project-path>' &&
            body.ref == 'refs/heads/main' &&
            body.checkout_sha != null &&
            body.checkout_sha.matches('^[0-9a-f]{40}$') &&
            body.checkout_sha != '0000000000000000000000000000000000000000'
  template:
    ref: application-cicd-backend-run
---
apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: application-cicd-code-events
  namespace: <pipeline-namespace>
  labels:
    app.kubernetes.io/part-of: application-cicd-demo
spec:
  serviceAccountName: <code-events-service-account>
  triggers:
    - name: frontend-code
      triggerRef: application-cicd-frontend-git
    - name: backend-code
      triggerRef: application-cicd-backend-git

前端 Trigger 首先验证 GitLab 令牌和事件类型:

interceptors:
  - ref:
      name: gitlab
      kind: ClusterInterceptor
    params:
      - name: secretRef
        value:
          secretName: application-cicd-gitlab-webhook
          secretKey: secretToken
      - name: eventTypes
        value: [Push Hook]

然后使用 CEL 过滤器,仅允许预期的仓库和分支:

body.project.path_with_namespace == '<frontend-project-path>' &&
body.ref == 'refs/heads/main' &&
body.checkout_sha != null &&
body.checkout_sha.matches('^[0-9a-f]{40}$') &&
body.checkout_sha != '0000000000000000000000000000000000000000'

非空且非零的 SHA 检查会拒绝分支删除事件。这些是源文件位于根目录的 独立仓库,因此过滤器不会查找以 frontend/ 或 backend/ 开头的路径。单体仓库 需要采用不同的路径过滤策略。

打开 Triggers,创建引用 application-cicd-frontend-run 和 application-cicd-backend-run 的组件 Triggers。通过 TriggerBinding 将 revision 和 image-tag 映射到 checkout_sha。在 EventListeners 中创建 application-cicd-code-events,并添加这两个代码 Triggers。使用 YAML 视图检查拦截器和固定的模板引用。

或者,应用本地文件:

kubectl apply -f code-triggers.yaml
kubectl get eventlistener application-cicd-code-events -n <pipeline-namespace>

验证:监听器处于 Ready 状态,并且两个模板引用均存在。 创建 Trigger 或 EventListener 本身不应启动构建。

4. 配置 GitLab 并发送真实事件

在每个 GitLab 项目中,打开 Settings > Webhooks。使用已批准的代码监听器端点,配置 Secret token,并启用 Push events。GitLab 必须能够访问该端点;对于位于集群外部的 GitLab 服务器,仅集群内部可访问的 Service 地址并不足够。

向前端仓库的 main 分支推送一个小的更改。打开 PipelineRuns 并检查生成的运行:

  • 它引用的是 application-cicd-node,而不是 Go Pipeline。
  • 其 revision 和镜像标签等于事件的完整提交 SHA。
  • 克隆 URL、暂存注册表、身份和 Connectors 仍与前端 Run Template 匹配。
  • 其成功结果包括该提交和已发布的镜像摘要。

对后端重复上述操作。即使 GitLab 的 webhook 测试报告投递成功,也要测试真实提交;仅 HTTP 响应并不能证明已使用正确的参数创建 PipelineRun。

5. 验证被拒绝的事件

使用临时练习 webhook 或已批准的测试发送方。不要仅为了运行负面测试而替换 正常工作的 webhook 凭证。

事件预期的新运行
已通过身份验证的前端 main 推送一个前端 CI 运行,不运行后端 CI
已通过身份验证的后端 main 推送一个后端 CI 运行,不运行前端 CI
推送到其他分支或项目无
没有有效 checkout SHA 的分支删除无
缺少 webhook 令牌或 webhook 令牌不正确无

检查 PipelineRuns,以及 webhook 投递和 EventListener 日志。经过筛选的事件可能会被监听器确认,但不会创建运行。 Webhook 重试可能会产生重复投递;这些示例不提供去重功能。使用提交和运行标识来识别重试,并在投入生产前 应用发布队列或去重策略。

Artifact Events: 准备交接

镜像事件可以向组件的 CD Run Template 提供 artifact-digest 和 release-label。与代码 CI 不同,CD 会提升现有摘要,绝不会重新构建源代码。

以下资源使用单独的监听器和身份。它会将 Harbor 的 Authorization 标头与 Secret 进行身份验证,然后筛选确切的暂存仓库、PUSH_ARTIFACT 类型、单个镜像资源、有效摘要,以及由自动 CI 生成的 40 个字符的提交标签:

Complete Harbor artifact Trigger YAML
apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerBinding
metadata:
  name: application-cicd-artifact-push
  namespace: <pipeline-namespace>
  labels:
    app.kubernetes.io/part-of: application-cicd-demo
spec:
  params:
    - name: artifact-digest
      value: $(body.event_data.resources[0].digest)
    - name: release-label
      value: $(body.event_data.resources[0].tag)
---
apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
  name: application-cicd-backend-artifact
  namespace: <pipeline-namespace>
  labels:
    app.kubernetes.io/part-of: application-cicd-demo
spec:
  bindings:
    - ref: application-cicd-artifact-push
  interceptors:
    - ref:
        name: cel
        kind: ClusterInterceptor
      params:
        - name: filter
          value: >-
            header.canonical('Authorization').compareSecret('authorization', 'application-cicd-harbor-webhook')
    - ref:
        name: cel
        kind: ClusterInterceptor
      params:
        - name: filter
          value: >-
            body.type == 'PUSH_ARTIFACT' &&
            body.event_data.repository.repo_full_name == '<team>/backend' &&
            size(body.event_data.resources) == 1 &&
            body.event_data.resources[0].digest.matches('^sha256:[0-9a-f]{64}$') &&
            body.event_data.resources[0].tag.matches('^[0-9a-f]{40}$')
  template:
    ref: application-cicd-backend-promotion
---
apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
  name: application-cicd-frontend-artifact
  namespace: <pipeline-namespace>
  labels:
    app.kubernetes.io/part-of: application-cicd-demo
spec:
  bindings:
    - ref: application-cicd-artifact-push
  interceptors:
    - ref:
        name: cel
        kind: ClusterInterceptor
      params:
        - name: filter
          value: >-
            header.canonical('Authorization').compareSecret('authorization', 'application-cicd-harbor-webhook')
    - ref:
        name: cel
        kind: ClusterInterceptor
      params:
        - name: filter
          value: >-
            body.type == 'PUSH_ARTIFACT' &&
            body.event_data.repository.repo_full_name == '<team>/frontend' &&
            size(body.event_data.resources) == 1 &&
            body.event_data.resources[0].digest.matches('^sha256:[0-9a-f]{64}$') &&
            body.event_data.resources[0].tag.matches('^[0-9a-f]{40}$')
  template:
    ref: application-cicd-frontend-promotion
---
apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: application-cicd-artifact-events
  namespace: <pipeline-namespace>
  labels:
    app.kubernetes.io/part-of: application-cicd-demo
spec:
  serviceAccountName: <artifact-events-service-account>
  triggers:
    - name: backend-artifact
      triggerRef: application-cicd-backend-artifact
    - name: frontend-artifact
      triggerRef: application-cicd-frontend-artifact

暂时不要应用或启用 artifact webhook。其 CD Pipeline、Run Template、审批策略和应用必须先准备就绪。在 tutorial 4 中成功手动投递后再将其激活。

推送事件并不能证明镜像已通过漏洞扫描或签名验证。如果需要这些检查,请在审批前使用相应的已验证事件或策略门控。有关其他事件类型,请参阅 Harbor events。

检查点和故障排除

现在,两个组件都会根据经过身份验证的 main 推送自动构建,并且负面测试用例不会创建任何运行。

症状首要检查项
GitLab 无法投递监听器就绪状态、TLS 证书、端点路由和网络策略。
身份验证失败Secret 的命名空间和键、令牌是否相等,以及拦截器对 Secret 的访问权限。
已投递的事件未创建运行仓库路径、分支、事件类型、SHA 和监听器日志。
运行以错误的值启动TriggerBinding 映射以及所引用的 Run Template。
运行次数超出预期重复的 webhook 注册、重试,或 PAC 和 Triggers 同时处理了该事件。

对于由仓库负责的自动化,Pipelines as Code 是另一种选择:它会运行存储在 .tekton/ 下的定义。当应用团队应将执行定义与源代码一同进行版本控制时,请选择 PAC;当平台团队集中管理事件端点和模板时,请选择此 Trigger 工作流。除非你确实希望创建两次运行,否则不要为同一事件同时启用两者。

下一步:审批并投递发布版本。

上一步:构建并运行组件 CI。