내부 API

내부 API는 다양한 GitLab 구성 요소에서 사용되며 다른 소비자에서는 사용할 수 없습니다. 이 문서는 GitLab 코드베이스에서 작업하는 사람들을 위해 작성되었습니다.

GitLab Pages에서 사용하는 내부 API에 대한 정보는 아직이 문서에 포함되어 있지 않습니다.

GitLab 구독 내부 API에 대한 자세한 내용은 전용 페이지를 참조하십시오.

새로운 엔드포인트 추가

API 엔드포인트는 기본적으로 외부에서 액세스할 수 있어야 하며 적절한 인증 및 권한 부여가 되어야 합니다. 새로운 내부 엔드포인트를 추가하기 전에 해당 API가 넓은 GitLab 커뮤니티에 이점을 제공하고 외부적으로 액세스할 수 있는지를 고려하십시오.

가끔 내부 API 엔드포인트를 우대하는 이유 중 하나는 해당 엔드포인트를 사용하는 데 내부 데이터가 필요한 경우입니다. 예를 들어, 내부 Pages API에서는 외부 액터가 가지지 못한 비공개 토큰을 사용하거나 해당 엔드포인트에만 액세스할 수 있는 공개 키로 요청에 서명할 수 있습니다.

내부 API로 무언가를 분리하는 또 다른 이유는 해당 API 엔드포인트로의 요청이 엣지(공개) 로드 밸런서를 통해 절대로 전달되지 말아야 할 때입니다. 이렇게 함으로써 해당 엔드포인트에 대해 다른 속도 제한 규칙 및 정책을 구성할 수 있으며, 내부 요청만이 내부 로드 밸런서를 통해 해당 엔드포인트로 전달되기 때문에 이를 확인할 수 있습니다.

인증

이러한 메소드들은 모두 공유 비밀로 인증됩니다. 이 비밀은 기본적으로 config/gitlab.yml에 구성된 경로의 파일에 저장되어 있으며, 기본적으로 이 파일은 레일 앱의 루트에 있는 .gitlab_shell_secret라는 이름을 가지고 있습니다.

해당 토큰을 사용하여 인증하려면, 클라이언트는:

  1. 해당 파일의 내용을 읽습니다.
  2. 파일 내용을 사용하여 JSON Web Token (JWT)을 생성합니다.
  3. 생성된 JWT를 Gitlab-Shell-Api-Request 헤더에 전달합니다.

Git 인증

Gitaly 및 GitLab Shell에서 호출되어 리포지토리 액세스를 확인합니다.

  • GitLab Shell에서 호출될 때: 변경 사항이 전달되지 않으며, 내부 API는 Gitaly로 요청을 전달하는 데 필요한 정보를 응답합니다.
  • Gitaly의 pre-receive 후크에서 호출될 때: 변경 사항이 전달되어 푸시가 허용되는지 확인됩니다.

각 호출은 최대 50초로 제한됩니다.

이 엔드포인트는 자세하게 다루어져 있어서 별도의 페이지에 포함되어 있습니다. 

POST /internal/allowed
속성 유형 필요 여부 설명
key_id string no GitLab Shell에 연결하는 데 사용된 SSH 키 ID
username string no GitLab Shell에 연결하는 데 사용된 인증서의 사용자 이름
project string no (만약 gl_repository가 전달되었다면 필요하지 않음) 프로젝트 경로
gl_repository string no (만약 project가 전달되었다면 필요하지 않음) project-7와 같은 리포지토리 식별자
protocol string yes GitLab Shell에서 호출되었을 때는 SSH, Gitaly에서 호출되었을 때는 HTTP 또는 SSH
action string yes 실행 중인 Git 명령 (git-upload-pack, git-receive-pack, git-upload-archive)
changes string yes Gitaly에서 호출될 때는 <oldrev> <newrev> <refname>, GitLab Shell에서 호출될 때는 매직 문자열 _any
check_ip string no GitLab Shell로의 호출이 일어난 IP 주소

예시 요청: 

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT 토큰>" \
     --data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" \
     "http://localhost:3001/api/v4/internal/allowed"

예시 응답: 

{
  "status": true,
  "gl_repository": "project-3",
  "gl_project_path": "gnuwget/wget2",
  "gl_id": "user-1",
  "gl_username": "root",
  "git_config_options": [],
  "gitaly": {
    "repository": {
      "storage_name": "default",
      "relative_path": "@hashed/4e/07/4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce.git",
      "git_object_directory": "",
      "git_alternate_object_directories": [],
      "gl_repository": "project-3",
      "gl_project_path": "gnuwget/wget2"
    },
    "address": "unix:/Users/bvl/repos/gitlab/gitaly.socket",
    "token": null
  },
  "gl_console_messages": []
}

알려진 이용자

  • Gitaly
  • GitLab Shell

LFS 인증

이 엔드포인트는 SSH를 통해 리포지토리에 액세스할 때 LFS 클라이언트에게 정보를 제공하기 위해 GitLab Shell에서 호출됩니다.

속성 유형 필요 여부 설명
key_id string no GitLab Shell에 연결하는 데 사용된 SSH 키 ID
username string no GitLab Shell에 연결하는 데 사용된 인증서의 사용자 이름
project string no 프로젝트 경로

예시 요청: 

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT 토큰>" \
     --data "key_id=11&project=gnuwget/wget2" "http://localhost:3001/api/v4/internal/lfs_authenticate"

{
  "username": "root",
  "lfs_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImFjdG9yIjoicm9vdCJ9LCJqdGkiOiIyYWJhZDcxZC0xNDFlLTQ2NGUtOTZlMi1mODllYWRiMGVmZTYiLCJpYXQiOjE1NzAxMTc2NzYsIm5iZiI6MTU3MDExNzY3MSwiZXhwIjoxNTcwMTE5NDc2fQ.g7atlBw1QMY7QEBVPE0LZ8ZlKtaRzaMRmNn41r2YITM",
  "repository_http_path": "http://localhost:3001/gnuwget/wget2.git",
  "expires_in": 1800
}

알려진 소비자

  • GitLab Shell

인증된 키 확인

이 엔드포인트는 GitLab Shell이 호출하는 인증된 키 확인입니다. 이는 OpenSSH 또는 GitLab SSHD가 빠른 SSH 키 조회를 위해 호출합니다.

속성 유형 필수 설명
key 문자열 예 공개 키 인증에 사용된 허가된 키입니다. 
GET /internal/authorized_keys

예시 요청: 

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/authorized_keys?key=<key>"

예시 응답: 

{
  "id": 11,
  "title": "admin@example.com",
  "key": "ssh-rsa ...",
  "created_at": "2019-06-27T15:29:02.219Z"
}

알려진 소비자

  • GitLab Shell

인증된 인증서

이 엔드포인트는 GitLab Shell에 의해 호출되어 특정 CA SSH 인증서를 구성한 네임스페이스를 가져오거나 user_identifier를 사용하여 지정된 식별자에 대한 GitLab 사용자를 반환합니다.

속성 유형 필수 설명
key 문자열 예 SSH 인증서의 지문입니다.
user_identifier 문자열 예 SSH 인증서가 발급된 사용자의 식별자(사용자 이름 또는 기본 이메일)입니다. 
GET /internal/authorized_certs

예시 요청: 

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/authorized_certs?key=<key>&user_identifier=<user_identifier>"

예시 응답: 

{
  "success": true,
  "namespace": "gitlab-org",
  "username": "root"
}

알려진 소비자

  • GitLab Shell

사용자 ID 또는 키에 대한 사용자 가져오기

이 엔드포인트는 사용자가 ssh git@gitlab.com를 수행할 때 사용됩니다. SSH 키와 관련된 사용자를 알아냅니다.

속성 유형 필수 설명
key_id 정수 아니오 허가된 키 파일이나 /authorized_keys 확인을 통해 찾은 SSH 키의 ID입니다.
username 문자열 아니오 인증서를 사용하여 인증하는 GitLab Shell에서 사용되는 사용자 이름입니다. 
GET /internal/discover

예시 요청: 

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/discover?key_id=7"

예시 응답: 

{
  "id": 7,
  "name": "Dede Eichmann",
  "username": "rubi"
}

알려진 소비자

  • GitLab Shell

인스턴스 정보

인스턴스에 대한 일반적인 정보를 얻습니다. 이는 Geo 노드가 서로에 대한 정보를 얻기 위해 사용됩니다. 

GET /internal/check

예시 요청: 

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/check"

예시 응답: 

{
  "api_version": "v4",
  "gitlab_version": "12.3.0-pre",
  "gitlab_rev": "d69c988e6a6",
  "redis": true
}

알려진 소비자

  • GitLab Geo
  • GitLab Shell의 bin/check
  • Gitaly

SSH 키를 사용하여 새 2단계 인증 복구 코드 가져오기

이는 GitLab Shell에서 호출되어 사용자가 SSH 키를 기반으로 새 2단계 인증 복구 코드를 받을 수 있게 합니다.

속성 유형 필수 설명
key_id 정수 아니오 허가된 키 파일이나 /authorized_keys 확인을 통해 찾은 SSH 키의 ID입니다.
user_id 정수 아니오 늘어진 새 복구 코드를 생성할 사용자 ID 
GET /internal/two_factor_recovery_codes

예시 요청: 

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "key_id=7" "http://localhost:3001/api/v4/internal/two_factor_recovery_codes"

예시 응답: 

{
  "success": true,
  "recovery_codes": [
    "d93ee7037944afd5",
    "19d7b84862de93dd",
    "1e8c52169195bf71",
    "be50444dddb7ca84",
    "26048c77d161d5b7",
    "482d5c03d1628c47",
    "d2c695e309ce7679",
    "dfb4748afc4f12a7",
    "0e5f53d1399d7979",
    "af04d5622153b020"
  ]
}

알려진 소비자

  • GitLab Shell

새 개인 액세스 토큰 가져오기

GitLab Shell에서 호출되어 사용자가 새로운 개인 액세스 토큰을 생성할 수 있게 합니다.

속성 유형 필수 설명
name 문자열 예 새 토큰의 이름입니다.
scopes 문자열 배열 예 새 토큰의 승인 범위입니다. 이러한 범위는 유효한 토큰 범위여야 합니다.
expires_at 문자열 아니오 새 토큰의 만료일입니다.
key_id 정수 아니오 허가된 키 파일이나 /authorized_keys 확인을 통해 찾은 SSH 키의 ID입니다.
user_id 정수 아니오 새 토큰을 생성할 사용자 ID입니다. 
POST /internal/personal_access_token

예시 요청: 

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "user_id=29&name=mytokenname&scopes[]=read_user&scopes[]=read_repository&expires_at=2020-07-24" \
     "http://localhost:3001/api/v4/internal/personal_access_token"

예시 응답: 

{
  "success": true,
  "token": "Hf_79B288hRv_3-TSD1R",
  "scopes": ["read_user","read_repository"],
  "expires_at": "2020-07-24"
}

알려진 소비자

  • GitLab Shell

오류 추적 요청 인증

이 엔드포인트는 오류 추적 Go REST API 어플리케이션에서 프로젝트를 인증하기 위해 호출됩니다. > GitLab 15.1에 도입되었습니다.

속성 유형 필수 설명
project_id 정수 예 연관된 키를 가진 프로젝트의 ID
public_key 문자열 예 통합된 오류 추적 기능에서 생성된 공개 키 
POST /internal/error_tracking/allowed

예시 요청: 

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT 토큰>" \
     --data "project_id=111&public_key=generated-error-tracking-key" \
          "http://localhost:3001/api/v4/internal/error_tracking/allowed"

예시 응답: 

{ "enabled": true }

알려진 소비자

  • OpsTrace

사전 수신 시 카운터 증가

이것은 수락될 수 있는 푸시를위한 참조 카운터를 증가시키는 Gitaly 훅에서 호출됩니다.

속성 유형 필수 설명
gl_repository 문자열 예 푸시를받는 저장소의 저장소 식별자 
POST /internal/pre_receive

예시 요청: 

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT 토큰>" \
     --data "gl_repository=project-7" "http://localhost:3001/api/v4/internal/pre_receive"

예시 응답: 

{
  "reference_counter_increased": true
}

PostReceive

푸시를 받은 후 Gitaly에서 호출됩니다. 이것은 PostReceive-worker를 Gitaly에서 트리거하며, 전달된 푸시 옵션을 처리하고 사용자에게 표시해야하는 메시지를 포함하여 응답을 작성합니다.

속성 유형 필수 설명
identifier 문자열 예 푸시를 실행하는 사용자를 식별하는 user-[id] 또는 key-[id]
gl_repository 문자열 예 푸시되는 저장소의 식별자
push_options 문자열 배열 아니요 푸시 옵션의 배열
changes 문자열 아니요 oldrev newrev refname\n 형식의 푸시에 대해 업데이트 될 참조. 
POST /internal/post_receive

예시 요청: 

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT 토큰>" \
     --data "gl_repository=project-7" --data "identifier=user-1" \
     --data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" \
     "http://localhost:3001/api/v4/internal/post_receive"

예시 응답: 

{
  "messages": [
    {
      "message": "Hello from post-receive",
      "type": "alert"
    }
  ],
  "reference_counter_decreased": true
}

GitLab 에이전트 엔드포인트

History

다음 엔드포인트는 다양한 목적으로 GitLab 에이전트 서버(kas)에서 사용됩니다.

이러한 엔드포인트 모두 JWT를 사용하여 인증됩니다. JWT 비밀은 config/gitlab.yml에서 지정된 파일에 저장됩니다. 기본적으로 위치는 .gitlab_kas_secret라는 파일로 GitLab Rails 어플리케이션의 루트에 있습니다.

GitLab 에이전트 정보

GitLab 에이전트 서버(kas)에서 특정 에이전트 토큰에 대한 에이전트 정보를 검색하기 위해 호출됩니다. 이는 kas가 에이전트의 구성을 가져 오고 업데이트하기 위해 에이전트 프로젝트의 Gitaly 연결 정보를 반환합니다. 

GET /internal/kubernetes/agent_info

예시 요청: 

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT 토큰>" \
     --header "Authorization: Bearer <에이전트 토큰>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info"

GitLab 에이전트 프로젝트 정보

GitLab 에이전트 서버(kas)에서 특정 에이전트 토큰에 대한 프로젝트 정보를 검색하기 위해 호출됩니다. 이는 요청된 프로젝트의 Gitaly 연결을 반환합니다. GitLab kas는 이를 사용하여 프로젝트 저장소에서 Kubernetes 자원을 동기화하기 위해 에이전트를 구성합니다.

공개 프로젝트만 지원됩니다. 비공개 프로젝트의 경우 에이전트가 인가되는 기능은 아직 구현되지 않았습니다.

속성 유형 필수 설명
id 정수/문자열 예 프로젝트의 ID 또는 URL 인코딩 된 경로 
GET /internal/kubernetes/project_info

예시 요청: 

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT 토큰>" \
     --header "Authorization: Bearer <에이전트 토큰>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7"

GitLab 에이전트 사용량 메트릭

GitLab 에이전트 서버(kas)에서 사용량 메트릭 카운터를 증가시키기위해 호출됩니다.

속성 유형 필수 설명
counters 해시 아니요 카운터 해시
counters["k8s_api_proxy_request"] 정수 아니요 k8s_api_proxy_request 카운터를 증가시킬 숫자
counters["flux_git_push_notifications_total"] 정수 아니요 flux_git_push_notifications_total 카운터를 증가시킬 숫자
counters["k8s_api_proxy_requests_via_ci_access"] 정수 아니요 k8s_api_proxy_requests_via_ci_access 카운터를 증가시킬 숫자
counters["k8s_api_proxy_requests_via_user_access"] 정수 아니요 k8s_api_proxy_requests_via_user_access 카운터를 증가시킬 숫자
counters["k8s_api_proxy_requests_via_pat_access"] 정수 아니요 k8s_api_proxy_requests_via_pat_access 카운터를 증가시킬 숫자
unique_counters 해시 아니요 고유 번호 배열
unique_counters["k8s_api_proxy_requests_unique_users_via_ci_access"] 정수 배열 아니요 ci_access를 통해 CI 터널과 상호 작용한 고유 사용자 ID 집합으로 k8s_api_proxy_requests_unique_users_via_ci_access 메트릭 이벤트를 추적
unique_counters["k8s_api_proxy_requests_unique_agents_via_ci_access"] 정수 배열 아니요 ci_access를 통해 CI 터널과 상호 작용한 고유 에이전트 ID 집합으로 k8s_api_proxy_requests_unique_agents_via_ci_access 메트릭 이벤트를 추적
unique_counters["k8s_api_proxy_requests_unique_users_via_user_access"] 정수 배열 아니요 user_access를 통해 CI 터널과 상호 작용한 고유 사용자 ID 집합으로 k8s_api_proxy_requests_unique_users_via_user_access 메트릭 이벤트를 추적
unique_counters["k8s_api_proxy_requests_unique_agents_via_user_access"] 정수 배열 아니요 user_access를 통해 CI 터널과 상호 작용한 고유 에이전트 ID 집합으로 k8s_api_proxy_requests_unique_agents_via_user_access 메트릭 이벤트를 추적
unique_counters["k8s_api_proxy_requests_unique_users_via_pat_access"] 정수 배열 아니요 PAT를 사용하여 KAS Kubernetes API 프록시를 사용한 고유 사용자 ID 집합을 추적하여 k8s_api_proxy_requests_unique_users_via_pat_access 메트릭 이벤트를 추적
unique_counters["k8s_api_proxy_requests_unique_agents_via_pat_access"] 정수 배열 아니요 PAT를 사용하여 KAS Kubernetes API 프록시를 사용한 고유 에이전트 ID 집합을 추적하여 k8s_api_proxy_requests_unique_agents_via_pat_access 메트릭 이벤트를 추적
unique_counters["flux_git_push_notified_unique_projects"] 정수 배열 아니요 고유한 프로젝트 ID 집합을 추적하여 flux_git_push_notified_unique_projects 메트릭 이벤트를 추적 
POST /internal/kubernetes/usage_metrics

예시 요청: 

curl --request POST --header "Gitlab-Kas-Api-Request: <JWT 토큰>" --header "Content-Type: application/json" \
     --data '{"counters": {"k8s_api_proxy_request":1}}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics"

GitLab 에이전트 이벤트

GitLab 에이전트 서버(kas)에서 이벤트를 추적하기 위해 호출됩니다.

속성 유형 필수 설명
events 해시 아니오 이벤트의 해시
events["k8s_api_proxy_requests_unique_users_via_ci_access"] 해시 배열 아니오 k8s_api_proxy_requests_unique_users_via_ci_access 이벤트 배열
events["k8s_api_proxy_requests_unique_users_via_ci_access"]["user_id"] 정수 아니오 이벤트에 대한 사용자 ID
events["k8s_api_proxy_requests_unique_users_via_ci_access"]["project_id"] 정수 아니오 이벤트에 대한 프로젝트 ID
events["k8s_api_proxy_requests_unique_users_via_user_access"] 해시 배열 아니오 k8s_api_proxy_requests_unique_users_via_user_access 이벤트 배열
events["k8s_api_proxy_requests_unique_users_via_user_access"]["user_id"] 정수 아니오 이벤트에 대한 사용자 ID
events["k8s_api_proxy_requests_unique_users_via_user_access"]["project_id"] 정수 아니오 이벤트에 대한 프로젝트 ID
events["k8s_api_proxy_requests_unique_users_via_pat_access"] 해시 배열 아니오 k8s_api_proxy_requests_unique_users_via_pat_access 이벤트 배열
events["k8s_api_proxy_requests_unique_users_via_pat_access"]["user_id"] 정수 아니오 이벤트에 대한 사용자 ID
events["k8s_api_proxy_requests_unique_users_via_pat_access"]["project_id"] 정수 아니오 이벤트에 대한 프로젝트 ID 
POST /internal/kubernetes/agent_events

예시 요청: 

curl --request POST \
  --url "http://localhost:3000/api/v4/internal/kubernetes/agent_events" \
  --header "Gitlab-Kas-Api-Request: <JWT 토큰>" \
  --header "Content-Type: application/json" \
  --data '{
    "events": {
      "k8s_api_proxy_requests_unique_users_via_ci_access": [
        {
          "user_id": 1,
          "project_id": 1
        }
      ]
    }
  }'

Starboard 취약점 생성

GitLab 에이전트 서버(kas)에서 Starboard 취약점 보고서로부터 보안 취약성을 생성하기 위해 호출됩니다. 이 요청은 멱등성을 갖습니다. 동일한 데이터로 여러 요청을 보내도 단일 취약성이 생성됩니다. 응답에는 생성된 취약성 발견의 UUID가 포함됩니다.

속성 유형 필수 설명
vulnerability 해시 예 보고서 스키마와 일치하는 취약성 데이터vulnerability 필드.
scanner 해시 예 보고서 스키마와 일치하는 스캐너 데이터 scanner 필드. 
PUT internal/kubernetes/modules/starboard_vulnerability

예시 요청: 

curl --request PUT --header "Gitlab-Kas-Api-Request: <JWT 토큰>" \
     --header "Authorization: Bearer <에이전트 토큰>" --header "Content-Type: application/json" \
     --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability" \
     --data '{
  "vulnerability": {
    "name": "libc의 CVE-123-4567",
    "severity": "높음",
    "confidence": "알 수 없음",
    "location": {
      "kubernetes_resource": {
        "namespace": "production",
        "kind": "deployment",
        "name": "nginx",
        "container": "nginx"
      }
    },
    "identifiers": [
      {
        "type": "cve",
        "name": "CVE-123-4567",
        "value": "CVE-123-4567"
      }
    ]
  },
  "scanner": {
    "id": "starboard_trivy",
    "name": "Trivy (Starboard Operator를 통해)",
    "vendor": "GitLab"
  }
}'

예시 응답: 

{
  "uuid": "4773b2ee-5ba5-5e9f-b48c-5f7a17f0faac"
}

Starboard 취약점 해결

GitLab 에이전트 서버(kas)에서 Starboard 보안 취약성을 해결하기 위해 호출됩니다. 목록 UUID를 수락하고 해당 목록에 식별되지 않는 모든 Starboard 취약성을 해결로 표시합니다.

속성 유형 필수 설명
uuids 문자열 배열 예 Starboard 취약점 생성 응답에서 수집된 감지된 취약점의 UUID. 
POST internal/kubernetes/modules/starboard_vulnerability/scan_result

예시 요청: 

curl --request POST --header "Gitlab-Kas-Api-Request: <JWT 토큰>" \
     --header "Authorization: Bearer <에이전트 토큰>" --header "Content-Type: application/json" \
     --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/scan_result" \
     --data '{ "uuids": ["102e8a0a-fe29-59bd-b46c-57c3e9bc6411", "5eb12985-0ed5-51f4-b545-fd8871dc2870"] }'

스캔 실행 정책

GitLab 에이전트 서버(kas)에서 에이전트 토큰에 속한 프로젝트를 위해 구성된 scan_execution_policies를 검색하기 위해 호출됩니다. GitLab kas는 이것을 사용하여 에이전트를 구성하여 정책에 따라 Kubernetes 클러스터의 이미지를 스캔합니다. 

GET /internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies

예시 요청: 

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT 토큰>" \
     --header "Authorization: Bearer <에이전트 토큰>" "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies"

예시 응답: 

{
  "policies": [
    {
      "name": "정책",
      "description": "정책 설명",
      "enabled": true,
      "yaml": "---\nname: 정책\ndescription: '정책 설명'\nenabled: true\nactions:\n- scan: container_scanning\nrules:\n- type: pipeline\n  branches:\n  - main\n",
      "updated_at": "2022-06-02T05:36:26+00:00"
    }
  ]
}

정책 구성

GitLab 에이전트 서버(kas)에서 프로젝트에 대한 설정된 policies_configuration을 검색하는 데 사용됩니다. GitLab kas는 이를 사용하여 구성에 기반하여 Kubernetes 클러스터에서 이미지를 스캔하는 에이전트를 구성합니다. 

GET /internal/kubernetes/modules/starboard_vulnerability/policies_configuration

예시 요청: 

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <에이전트 토큰>" "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/policies_configuration"

예시 응답: 

{
  "configurations": [
    {
      "cadence": "30 2 * * *",
      "namespaces": [
        "namespace-a",
        "namespace-b"
      ],
      "updated_at": "2022-06-02T05:36:26+00:00"
    }
  ]
}

스토리지 한도 제외

네임스페이스 스토리지 한도 제외 엔드포인트는 GitLab.com의 최상위 네임스페이스에서 스토리지 한도 제외를 관리합니다. 이러한 엔드포인트는 GitLab.com의 관리자 영역에서만 사용할 수 있습니다.

스토리지 한도 제외 검색

모든 Namespaces::Storage::LimitExclusion 레코드를 검색하려면 GET 요청을 사용하세요. 

GET /namespaces/storage/limit_exclusions

예시 요청: 

curl --request GET \
  --url "https://gitlab.com/v4/namespaces/storage/limit_exclusions" \
  --header 'PRIVATE-TOKEN: <관리자 액세스 토큰>'

예시 응답: 

[
    {
      "id": 1,
      "namespace_id": 1234,
      "namespace_name": "네임스페이스 이름",
      "reason": "네임스페이스를 제외하는 이유"
    },
    {
      "id": 2,
      "namespace_id": 4321,
      "namespace_name": "다른 네임스페이스 이름",
      "reason": "네임스페이스를 제외하는 다른 이유"
    },
]

스토리지 한도 제외 생성

Namespaces::Storage::LimitExclusion를 생성하려면 POST 요청을 사용하세요. 

POST /namespaces/:id/storage/limit_exclusion
속성 유형 필수여부 설명
reason 문자열 예 네임스페이스를 제외하는 이유.

예시 요청: 

curl --request POST \
  --url "https://gitlab.com/v4/namespaces/123/storage/limit_exclusion" \
  --header 'Content-Type: application/json' \
  --header 'PRIVATE-TOKEN: <관리자 액세스 토큰>' \
  --data '{
    "reason": "네임스페이스를 제외하는 이유"
  }'

예시 응답: 

{
  "id": 1,
  "namespace_id": 1234,
  "namespace_name": "네임스페이스 이름",
  "reason": "네임스페이스를 제외하는 이유"
}

스토리지 한도 제외 삭제

네임스페이스의 Namespaces::Storage::LimitExclusion를 삭제하려면 DELETE 요청을 사용하세요. 

DELETE /namespaces/:id/storage/limit_exclusion

예시 요청: 

curl --request DELETE \
  --url "https://gitlab.com/v4/namespaces/123/storage/limit_exclusion" \
  --header 'PRIVATE-TOKEN: <관리자 액세스 토큰>'

예시 응답: 

204

알려진 사용자

  • GitLab.com의 관리자 영역

그룹 SCIM API

Tier: Premium, Ultimate Offering: GitLab.com

그룹 SCIM API는 부분적으로 RFC7644 프로토콜을 구현합니다. 이 API는 /groups/:group_path/Users 및 /groups/:group_path/Users/:id 엔드포인트를 제공합니다. 기본 URL은 <http|https>://<GitLab 호스트>/api/scim/v2입니다. 이 API는 SCIM 프로바이더 통합을 위한 시스템 사용을 위해 제공되며 사전 예고 없이 변경될 수 있습니다.

이 API를 사용하려면 그룹에 대한 그룹 SSO를 활성화하세요. 이 API는 SCIM for Group SSO가 활성화된 경우에만 사용됩니다. 이는 SCIM 아이디를 생성하기 전에 필수적인 단계입니다.

이 그룹 SCIM API:

  • SCIM 프로바이더 통합을 위해 시스템 사용을 위한 것입니다.
  • RFC7644 프로토콜을 구현합니다.
  • 그룹에 대해 SCIM 프로비저닝된 사용자 목록을 가져옵니다.
  • 그룹에 대해 SCIM 프로비저닝된 사용자를 생성, 삭제 및 업데이트합니다.

인스턴스 SCIM API는 인스턴스에 대해 동일한 작업을 수행합니다.

이 그룹 SCIM API는 SCIM API와 다릅니다. SCIM API:

  • 내부 API가 아닙니다.
  • RFC7644 프로토콜을 구현하지 않습니다.
  • 그룹에서 SCIM 식별자를 가져오고 확인하며 업데이트 및 삭제하지만 합니다.

참고: 이 API는 Gitlab-Shell-Api-Request 헤더가 필요하지 않습니다.

SCIM 프로비저닝된 사용자 목록 가져오기

이 엔드포인트는 SCIM 동기화 메커니즘의 일부로 사용됩니다. 사용된 필터에 따라 사용자 목록을 반환합니다. 

GET /api/scim/v2/groups/:group_path/Users

매개변수:

속성 유형 필수여부 설명
filter 문자열 아니오 필터 표현식
group_path 문자열 예 그룹의 전체 경로
startIndex 정수 아니오 결과를 반환할 시작 인덱스(1부터 시작)를 나타냅니다. 1 미만의 값은 1로 해석됩니다.
count 정수 아니오 원하는 최대 쿼리 결과 수입니다.

참고: 페이지네이션은 다른 곳에서 사용되는 GitLab 페이지네이션과 달리 SCIM 사양을 따릅니다. 요청 사이에 기록이 변경되면 다른 페이지로 이동한 기록이 누락되거나 이전 요청에서 기록을 반복할 수 있습니다.

특정 식별자를 필터링한 예시 요청: 

curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \
     --header "Authorization: Bearer <your_scim_token>" \
     --header "Content-Type: application/scim+json"

예시 응답: 

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "itemsPerPage": 20,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
      "active": true,
      "name.formatted": "테스트 사용자",
      "userName": "username",
      "meta": { "resourceType":"User" },
      "emails": [
        {
          "type": "work",
          "value": "name@example.com",
          "primary": true
        }
      ]
    }
  ]
}

단일 SCIM 프로비저닝된 사용자 가져오기 

GET /api/scim/v2/groups/:group_path/Users/:id

매개변수:

속성 유형 필수 설명
id 문자열 예 사용자의 외부 UID
group_path 문자열 예 그룹의 전체 경로.

예시 요청: 

curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

예시 응답: 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

SCIM 프로비저닝된 사용자 작성 

POST /api/scim/v2/groups/:group_path/Users/

매개변수:

속성 유형 필수 설명
externalId 문자열 예 사용자의 외부 UID
userName 문자열 예 사용자의 유저네임
emails JSON 문자열 예 근무 이메일
name JSON 문자열 예 사용자 이름
meta 문자열 아니요 리소스 유형 (User).

예시 요청: 

curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/groups/test_group/Users" \
     --data '{"externalId":"test_uid","active":null,"username":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

예시 응답: 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

성공하면 201 상태 코드를 반환합니다.

참고: 그룹 SCIM 식별자를 사용자에 대해 만든 후, 해당 SCIM 식별자를 관리자 영역에서 볼 수 있습니다.

단일 SCIM 프로비저닝된 사용자 업데이트

업데이트할 수 있는 필드는 다음과 같습니다:

SCIM/IdP 필드 GitLab 필드
id/externalId extern_uid
name.formatted name (삭제됨)
emails\[type eq "work"\].value email (삭제됨)
active active가 false이면 식별 제거
userName username (삭제됨) 
PATCH /api/scim/v2/groups/:group_path/Users/:id

매개변수:

속성 유형 필수 설명
id 문자열 예 사용자의 외부 UID
group_path 문자열 예 그룹의 전체 경로
Operations JSON 문자열 예 operations 표현식.

사용자의 id를 업데이트하는 예시 요청: 

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --data '{ "Operations": [{"op":"replace","path":"id","value":"1234abcd"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공하면 204 상태 코드를 가진 빈 응답을 반환합니다.

사용자의 active 상태를 설정하는 예시 요청: 

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --data '{ "Operations": [{"op":"replace","path":"active","value":"true"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공하면 204 상태 코드를 가진 빈 응답을 반환합니다.

단일 SCIM 프로비저닝된 사용자 제거

사용자의 SSO 식별과 그룹 멤버십을 제거합니다. 

DELETE /api/scim/v2/groups/:group_path/Users/:id

매개변수:

속성 유형 필수 설명
id 문자열 예 사용자의 외부 UID
group_path 문자열 예 그룹의 전체 경로

예시 요청: 

curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공하면 204 상태 코드를 가진 빈 응답을 반환합니다.

인스턴스 SCIM API

Tier: Premium, Ultimate Offering: Self-managed
  • 이슈에서 GitLab 15.8에 도입되었습니다.

인스턴스 SCIM API는 RFC7644 프로토콜을 부분적으로 구현합니다. 이 API는 /application/Users 및 /application/Users/:id 엔드포인트를 제공합니다. 기본 URL은 <http|https>://<GitLab 호스트>/api/scim/v2입니다. SCIM 프로바이더 통합을 위한 시스템 사용을 위한 API이기 때문에 사전 통보 없이 변경될 수 있습니다.

이 API를 사용하려면 인스턴스에 대해 SAML SSO를 활성화하세요.

이 인스턴스 SCIM API:

  • SCIM 프로바이저 통합을 위한 시스템 사용을 위한 것입니다.
  • RFC7644 프로토콜을 구현합니다.
  • 그룹의 SCIM 프로비저닝 사용자 목록을 가져옵니다.
  • 그룹의 SCIM 프로비저닝 사용자를 생성, 삭제, 및 업데이트합니다.

group SCIM API는 그룹에 대해 동일한 작업을 수행합니다.

이 인스턴스 SCIM API는 SCIM API와 다릅니다. SCIM API:

  • 내부 API가 아닙니다.
  • RFC7644 프로토콜을 구현하지 않습니다.
  • 그룹 내의 SCIM 신원을 가져오거나 확인하고 업데이트 및 삭제하지 않습니다.
note
이 API는 Gitlab-Shell-Api-Request 헤더가 필요하지 않습니다.

SCIM 프로비저닝된 사용자 목록 가져오기

이 엔드포인트는 SCIM 동기화 메커니즘의 일부로 사용됩니다. 사용된 필터에 따라 사용자 목록을 반환합니다. 

GET /api/scim/v2/application/Users

매개변수:

속성 타입 필수 여부 설명
filter string 아니요 filter 식입니다.
startIndex integer 아니요 반환 결과를 시작할 1부터 시작하는 인덱스입니다. 1보다 작은 값은 1로 해석됩니다.
count integer 아니요 원하는 쿼리 결과의 최대 개수입니다.
note
페이지네이션은 다른 곳에서 사용된 GitLab 페이지네이션과 달리 SCIM 사양을 따릅니다. 요청 사이에 레코드가 변경되면 다른 페이지로 이동한 레코드가 누락되거나 이전 요청에서 반복된 레코드가 발생할 수 있습니다.

예시 요청: 

curl "https://gitlab.example.com/api/scim/v2/application/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \
     --header "Authorization: Bearer <your_scim_token>" \
     --header "Content-Type: application/scim+json"

예시 응답: 

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "itemsPerPage": 20,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
      "active": true,
      "name.formatted": "Test User",
      "userName": "username",
      "meta": {"resourceType":"User"},
      "emails": [
        {
          "type": "work",
          "value": "name@example.com",
          "primary": true
        }
      ]
    }
  ]
}

단일 SCIM 프로비저닝 사용자 가져오기 

GET /api/scim/v2/application/Users/:id

매개변수:

속성 타입 필수 여부 설명
id string 예 사용자의 외부 UID.

예시 요청: 

curl "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

예시 응답: 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

SCIM 프로비저닝 사용자 생성하기 

POST /api/scim/v2/application/Users

매개변수:

속성 타입 필수 여부 설명
externalId string 예 사용자의 외부 UID.
userName string 예 사용자의 사용자 이름.
emails JSON string 예 사무실 이메일.
name JSON string 예 사용자의 이름.
meta string 아니요 리소스 유형 (User).

예시 요청: 

curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/application/Users" \
     --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

예시 응답: 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

성공하면 201 상태 코드를 반환합니다.

단일 SCIM 프로비저닝된 사용자 업데이트

업데이트할 수 있는 필드는 다음과 같습니다.

SCIM/IdP 필드 GitLab 필드
id/externalId extern_uid
active false인 경우 사용자가 차단되지만 SCIM 식별은 유지됩니다. 
PATCH /api/scim/v2/application/Users/:id

매개변수:

속성 유형 필수 설명
id 문자열 예 사용자의 외부 UID.
Operations JSON 문자열 예 operations 표현식.

예시 요청: 

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --data '{ "Operations": [{"op":"Update","path":"active","value":"false"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공 시 204 상태 코드와 빈 응답을 반환합니다.

단일 SCIM 프로비저닝된 사용자 차단

사용자가 차단 상태로 변경되며 로그아웃됩니다. 이것은 사용자가 로그인하거나 코드를 push 또는 pull할 수 없음을 의미합니다. 

DELETE /api/scim/v2/application/Users/:id

매개변수:

속성 유형 필수 설명
id 문자열 예 사용자의 외부 UID.

예시 요청: 

curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공 시 204 상태 코드와 빈 응답을 반환합니다.

사용 가능한 필터

the RFC7644 filtering section에 명시된대로 표현식과 일치합니다.

필터 설명
eq 속성이 지정된 값과 정확히 일치합니다.

예시: 

id eq a-b-c-d

사용 가능한 연산

the RFC7644 update section에 명시된대로 작업을 수행합니다.

연산자 설명
Replace 속성값을 업데이트합니다.
Add 속성에 새 값이 있습니다.

예시: 

{ "op": "Add", "path": "name.formatted", "value": "New Name" }