Orbit 내부 API는 지식 그래프 서비스에서 사용됩니다. 이 API는 다른 소비자가 사용할 수 없습니다. 이 문서는 GitLab 코드베이스에서 작업하는 사람들을 위한 것입니다.

새 엔드포인트 추가#

API 엔드포인트는 적절한 인증 및 권한 부여를 통해 기본적으로 외부에서 접근 가능해야 합니다. 새로운 내부 엔드포인트를 추가하기 전에, API가 더 넓은 GitLab 커뮤니티에 이점을 줄 수 있는지, 외부에서 접근 가능하게 만들 수 있는지 고려하세요.

Orbit API는 요청이 사용자 토큰이 아닌 서비스 수준 JWT 토큰으로 인증되고 내부 로드 밸런서를 통해서만 접근 가능해야 하기 때문에 내부 엔드포인트를 사용합니다.

인증#

이러한 엔드포인트는 모두 지식 그래프의 JWT 인증을 사용하여 인증됩니다.

JWT를 사용하여 인증하려면 클라이언트가:

• 지식 그래프 JWT 서명 시크릿을 읽습니다.

• 서명 키를 사용하여 gkg-indexer: 주체 접두사로 JSON Web Token (JWT)을 생성합니다.

• Gitlab-Orbit-Api-Request 헤더에 JWT를 전달합니다.

모든 엔드포인트는 knowledge_graph_infra 피처 플래그가 활성화되어 있어야 합니다.

지식 그래프 서비스가 이 엔드포인트를 호출하면, 요청은 인증된 사용자 컨텍스트에서 실행됩니다. 그 결과, 프로젝트 감사 이벤트에는 인덱서 활동에 의해 트리거되었지만 직접적인 사용자 액션이 아닌 저장소 작업(예: repository_download_operation)을 수행하는 인증된 사용자가 표시될 수 있습니다.

내부 엔드포인트#

프로젝트#

프로젝트 정보 가져오기#

프로젝트의 기본 브랜치를 가져오려면 GET 명령을 사용합니다.

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

요청 예시:

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

응답 예시:

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

저장소#

저장소 아카이브 다운로드#

지정된 ref에서 프로젝트 저장소의 tar.gz 아카이브를 다운로드하려면 GET 명령을 사용합니다.

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

요청 예시:

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

응답 예시:

200

응답 본문은 Workhorse를 통해 스트리밍되는 바이너리 tar.gz 아카이브입니다.

이 엔드포인트를 호출하면 인덱서가 대신 행동하는 인증된 사용자에게 귀속된 repository_download_operation 감사 이벤트가 트리거됩니다. 이는 직접적인 사용자 액션이 아닙니다.

변경된 파일 경로 스트리밍#

두 트리 리비전 사이의 변경된 파일 경로를 Workhorse를 통해 개행 구분자 JSON으로 스트리밍하려면 GET 명령을 사용합니다. Gitaly FindChangedPaths RPC로 프록시됩니다. left_tree_revision이 right_tree_revision의 조상이 아닌 경우 400을 반환합니다 (강제 푸시 감지).

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

요청 예시:

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"

응답 예시 (Workhorse를 통해 스트리밍되는 개행 구분자 JSON):

{"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":""}

Blob 목록 조회#

지정된 리비전에 대한 blob 콘텐츠를 Workhorse를 통해 길이 접두사 protobuf 프레임으로 스트리밍하려면 POST 명령을 사용합니다. Gitaly ListBlobs RPC로 프록시됩니다. bytes_limit보다 큰 blob은 잘립니다.

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

요청 예시:

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"

응답 본문은 ListBlobsResponse protobuf 프레임의 바이너리 스트림입니다. 각 프레임 앞에는 이후 protobuf 메시지의 크기를 나타내는 4바이트 빅엔디언 길이 접두사가 붙습니다.

저장소 커밋 목록#

지정된 ref에 대한 페이지별 커밋 목록을 가져오려면 GET 명령을 사용합니다.

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

요청 예시:

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"

응답 예시:

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

머지 리퀘스트#

diff 엔드포인트는 두 가지 형식으로 제공됩니다:

• 파일별 JSON diff (merge_request_diffs/:diff_id)는 변경된 각 파일의 diff 콘텐츠와 메타데이터(경로, 모드, 이름 변경/삭제 상태)를 반환합니다. MergeRequestDiffFile 레코드를 읽습니다. paths 파라미터를 사용하여 특정 파일만 요청할 수 있습니다.

• Raw 통합 패치 (merge_requests/:iid/raw_diffs 또는 merge_request_diffs/:diff_id/raw_diffs)는 Gitaly에서 계산하고 Workhorse를 통해 스트리밍된 전체 diff를 text/plain으로 반환합니다.

머지 리퀘스트 최신 버전의 raw diff 가져오기#

머지 리퀘스트의 최신 diff 버전에 대한 전체 통합 패치를 가져오려면 GET 명령을 사용합니다. 응답은 Workhorse를 통해 text/plain으로 스트리밍됩니다.

GET /internal/orbit/project/:project_id/merge_requests/:merge_request_iid/raw_diffs

요청 예시:

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

응답은 Workhorse를 통해 스트리밍되는 text/plain 통합 패치입니다.

머지 리퀘스트 diff#

이 엔드포인트는 데이터베이스 ID로 특정 MergeRequestDiff 버전을 처리합니다.

머지 리퀘스트 diff의 파일별 diff 가져오기#

MergeRequestDiff 레코드의 파일별 diff를 가져오려면 GET 명령을 사용합니다.

GET /internal/orbit/project/:project_id/merge_request_diffs/:diff_id

요청 예시:

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

응답 예시:

{
  "id": 42,
  "head_commit_sha": "abc123def456",
  "base_commit_sha": "789fed012cba",
  "start_commit_sha": "456abc789def",
  "diffs": [
    {
      "diff": "@@ -1,3 +1,4 @@\n...",
      "collapsed": false,
      "too_large": false,
      "new_path": "app/models/user.rb",
      "old_path": "app/models/user.rb",
      "a_mode": "100644",
      "b_mode": "100644",
      "new_file": false,
      "renamed_file": false,
      "deleted_file": false,
      "generated_file": false
    }
  ]
}

머지 리퀘스트 diff의 raw 통합 패치 가져오기#

MergeRequestDiff 레코드의 전체 통합 패치를 Workhorse를 통해 스트리밍되는 text/plain으로 가져오려면 GET 명령을 사용합니다.

GET /internal/orbit/project/:project_id/merge_request_diffs/:diff_id/raw_diffs

요청 예시:

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

응답은 Workhorse를 통해 스트리밍되는 text/plain 통합 패치입니다.