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:

1. Read the knowledge graph JWT signing secret.
2. Use the signing key to generate a JSON Web Token (JWT) with the gkg-indexer: subject prefix.
3. 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

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:

200

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

Stream changed file paths

Use a GET command to stream changed file paths between two tree revisions as newline-delimited JSON via Workhorse. Proxies to the Gitaly FindChangedPaths RPC. Returns 400 if left_tree_revision is not an ancestor of right_tree_revision (force push detected).

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

Example request:

curl --header "Gitlab-Orbit-Api-Request: <json-web-token>" "https://gitlab.example.com/api/v4/internal/orbit/project/1/repository/changed_paths?left_tree_revision=abc123&right_tree_revision=def456"

Example response (newline-delimited JSON streamed via Workhorse):

{"path":"app/models/user.rb","status":"MODIFIED","old_path":"","new_mode":33188,"old_blob_id":"aaa111","new_blob_id":"bbb222"}
{"path":"README.md","status":"ADDED","old_path":"","new_mode":33188,"old_blob_id":"","new_blob_id":"ccc333"}
{"path":"old_file.rb","status":"DELETED","old_path":"","new_mode":0,"old_blob_id":"ddd444","new_blob_id":""}

List blobs

Use a POST command to stream blob contents for given revisions as length-prefixed protobuf frames via Workhorse. Proxies to the Gitaly ListBlobs RPC. Blobs larger than bytes_limit are truncated.

POST /internal/orbit/project/:project_id/repository/list_blobs

Example request:

curl --request POST --header "Gitlab-Orbit-Api-Request: <json-web-token>" \
  --header "Content-Type: application/json" \
  --data '{"revisions": ["def456", "--not", "abc123"]}' \
  "https://gitlab.example.com/api/v4/internal/orbit/project/1/repository/list_blobs"

The response body is a binary stream of ListBlobsResponse protobuf frames. Each frame is preceded by a 4-byte big-endian length prefix indicating the size of the following protobuf message.

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

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"
  }
]