🦊 gitlab-ci-pipelines-exporter

gitlab-ci-pipelines-exporter 允许您通过 Prometheus 或任何支持 OpenMetrics 格式的监控工具，监控您的 GitLab CI 流水线。有关其如何帮助提升流水线效率的更多信息，可参考 GitLab 官方文档。

概览

该工具可导出 GitLab CI 流水线的关键指标（如运行状态、持续时间、成功率等），支持与 Grafana 集成以实现可视化监控。提供多种预配置的 Grafana 仪表盘，覆盖流水线、作业、环境/部署等维度的监控需求。

仪表盘示例

流水线监控

!流水线仪表盘
Grafana 仪表盘 #10620

作业监控

!作业仪表盘
Grafana 仪表盘 #13328

环境/部署监控

!环境仪表盘
Grafana 仪表盘 #13329

如需快速体验，可参考 examples/quickstart 目录，通过 docker-compose 在约5分钟内部署包含 exporter、Prometheus 和 Grafana 的测试环境。

核心功能与特性

• 全面的指标导出：支持流水线状态、持续时间、成功率，作业执行时间、状态，环境部署状态等指标（完整指标列表见 文档）。
• 灵活的项目配置：支持通过配置文件指定监控的项目、分支、变量，或通过通配符批量匹配群组/用户下的项目。
• 高可用部署：支持多实例部署，通过 Redis 共享存储实现负载均衡和数据一致性。
• Webhook 推送：支持接收 GitLab 流水线事件 Webhook，实时更新指标，减少轮询开销。
• 多平台支持：提供 Docker 镜像，同时支持二进制、DEB/RPM 包、Kubernetes Helm Chart 等部署方式。

使用场景与适用范围

• DevOps 团队：监控 GitLab CI 流水线效率，优化构建流程。
• 开发团队：跟踪特定项目/分支的流水线成功率、作业执行时间。
• SRE/运维团队：监控关键环境部署状态，及时发现部署失败或延迟。
• 需要对接 Prometheus/Grafana 的监控体系，实现 GitLab CI 与现有监控平台的集成。

使用方法与配置说明

Docker 快速启动

基础运行

# 直接运行（需后续通过配置文件或环境变量指定 GitLab 信息）
docker run -it --rm mvisonneau/gitlab-ci-pipelines-exporter

挂载配置文件运行

1. 创建配置文件 config.yml：

gitlab:
  url: [***]  # GitLab 实例 URL
  token: <your_private_token>      # GitLab 访问令牌（需有 api 权限）
projects:
  - name: foo/project              # 需监控的项目（格式：<namespace>/<project>）
  - name: bar/project
wildcards:
  - owner:                         # 通配符匹配（批量监控群组/用户下的项目）
      name: foo                    # 群组/用户名
      kind: group                  # 类型：group 或 user

2. 通过 Docker 运行并挂载配置文件：

docker run -it --rm \
  --name gitlab-ci-pipelines-exporter \
  -v $(pwd)/config.yml:/etc/config.yml \  # 挂载配置文件
  -p 8080:8080 \                         # 暴露指标端口（默认 8080）
  mvisonneau/gitlab-ci-pipelines-exporter:latest \
  --config /etc/config.yml               # 指定配置文件路径

docker-compose 部署（含 Prometheus 和 Grafana）

参考以下 docker-compose.yml 配置（完整示例见 examples/quickstart）：

version: '3'
services:
  exporter:
    image: mvisonneau/gitlab-ci-pipelines-exporter:latest
    volumes:
      - ./config.yml:/etc/config.yml
    ports:
      - "8080:8080"
    command: --config /etc/config.yml

  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"
    depends_on:
      - exporter

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    depends_on:
      - prometheus

启动服务：

docker-compose up -d

访问 http://localhost:8080/metrics 即可查看导出的指标，通过 Grafana 导入仪表盘（ID：10620、13328、13329）可可视化监控数据。

关键配置参数

配置文件语法

完整配置语法见 文档，核心参数说明：

环境变量与命令行参数

高可用（HA）部署

通过 Redis 实现多实例共享存储，分摊 GitLab API 调用压力，确保指标一致性：

1. 配置 Redis 连接（通过配置文件或 --redis-url/GCPE_REDIS_URL）：

# config.yml 中添加
redis:
  url: redis://redis-host:6379/0  # Redis 实例 URL

2. 启动多个 exporter 实例，自动均衡负载。

Webhook 实时更新

启用 Webhook 接收 GitLab 流水线事件，减少轮询频率：

1. 配置文件中开启 Webhook：

server:
  webhook:
    enabled: true
    secret_token: <your_webhook_secret>  # 需与 GitLab Webhook 配置中的 "Secret token" 一致

2. 在 GitLab 项目/群组设置中添加 Webhook：
   • URL：[***]
   • 触发事件：勾选 "Pipeline events"
   • Secret token：填写配置文件中的 secret_token

命令行帮助

docker run -it --rm mvisonneau/gitlab-ci-pipelines-exporter --help

输出：

NAME:
   gitlab-ci-pipelines-exporter - 导出 GitLab CI 流水线状态指标

USAGE:
   gitlab-ci-pipelines-exporter [全局选项] 命令 [命令选项] [参数...]

COMMANDS:
   help, h  显示命令列表或单个命令帮助

GLOBAL OPTIONS:
   --config file, -c file        配置文件路径（默认："~/.gitlab-ci-pipelines-exporter.yml"） [$GCPE_CONFIG]
   --redis-url url               Redis URL（用于 HA 部署） [$GCPE_REDIS_URL]
   --gitlab-token token          GitLab API 访问令牌（覆盖配置文件） [$GCPE_GITLAB_TOKEN]
   --webhook-secret-token token  Webhook 验证令牌（覆盖配置文件） [$GCPE_WEBHOOK_SECRET_TOKEN]
   --log-level level             日志级别（debug,info,warn,fatal,panic）（默认："info"） [$GCPE_LOG_LEVEL]
   --log-format format           日志格式（json,text）（默认："text"） [$GCPE_LOG_FORMAT]
   --help, -h                    显示帮助（默认：false）

相关资源

• Grafana 仪表盘：
  • 流水线监控
  • 作业监控
  • 环境/部署监控
• 完整指标列表：文档
• Helm Chart：用于 Kubernetes 部署