Orbit Internal API

The Orbit internal API is used by the knowledge graph service. The API cannot be used by other consumers. This documentation is intended for people working on the GitLab codebase.

Add new endpoints

API endpoints should be externally accessible by default, with proper authentication and authorization. Before adding a new internal endpoint, consider if the API would benefit the wider GitLab community and can be made externally accessible.

The Orbit API uses internal endpoints because requests are authenticated with a service-level JWT token rather than a user token, and should only be accessible through an internal load balancer.

Authentication

These endpoints are all authenticated using JWT authentication from the knowledge graph.

To authenticate using the JWT, clients:

Read the knowledge graph JWT signing secret.
Use the signing key to generate a JSON Web Token (JWT) with the gkg-indexer: subject prefix.
Pass the JWT in the Gitlab-Orbit-Api-Request header.

All endpoints require the knowledge_graph_infra feature flag to be enabled.

Internal Endpoints

Project

Fetch project info

Use a GET command to get the default branch for a project.

GET /internal/orbit/project/:project_id/info

Example request:

curl --header "Gitlab-Orbit-Api-Request: <json-web-token>" "https://gitlab.example.com/api/v4/internal/orbit/project/1/info"

Example response:

{
  "project_id": 1,
  "default_branch": "main"
}

Repository

Download repository archive

Use a GET command to download a tar.gz archive of the project repository at a given ref.

GET /internal/orbit/project/:project_id/repository/archive

Attribute	Type	Required	Description
`project_id`	integer	yes	ID of the project
`ref`	string	no	Git ref to archive (branch, tag, or SHA). Defaults to the default branch.

Example request:

curl --header "Gitlab-Orbit-Api-Request: <json-web-token>" "https://gitlab.example.com/api/v4/internal/orbit/project/1/repository/archive?ref=main"

Example response:

The response body is a binary tar.gz archive streamed via Workhorse.

List repository commits

Use a GET command to get a paginated list of commits for a given ref.

GET /internal/orbit/project/:project_id/repository/commits

Attribute	Type	Required	Description
`project_id`	integer	yes	ID of the project
`ref`	string	no	Branch, tag, or SHA. Defaults to the default branch.
`since`	datetime	no	Only commits after or on this date (ISO 8601)
`until`	datetime	no	Only commits before or on this date (ISO 8601)
`order`	string	no	Sort order: `default` or `topo`. Defaults to `default`
`page`	integer	no	Page number (defaults to 1)
`per_page`	integer	no	Number of items per page (defaults to 20)

Example request:

curl --header "Gitlab-Orbit-Api-Request: <json-web-token>" "https://gitlab.example.com/api/v4/internal/orbit/project/1/repository/commits?ref=main&per_page=2"

Example response:

[
  {
    "id": "abc123def456",
    "short_id": "abc123d",
    "title": "Update README",
    "message": "Update README with new instructions",
    "author_name": "Jane Smith",
    "author_email": "jane@example.com",
    "authored_date": "2025-01-15T10:30:00.000Z",
    "committed_date": "2025-01-15T10:30:00.000Z"
  }
]