> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Gitlab

> OpenTelemetry receiver for Gitlab

# Gitlab Receiver

![Status](https://img.shields.io/badge/status-alpha-red)

**Available in:** `contrib`

**Maintainers:** [@adrielp](https://github.com/adrielp), [@atoulme](https://github.com/atoulme), [@niwoerner](https://github.com/niwoerner)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/gitlabreceiver)

## Supported Telemetry

![Traces](https://img.shields.io/badge/traces-alpha-orange)

## Overview

## Traces - Getting Started

Workflow tracing support is actively being added to the GitLab receiver.
This is accomplished through the processing of GitLab webhook
events for pipelines. The [`pipeline`](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html#pipeline-events) event payloads are then constructed into `trace`
telemetry.

Each GitLab pipeline, along with its jobs, is converted
into trace spans, allowing the observation of workflow execution times,
success, and failure rates.

### Configuration

**IMPORTANT**: Ensure your WebHook endpoint is secured with a secret and a Web
Application Firewall (WAF) or other security measure.

The WebHook configuration exposes the following settings:

* `endpoint`: (default = `localhost:8080`) - The address and port to bind the WebHook to.
* `path`: (default = `/events`) - The path for Action events to be sent to.
* `health_path`: (default = `/health`) - The path for health checks.
* `secret`: (optional) - The secret used to [validate the payload](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#custom-headers).
* `required_headers`: (optional) - One or more key-value pairs representing required headers for incoming requests. These headers must not conflict with the fixed default GitLab headers. See the customizable and fixed GitLab headers in [config.go](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/gitlabreceiver/config.go).
* `include_user_attributes`: (default = `false`) - When enabled, includes user information such as commit author details (name, email), commit messages, and pipeline actor information (username, name) in the span attributes.

The WebHook configuration block also accepts all the [confighttp](https://pkg.go.dev/go.opentelemetry.io/collector/config/confighttp#ServerConfig)
settings.

An example configuration is as follows:

```yaml theme={null}
receivers:
    gitlab:
        webhook:
            endpoint: localhost:19418
            path: /events
            health_path: /health
            secret: ${env:SECRET_STRING_VAR}
            required_headers:
                WAF-Header: "value"
            include_user_attributes: false
```

For tracing, all configuration is set under the `webhook` key. The full set
of exposed configuration values can be found in [`config.go`](config.go).

## Tracing Limitations

### Deterministic Trace/Span IDs and Manual Instrumentation

The GitLab receiver creates deterministic trace/span IDs for pipelines by using an unique pipeline/job ID and the pipeline's `finished_at` timestamp. This approach ensures that the same pipeline execution always generates the same ID.

**Limitation**: Manual instrumentation within GitLab pipeline jobs is currently not possible. Since the trace ID generation requires the `finished_at` timestamp, which is only available once the pipeline has completed, it's not possible to generate the same traceID within running jobs to correlate manually instrumented spans with the automatically created pipeline spans. More details can be found [here](https://github.com/open-telemetry/semantic-conventions/issues/1749#issuecomment-2772544215).

This means:

* The receiver can automatically create traces/spans for GitLab pipelines
* You cannot manually instrument code within your pipeline jobs and have those spans appear in the same trace as the pipeline spans

### Child and Multi-Project Pipelines

**Limitation**: Child and multi-project pipelines are not supported yet. The hierarchy between parent/trigger pipelines wouldn't be reflected correctly, and instead two independent traces would be created for each pipeline. This means that the parent-child relationship between pipelines is not preserved in the generated traces.

## Configuration

### Example Configuration

```yaml theme={null}
receivers:
  gitlab:
    webhook:
      endpoint: localhost:8080
      read_timeout: "500ms"
      write_timeout: "500ms"
      path: "some/path"
      health_path: "health/path"
      required_headers:
        key1-present: "value1-present"

  gitlab/customname:
    webhook:
      endpoint: localhost:8080
      read_timeout: "500ms"
      write_timeout: "500ms"
      path: "some/path"
      health_path: "health/path"
      required_headers:
        key1-present: "value1-present"
        key2-present: "value2-present" 
        User-Agent: "GitLab/1.2.3-custom-version"        
        X-Gitlab-Instance: "https://gitlab.self-hosted.xyz"
        
processors:
  nop:

exporters:
  nop:

service:
  pipelines:
    traces:
      receivers: [gitlab, gitlab/customname]
      processors: [nop]
      exporters: [nop]
```

***

*Last generated: 2026-07-06*