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

새 엔드포인트 추가#

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

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

인증#

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

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

1. 지식 그래프 JWT 서명 시크릿을 읽습니다.
2. 서명 키를 사용하여 gkg-indexer: 주체 접두사로 JSON Web Token (JWT)을 생성합니다.
3. Gitlab-Orbit-Api-Request 헤더에 JWT를 전달합니다.

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

내부 엔드포인트#

프로젝트#

프로젝트 정보 가져오기#

프로젝트의 기본 브랜치를 가져오려면 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 아카이브입니다.

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

두 커밋 간에 변경된 파일 경로를 스트리밍하려면 GET 명령을 사용합니다.

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?from=abc123&to=def456"

응답 예시:

[
  "path/to/changed_file.rb",
  "another/changed_file.go"
]

Blob 목록 조회#

저장소의 blob 목록을 조회하려면 POST 명령을 사용합니다.

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 '{"ref": "main"}' \
  "https://gitlab.example.com/api/v4/internal/orbit/project/1/repository/list_blobs"

응답 예시:

[
  {
    "oid": "abc123def456",
    "path": "path/to/file.rb",
    "size": 1024
  }
]

저장소 커밋 목록#

지정된 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 가져오기#

GET 명령을 사용하여 머지 리퀘스트의 최신 diff 버전에 대한 전체 통합 패치를 가져옵니다. 응답은 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 가져오기#

GET 명령을 사용하여 MergeRequestDiff 레코드의 파일별 diff를 가져옵니다.

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 통합 패치 가져오기#

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

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 통합 패치입니다.