gitlab-ci-pipelines-exporter for Prometheus and OpenMetrics

GitLab CI telemetry without custom polling code

gitlab-ci-pipelines-exporter addresses a specific gap: GitLab has CI data, while Prometheus and OpenMetrics systems need time-series measurements that they can scrape and alert on. The exporter is intended for engineers and operators responsible for GitLab CI who also maintain a metrics stack. It covers pipelines and jobs as well as environments and deployments, according to the dashboard examples linked by the README. That scope is broader than merely counting successful HTTP requests.

The project does not replace GitLab's pipeline interface. Instead, it acts as a separate collection service that retrieves CI information and presents it in a monitoring format. This distinction matters for access control and failure isolation. A GitLab token must be available to the exporter, while Prometheus or another compatible system consumes its output independently.

Configuration can name individual projects, including entries such as `foo/project` and `bar/project`. It also supports wildcard ownership rules, with the documented example selecting a group named `foo`. That is useful for installations with many repositories, but it also makes permission scope and cost control part of configuration review rather than an incidental deployment detail.

Polling, GitLab data, and metric refresh

The startup log shown in the README exposes the principal collection flow. The exporter records its GitLab endpoint and separate refresh settings for pipelines, projects, and refs. The example reports `pulling-pipelines-every=60s`, `pulling-projects-every=15s`, `pulling-refs-every=10s`, and `pulling-workers=2`. These are log values from the documented startup output, not claims about every deployment. They show that different GitLab resources are refreshed on independent schedules rather than through one synchronized read.

The repository is a Go module, and its dependency list includes `gitlab.com/gitlab-org/api/client-go`. OpenTelemetry packages and OTLP trace export support are also declared, while Prometheus instrumentation comes from `github.com/prometheus/client_golang`. These dependencies are consistent with a service that talks to GitLab, exposes metrics, and includes tracing support. The README does not document every internal collector or explain which GitLab API calls each refresh performs, so those details should not be inferred.

Rate limiting is part of the operational model. The sample startup output includes `rate-limit=10rps`, and the dependencies include Redis-based rate counter packages. The logs also confirm configured wildcards, showing that project discovery is a recognized part of startup and runtime behavior. Based on the repository layout, configuration, CLI, internal, and package code are separated, but the README does not describe their complete dependency graph.

Install through Go, Docker, or Kubernetes

The simplest README installation route runs the current Go module command. This is suitable for a workstation or host with a compatible Go toolchain. The module declares `go 1.26.2`, although the Makefile still defines `GOLANG_VERSION := 1.24`, so source-build environments should verify which toolchain the selected build path actually requires.

This command downloads and runs the exporter through Go:

~$ go run github.com/mvisonneau/gitlab-ci-pipelines-exporter/cmd/gitlab-ci-pipelines-exporter@latest

Docker is another documented option. These commands run the image from Docker Hub, GitHub Container Registry, or Quay:

~$ docker run -it --rm docker.io/mvisonneau/gitlab-ci-pipelines-exporter
~$ docker run -it --rm ghcr.io/mvisonneau/gitlab-ci-pipelines-exporter
~$ docker run -it --rm quay.io/mvisonneau/gitlab-ci-pipelines-exporter

The image runs as user `65534`, exposes port `8080`, and uses `run` as its default command. Kubernetes users can add the documented chart repository and install it with a minimal `values.yml`:

~$ helm repo add mvisonneau https://charts.visonneau.fr

config:
  gitlab:
    url: https://gitlab.example.com
    token: xrN14n9-ywvAFxxxxxx
  projects:
    - name: foo/project

The example also says a token may be supplied with `--gitlab-token` or through `GCPE_GITLAB_TOKEN`. The Helm example embeds a token in `values.yml`; a real deployment should account for that file's handling, which the README does not expand upon.

First scrape with a minimal YAML configuration

The quickstart begins with a configuration file containing the GitLab URL, a token placeholder, two explicit projects, and one group wildcard. Create a local file with the following structure:

gitlab:
  url: https://gitlab.example.com
  token: <your_token>
projects:
  - name: foo/project
  - name: bar/project
wildcards:
  - owner:
      name: foo
      kind: group

If a binary is already installed, start it with the documented binary name and `--config` option:

~$ gitlab-ci-pipelines-exporter --config /etc/config.yml

The same file can be mounted into a Docker container. The README expects the container to expose port `8080` and supplies the configuration at `/etc/config.yml`:

~$ docker run -it --rm \
   --name gitlab-ci-pipelines-exporter \
   -v $(pwd)/config.yml:/etc/config.yml \
   -p 8080:8080 \
   mvisonneau/gitlab-ci-pipelines-exporter:latest \
   run --config /etc/config.yml

A successful start should produce the documented initialization log, including the configured GitLab endpoint, refresh intervals, worker count, rate limit, and configured-wildcards message. The README does not include the final metrics request or its response, so it does not establish the exact scrape URL. Grafana dashboards for pipelines, jobs, and environments are linked, and `examples/quickstart` documents a Docker Compose setup involving the exporter, Prometheus, and Grafana.

Project selection, rate limits, and GitLab access

The largest operational constraint is the relationship between wildcard scope and GitLab access. Wildcards can discover projects by owner, but the exporter still needs a token that permits the intended API operations. The README does not enumerate the exact GitLab scopes, so an administrator should not guess them from the YAML example. The token also appears in one Helm configuration example, creating a credential-management decision before deployment.

Rate limiting is visible in the example startup output, while pipelines, projects, and refs are pulled at different intervals. Selecting a large group can therefore increase request volume and processing work even if the GitLab endpoint remains available. `pulling-workers=2` is shown in the sample log, but the README does not say whether this value is a universal default or how it changes under load.

An incorrect project name or inaccessible token can leave an apparently healthy exporter with incomplete data. The README does not define retry semantics, persistence behavior, or the exact error telemetry for each GitLab failure. Operators need to inspect startup logs and their GitLab permissions rather than assuming that every absent metric means no CI activity.

Exporter versus custom API collection

The practical alternative is to write custom code that calls the GitLab API and converts selected pipeline data into Prometheus metrics yourself. That approach gives an organization exact control over endpoints, labels, query volume, and transformation logic. It also requires maintaining GitLab client behavior, authentication, pagination assumptions, metric stability, and scraper integration inside the team's own code.

gitlab-ci-pipelines-exporter packages those concerns into an existing Go service. According to the README, it already covers GitLab CI monitoring and exports data for Prometheus or any system supporting OpenMetrics. Its YAML model handles project lists and wildcard ownership, while separate pull intervals and a rate limit are represented in its startup behavior. The repository also includes webhook examples, though the README does not explain their current scope or configuration.

This is not equivalent to using GitLab's own built-in pipeline monitoring. The README links to GitLab documentation about pipeline monitoring and efficiency, but it does not provide a feature-by-feature comparison between GitLab's native facility and this exporter. The defensible distinction is architectural: GitLab presents the data, while this project supplies a dedicated Prometheus or OpenMetrics collection process. Whether that additional process is preferable depends on an installation's existing monitoring stack.

Release packaging, Go dependency, and license cost

The repository is not archived, and the last push was on 2026-10-14. Recent listed releases include `v0.6.0` on 2026-01-14, `v0.5.10` on 2025-01-14, and an `edge` release dated 2021-03-08. The release page is also the documented source for binary, DEB, and RPM artifacts. This gives operators more than one upgrade route, including Go, Snapcraft, Homebrew, Docker, Scoop, NixOS, and Helm.

Upgrade cost still depends on the route. Container and package deployments can require image or package replacement, configuration review, and compatibility checks against GitLab behavior. A source build depends on Go modules, and `go.mod` includes several release-candidate or beta dependencies, such as `github.com/vmihailenco/taskq/v4 v4.0.0-beta.4` and `github.com/xeonx/timeago v1.0.0-rc5`. Those versions are dependency declarations, not an assertion that the exporter itself is a beta release.

The project uses the Apache-2.0 license. That identifies the license granted for use and modification, but organizations still need to review their own notice, attribution, and dependency obligations. The repository includes `LICENSE`, `CHANGELOG.md`, and release packaging configuration, which are the first project-specific files to inspect when planning an upgrade.

Editorial conclusion

Adopt this project if your team operates GitLab CI and wants a configurable metrics collector instead of writing GitLab API polling code. Do not choose it for environments that cannot grant it the required GitLab access or that do not consume Prometheus or OpenMetrics. Verify access to every configured GitLab project first, then confirm the selected projects, wildcard scope, polling limits, and relevant entries in docs/metrics.md.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. mvisonneau/gitlab-ci-pipelines-exporter on GitHub
4. README
5. Releases