내부 API

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

이 문서에는 아직 GitLab Pages에서 사용하는 내부 API가 포함되지 않았습니다.

GitLab 구독에 대한 내부 API 정보는 전용 페이지를 참조하세요.

새 엔드포인트 추가

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

내부 API 엔드포인트를 선호하는 한 가지 이유는 그러한 엔드포인트를 사용하는 데 내부 데이터가 필요하여 외부 행위자가 접근할 수 없을 때입니다. 예를 들어, 내부 Pages API에서는 요청이 내부임을 식별하는 비밀 토큰을 사용하거나 더 넓은 커뮤니티에서 사용할 수 없는 공개 키로 요청에 서명할 수 있습니다.

내부 API로 분리하는 또 다른 이유는 해당 API 엔드포인트에 대한 요청이 절대적으로 엣지(공개) 로드 밸런서를 통과해서는 안 될 때입니다. 이렇게 하면 엔드포인트에 접근하는 방법에 대한 서로 다른 속도 제한 규칙 및 정책을 구성할 수 있습니다. 왜냐하면 우리는 내부 요청만 해당 엔드포인트로 전송될 수 있다는 것을 알고 있기 때문입니다.

인증

이 방법들은 모두 공유 비밀을 사용하여 인증됩니다. 이 비밀은 기본적으로 config/gitlab.yml에서 구성된 경로에 파일로 저장됩니다. 기본적으로 이는 .gitlab_shell_secret이라는 이름의 Rails 앱 루트에 있습니다.

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

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

Git 인증

Gitaly와 GitLab Shell에 의해 리포지토리에 대한 접근을 확인하기 위해 호출됩니다.

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

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

이 엔드포인트에 대한 자세한 내용은 그 자체의 페이지를 참조하세요. 이 페이지에서 다루는 범위로 인해 더욱 자세히 설명됩니다.

POST /internal/allowed
속성 타입 필수 여부 설명
key_id string 아니오 GitLab Shell에 연결하기 위해 사용된 SSH 키의 ID
username string 아니오 GitLab Shell에 연결하기 위해 사용된 인증서의 사용자 이름
project string 아니오 (만약 gl_repository가 전달되면) 프로젝트의 경로
gl_repository string 아니오 (만약 project가 전달되면) 리포지토리 식별자, 예: project-7
protocol string 예 GitLab Shell에서 호출할 때 SSH, Gitaly에서 호출할 때 HTTP 또는 SSH
action string 예 실행 중인 Git 명령어 (git-upload-pack, git-receive-pack, git-upload-archive)
changes string 예 Gitaly에서 호출할 때 <oldrev> <newrev> <refname>, GitLab Shell에서 호출할 때 마법 문자열 _any
check_ip string 아니오 GitLab Shell에 대한 호출이 이루어진 IP 주소

예제 요청:

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --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 인증

이 엔드포인트는 GitLab Shell에서 호출되어 SSH를 통해 리포지토리에 접근할 때 LFS 클라이언트를 위한 정보를 제공합니다.

속성 유형 필수 설명
key_id string 아니오 GitLab Shell에 연결하는 데 사용되는 SSH 키의 ID
username string 아니오 GitLab Shell에 연결하는 데 사용되는 인증서의 사용자 이름
project string 아니오 프로젝트의 경로

예제 요청:

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --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 string 예 공개 키 인증에 사용되는 승인된 키입니다. 
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 string 예 SSH 인증서의 지문입니다.
user_identifier string 예 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 파일에서 발견되거나 /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 키를 사용하여 새로운 2FA 복구 코드 가져오기

이것은 GitLab Shell에서 호출되며 사용자가 SSH 키를 기반으로 새로운 2FA 복구 코드를 받을 수 있게 합니다.

속성 유형 필수 설명
key_id 정수 아니요 authorized-keys 파일에서 발견되거나 /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 파일에서 발견되거나 /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 token>" \
     --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 token>" \
     --data "gl_repository=project-7" "http://localhost:3001/api/v4/internal/pre_receive"

예시 응답:

{
  "reference_counter_increased": true
}

PostReceive

푸시를 수신한 후 Gitaly에서 호출됩니다. 이는 Sidekiq에서 PostReceive 워커를 트리거하고, 전달된 푸시 옵션을 처리하며, 사용자에게 표시되어야 하는 메시지를 포함한 응답을 생성합니다.

속성 유형 필수 설명
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 token>" \
     --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": "post-receive에서 안녕하세요",
      "type": "alert"
    }
  ],
  "reference_counter_decreased": true
}

GitLab 에이전트 엔드포인트

다음 엔드포인트는 다양한 목적으로 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 token>" \
     --header "Authorization: Bearer <agent token>" "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 token>" \
     --header "Authorization: Bearer <agent token>" "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"] 정수 배열 아니오 Flux 작업을 조정하기 위해 통지된 고유 프로젝트 ID 세트, flux_git_push_notified_unique_projects 메트릭 이벤트를 추적하기 위해 사용 
POST /internal/kubernetes/usage_metrics

예제 요청:

curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" --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 token>" \
  --header "Content-Type: application/json" \
  --data '{
    "events": {
      "k8s_api_proxy_requests_unique_users_via_ci_access": [
        {
          "user_id": 1,
          "project_id": 1
        }
      ]
    }
  }'

스타보드 취약점 생성

GitLab 에이전트 서버(kas)에서 스타보드 취약점 보고서로부터 보안 취약점을 생성하기 위해 호출됩니다. 이 요청은 멱등성이 있습니다. 동일한 데이터로 여러 요청 시 하나의 취약점이 생성됩니다. 응답은 생성된 취약점 발견의 UUID를 포함합니다.

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

예제 요청:

curl --request PUT --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
     --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability" \
     --data '{
  "vulnerability": {
    "name": "CVE-123-4567 in libc",
    "severity": "high",
    "confidence": "unknown",
    "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 (via Starboard Operator)",
    "vendor": "GitLab"
  }
}'

예제 응답:

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

스타보드 취약점 해결

GitLab 에이전트 서버(kas)에서 호출되어 스타보드 보안 취약점을 해결합니다.

찾은 UUID 목록을 받아들이고 목록에 의해 식별되지 않은 모든 스타보드 취약점을 해결된 것으로 표시합니다.

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

예제 요청:

curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" --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 token>" \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies"

예제 응답:

{
  "policies": [
    {
      "name": "Policy",
      "description": "정책 설명",
      "enabled": true,
      "yaml": "---\nname: Policy\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 <agent token>" "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의 Admin 영역에서만 사용할 수 있습니다.

저장 한도 제외 조회

GET 요청을 사용하여 모든 Namespaces::Storage::LimitExclusion 레코드를 조회합니다.

GET /namespaces/storage/limit_exclusions

예시 요청:

curl --request GET \
  --url "https://gitlab.com/v4/namespaces/storage/limit_exclusions" \
  --header 'PRIVATE-TOKEN: <admin access token>'

예시 응답:

[
    {
      "id": 1,
      "namespace_id": 1234,
      "namespace_name": "A Namespace Name",
      "reason": "a reason to exclude the Namespace"
    },
    {
      "id": 2,
      "namespace_id": 4321,
      "namespace_name": "Another Namespace Name",
      "reason": "another reason to exclude the Namespace"
    },
]

저장 한도 제외 생성

POST 요청을 사용하여 Namespaces::Storage::LimitExclusion을 생성합니다.

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: <admin access token>' \
  --data '{
    "reason": "a reason to exclude the Namespace"
  }'

예시 응답:

{
  "id": 1,
  "namespace_id": 1234,
  "namespace_name": "A Namespace Name",
  "reason": "a reason to exclude the Namespace"
}

저장 한도 제외 삭제

DELETE 요청을 사용하여 네임스페이스에 대한 Namespaces::Storage::LimitExclusion을 삭제합니다.

DELETE /namespaces/:id/storage/limit_exclusion

예시 요청:

curl --request DELETE \
  --url "https://gitlab.com/v4/namespaces/123/storage/limit_exclusion" \
  --header 'PRIVATE-TOKEN: <admin access token>'

예시 응답:

204

알려진 소비자

  • GitLab.com Admin 영역

그룹 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 host>/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 아이덴티티를 조회, 확인, 업데이트 및 삭제합니다.
note
이 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": "테스트 사용자",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

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

POST /api/scim/v2/groups/:group_path/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/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 아이덴티티를 생성한 후, Admin 영역에서 해당 SCIM 아이덴티티를 확인할 수 있습니다.

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

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

SCIM/IdP 필드 GitLab 필드
id/externalId extern_uid
name.formatted name (Removed)
emails\[type eq "work"\].value email (Removed)
active active가 false인 경우 아이덴티티 제거
userName username (Removed) 
PATCH /api/scim/v2/groups/:group_path/Users/:id

매개변수:

속성 유형 필수 설명
id string 예 사용자의 외부 UID.
group_path string 예 그룹의 전체 경로.
Operations JSON string 예 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 string 예 사용자의 외부 UID.
group_path string 예 그룹에 대한 전체 경로.

예제 요청:

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

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

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

이 인스턴스 SCIM API는:

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

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

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

  • 내부 API가 아닙니다.
  • RFC7644 프로토콜을 구현하지 않습니다.
  • 그룹 내 SCIM 아이덴티티를 가져오고, 확인하고, 업데이트하고, 삭제합니다.

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

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

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

GET /api/scim/v2/application/Users

매개변수:

속성 유형 필수 설명
filter string 아니요 필터 표현식.
startIndex integer 아니요 결과 반환을 시작할 1기반 인덱스. 1보다 작은 값은 1로 해석됩니다.
count integer 아니요 원하는 쿼리 결과의 최대 숫자.

참고: 페이지 매김은 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": "테스트 사용자",
      "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": "테스트 사용자",
  "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":"테스트 사용자","familyName":"사용자","givenName":"테스트"},"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": "테스트 사용자",
  "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 ID는 여전히 연결된 상태로 유지됩니다. 
PATCH /api/scim/v2/application/Users/:id

매개변수:

속성 유형 필수 여부 설명
id string 예 사용자의 외부 UID.
Operations JSON string 예 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 프로비저닝된 단일 사용자 차단

사용자는 blocked 상태로 설정되고 로그아웃됩니다. 이는
사용자가 로그인하거나 코드를 푸시 또는 풀 수 없음을 의미합니다.

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