Service Ping internal API

The Service Ping internal API is used by services that report Service Ping on behalf of a GitLab instance, such as the Service Ping exporter. The API cannot be used by other consumers. This documentation is intended for people working on the GitLab codebase.

Authentication

Requests require Workhorse internal API authentication and a Service Ping JSON Web Token (JWT).

To create the JWT, clients:

  1. Read the Service Ping secret. The secret is in the file set by service_ping.secret_file in gitlab.yml, by default .gitlab_service_ping_secret in the GitLab Rails root. GitLab creates the file at startup if the file does not exist.
  2. Sign a JWT with the secret and the HS256 algorithm, with these claims:
    • iss: gitlab-service-ping
    • aud: gitlab
    • sub: The name of the calling service, for example service-ping-exporter.
    • iat: The current time. GitLab rejects tokens issued more than five minutes ago.
  3. Pass the JWT in the Gitlab-Service-Ping-Api-Request header.

Internal endpoints

Fetch the instance identity and Service Ping settings

Use a GET request to retrieve the identity of the instance and its Service Ping settings.

GET /internal/service_ping/instance

Example request:

shell
curl --header "Gitlab-Service-Ping-Api-Request: <json-web-token>" "https://gitlab.example.com/api/v4/internal/service_ping/instance"

Example response:

json
{
  "identity": {
    "instance_id": "d4f5e6a7-1b2c-4d3e-8f9a-0b1c2d3e4f5a",
    "unique_instance_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "host_name": "gitlab.example.com",
    "instance_version": "18.6.0-ee"
  },
  "settings": {
    "service_ping_enabled": true,
    "service_ping_generation_enabled": true,
    "service_ping_optional_metrics_enabled": true
  }
}

service_ping_enabled reports whether the instance is allowed to send Service Ping, including when the license requires Service Ping. Rails sends Service Ping only when service_ping_generation_enabled is also true. Fields are only added, never renamed or removed, so older clients keep working.