내부 API

내부 API는 다양한 GitLab 컴포넌트에서 사용되며, 다른 소비자들은 사용할 수 없습니다. 이 문서는 GitLab 코드베이스에서 작업하는 사람들을 대상으로 합니다.

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

새 엔드포인트 추가

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

가끔 우리가 내부 API 엔드포인트를 선호하는 이유는 해당 엔드포인트를 사용하는 것이 외부 사용자가 가질 수 없는 내부 데이터를 필요로 할 때입니다. 예를 들어, 내부 Pages API에서는 내부로 요청을 식별하는 비밀 토큰을 사용하거나, 넓은 커뮤니티에 공개되지 않은 공개 키로 요청에 서명할 수 있습니다.

내부 API로 나누는 또 다른 이유는 해당 API 엔드포인트로의 요청이 에지(공개) 로드 밸런서를 통해 절대로 전달되지 않아야 할 때입니다. 이렇게 하면 해당 엔드포인트에 액세스하는 방법을 다른 규칙과 정책으로 구성할 수 있습니다. 왜냐하면 우리는 그 엔드포인트에 내부 요청만이 내부 로드 밸런서를 통해 전달된다는 것을 알고 있기 때문입니다.

인증

이러한 메서드는 모두 공유 비밀로 인증됩니다. 이 비밀은 기본적으로 config/gitlab.yml에서 구성된 경로에 있는 파일에 저장됩니다. 이는 기본적으로 Rails 앱의 루트에 있는 .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 아니요 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 문자열 예 공개 키 인증에 사용되는 승인된 키 
GET /internal/authorized_keys

예시 요청: 

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT 토큰>" "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

승인된 Certs

이 엔드포인트는 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 토큰>" "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 토큰>" "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 토큰>" "http://localhost:3001/api/v4/internal/check"

예시 응답: 

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

알려진 소비자

  • GitLab Shell

오류 추적 요청 인증

이 엔드포인트는 오류 추적 Go REST API 애플리케이션에 의해 호출되어 프로젝트를 인증합니다. > 소개됨 in GitLab 15.1.

속성 유형 필수 설명
project_id integer yes 연결된 키가 있는 프로젝트의 ID입니다.
public_key string yes 통합된 오류 추적 기능에 의해 생성된 공개 키입니다. 
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

Pre-receive에서 카운터 증가

이 요청은 푸시가 수락될 수 있는 참조 카운터를 증가시키기 위해 Gitaly 후크에서 호출됩니다.

속성 유형 필수 설명
gl_repository string yes 푸시를 받는 리포지터리의 리포지터리 식별자 
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-워커를 Sidekiq에서 트리거하고, 넘겨진 푸시 옵션을 처리하며 사용자에게 표시해야 하는 메시지를 포함한 응답을 작성합니다.

속성 유형 필수 설명
identifier string yes 푸시를 수행하는 사용자를 식별하는 user-[id] 또는 key-[id]입니다.
gl_repository string yes 푸시되는 리포지터리의 식별자
push_options string array no 푸시 옵션의 배열
changes string no 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 에이전트 엔드포인트

다음 엔드포인트는 다양한 목적으로 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 integer/string yes 프로젝트의 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 해시 no 카운터 해시
counters["k8s_api_proxy_request"] 정수 no k8s_api_proxy_request 카운터를 증가시킬 숫자
counters["gitops_sync"] 정수 no gitops_sync 카운터를 증가시킬 숫자
counters["flux_git_push_notifications_total"] 정수 no flux_git_push_notifications_total 카운터를 증가시킬 숫자
counters["k8s_api_proxy_requests_via_ci_access"] 정수 no k8s_api_proxy_requests_via_ci_access 카운터를 증가시킬 숫자
counters["k8s_api_proxy_requests_via_user_access"] 정수 no k8s_api_proxy_requests_via_user_access 카운터를 증가시킬 숫자
counters["k8s_api_proxy_requests_via_pat_access"] 정수 no k8s_api_proxy_requests_via_pat_access 카운터를 증가시킬 숫자
unique_counters 해시 no 고유 숫자 배열
unique_counters["k8s_api_proxy_requests_unique_users_via_ci_access"] 정수 배열 no ci_access를 통해 CI 터널과 상호 작용한 고유 사용자 ID 세트로 k8s_api_proxy_requests_unique_users_via_ci_access 메트릭 이벤트를 추적합니다
unique_counters["k8s_api_proxy_requests_unique_agents_via_ci_access"] 정수 배열 no ci_access를 통해 CI 터널과 상호 작용한 고유 에이전트 ID 세트로 k8s_api_proxy_requests_unique_agents_via_ci_access 메트릭 이벤트를 추적합니다
unique_counters["k8s_api_proxy_requests_unique_users_via_user_access"] 정수 배열 no user_access를 통해 CI 터널과 상호 작용한 고유 사용자 ID 세트로 k8s_api_proxy_requests_unique_users_via_user_access 메트릭 이벤트를 추적합니다
unique_counters["k8s_api_proxy_requests_unique_agents_via_user_access"] 정수 배열 no user_access를 통해 CI 터널과 상호 작용한 고유 에이전트 ID 세트로 k8s_api_proxy_requests_unique_agents_via_user_access 메트릭 이벤트를 추적합니다
unique_counters["k8s_api_proxy_requests_unique_users_via_pat_access"] 정수 배열 no 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"] 정수 배열 no PAT를 통해 KAS Kubernetes API 프록시를 사용한 고유 에이전트 ID 세트로 k8s_api_proxy_requests_unique_agents_via_pat_access 메트릭 이벤트를 추적합니다 
POST /internal/kubernetes/usage_metrics

예시 요청: 

curl --request POST --header "Gitlab-Kas-Api-Request: <JWT 토큰>" --header "Content-Type: application/json" \
     --data '{"counters": {"gitops_sync":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 (via Starboard Operator)",
    "vendor": "GitLab"
  }
}'

예시 응답: 

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

Starboard 취약점 해결

GitLab 에이전트 서버(kas)에서 Starboard 보안 취약점을 해결하기 위해 호출됩니다. 지정된 디렉터리이 없는 모든 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 토큰>" \
     --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"
    }
  ]
}

구독

구독 엔드포인트는 CustomersDot (customers.gitlab.com)에서 사용되며, GitLab.com 내의 개인 네임스페이스 또는 최상위 그룹에 대한 시험 및 추가 구매를 포함하는 구독을 적용합니다.

구독 생성

구독을 생성하려면 POST 명령을 사용하십시오. 

POST /namespaces/:id/gitlab_subscription
속성 유형 필요여부 설명
start_date 날짜 예 구독 시작 날짜
end_date 날짜 아니오 구독 종료 날짜
plan_code 문자열 아니오 구독 티어 코드
seats 정수 아니오 구독 내 좌석 수
max_seats_used 정수 아니오 지난 달의 활성 사용자 중 최대 사용자 수
auto_renew 부울 아니오 구독이 종료 날짜에 자동으로 갱신되는지 여부
trial 부울 아니오 구독이 시험인지 여부
trial_starts_on 날짜 아니오 시험 시작 날짜
trial_ends_on 날짜 아니오 시험이 끝나는 날짜

예시 요청: 

curl --request POST --header "TOKEN: <관리자 액세스 토큰>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?start_date="2020-07-15"&plan="premium"&seats=10"

예시 응답: 

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false,
  },
  "usage": {
    "seats_in_subscription":10,
    "seats_in_use":1,
    "max_seats_used":0,
    "seats_owed":0
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":null,
    "trial_ends_on":null
  }
}

구독 업데이트

기존 구독을 업데이트하려면 PUT 명령을 사용하십시오. 

PUT /namespaces/:id/gitlab_subscription
속성 유형 필요여부 설명
start_date 날짜 아니오 구독 시작 날짜
end_date 날짜 아니오 구독 종료 날짜
plan_code 문자열 아니오 구독 티어 코드
seats 정수 아니오 구독 내 좌석 수
max_seats_used 정수 아니오 지난 달의 활성 사용자 중 최대 사용자 수
auto_renew 부울 아니오 구독이 종료 날짜에 자동으로 갱신되는지 여부
trial 부울 아니오 구독이 시험인지 여부
trial_starts_on 날짜 아니오 시험 시작 날짜. 시험이 true이면 필수입니다.
trial_ends_on 날짜 아니오 시험이 끝나는 날짜

예시 요청: 

curl --request PUT --header "TOKEN: <관리자 액세스 토큰>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?max_seats_used=0"

예시 응답: 

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false,
  },
  "usage": {
    "seats_in_subscription":80,
    "seats_in_use":82,
    "max_seats_used":0,
    "seats_owed":2
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":"2021-07-15",
    "trial_ends_on":null
  }
}

구독 검색

기존 구독을 보려면 GET 명령을 사용하십시오. 

GET /namespaces/:id/gitlab_subscription

예시 요청: 

curl --header "TOKEN: <관리자 액세스 토큰>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription"

예시 응답: 

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false,
    "exclude_guests":false,
  },
  "usage": {
    "seats_in_subscription":80,
    "seats_in_use":82,
    "max_seats_used":82,
    "seats_owed":2
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":"2021-07-15",
    "trial_ends_on":null
  }
}

알려진 소비자

  • CustomersDot

구독 부가 구매 (저장 및 컴퓨팅 팩 제외)

구독 부가 구매 엔드포인트는 CustomersDot (customers.gitlab.com)에서 사용되며, 개인 네임스페이스 또는 GitLab.com 내의 최상위 그룹에 대한 Code Suggestions와 같은 구독 부가 구매를 적용합니다. 이는 저장 및 컴퓨팅 팩 구매에는 적용되지 않습니다.

구독 애드온 구매 생성

구독 애드온 구매를 생성하려면 POST 명령을 사용합니다. 

POST /namespaces/:id/subscription_add_on_purchase/:add_on_name
속성 유형 필수 설명
quantity integer yes 구독 애드온 구매 단위 수 (예: Code Suggestions 애드온의 좌석 수)
expires_on date yes 구독 애드온 구매 만료일
purchase_xid string yes 구독 애드온 구매 식별자 (예: Code Suggestions 애드온의 구독 이름)

예시 요청: 

curl --request POST --header "PRIVATE-TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions?&quantity=10&expires_on="2024-07-15"&purchase_xid="A-S12345678""

예시 응답: 

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":10,
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678"
}

구독 애드온 구매 업데이트

기존 구독 애드온 구매를 업데이트하려면 PUT 명령을 사용합니다. 

PUT /namespaces/:id/subscription_add_on_purchase/:add_on_name
속성 유형 필수 설명
quantity integer no 구독 애드온 구매 단위 수 (예: Code Suggestions 애드온의 좌석 수)
expires_on date yes 구독 애드온 구매 만료일
purchase_xid string no 구독 애드온 구매 식별자 (예: Code Suggestions 애드온의 구독 이름)

예시 요청: 

curl --request PUT --header "PRIVATE-TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions?&quantity=15&expires_on="2024-07-15"&purchase_xid="A-S12345678""

예시 응답: 

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":15,
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678"
}

구독 애드온 구매 조회

기존 구독 애드온 구매를 보려면 GET 명령을 사용합니다. 

GET /namespaces/:id/subscription_add_on_purchase/:add_on_name

예시 요청: 

curl --header "PRIVATE-TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions"

예시 응답: 

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":15,
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678"
}

알려진 사용자

  • CustomersDot

리포지터리 한도 제외

네임스페이스 리포지터리 한도 제외 엔드포인트는 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: <admin access token>'

예시 응답: 

[
    {
      "id": 1,
      "namespace_id": 1234,
      "namespace_name": "A Namespace Name",
      "reason": "네임스페이스 제외 사유"
    },
    {
      "id": 2,
      "namespace_id": 4321,
      "namespace_name": "다른 네임스페이스 이름",
      "reason": "다른 네임스페이스 제외 사유"
    },
]

리포지터리 한도 제외 생성

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

POST /namespaces/:id/storage/limit_exclusion
속성 유형 필수 설명
reason string yes 네임스페이스 제외 사유

예시 요청: 

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": "네임스페이스 제외 사유"
  }'

예시 응답: 

{
  "id": 1,
  "namespace_id": 1234,
  "namespace_name": "A 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: <admin access token>'

예시 응답: 

204

알려진 사용자

  • GitLab.com 관리 영역

컴퓨팅 쿼터 프로비저닝

  • 이름 변경 from “CI/CD minutes” to “compute quota” and “compute minutes” in GitLab 16.1.

컴퓨팅 쿼터 엔드포인트는 CustomersDot (customers.gitlab.com) 가 GitLab.com의 개인 네임스페이스 또는 최상위 그룹에 추가적인 컴퓨팅 분의 팩을 적용하는 데 사용됩니다.

추가 팩 생성

추가 팩을 만들려면 POST 명령을 사용하세요. 

POST /namespaces/:id/minutes
속성 유형 필수 설명
packs 배열 예 구매한 컴퓨팅 팩의 배열
packs[expires_at] 날짜 예 구매한 팩의 만료 날짜
packs[number_of_minutes] 정수 예 추가 컴퓨팅 분의 수
packs[purchase_xid] 문자열 예 구매의 고유 ID

예시 요청: 

curl --request POST \
  --url "http://localhost:3000/api/v4/namespaces/123/minutes" \
  --header 'Content-Type: application/json' \
  --header 'PRIVATE-TOKEN: <admin access token>' \
  --data '{
    "packs": [
      {
        "number_of_minutes": 10000,
        "expires_at": "2022-01-01",
        "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
      }
    ]
  }'

예시 응답: 

[
  {
    "namespace_id": 123,
    "expires_at": "2022-01-01",
    "number_of_minutes": 10000,
    "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
  }
]

추가 팩 이동

한 네임스페이스에서 다른 네임스페이스로 추가 팩을 옮기려면 PATCH 명령을 사용하세요. 

PATCH /namespaces/:id/minutes/move/:target_id
속성 유형 필수 설명
id 문자열 예 팩을 전송할 네임스페이스의 ID
target_id 문자열 예 팩을 전송할 대상 네임스페이스의 ID

예시 요청: 

curl --request PATCH \
  --url "http://localhost:3000/api/v4/namespaces/123/minutes/move/321" \
  --header 'PRIVATE-TOKEN: <admin access token>'

예시 응답: 

{
  "message": "202 Accepted"
}

알려진 사용자

  • CustomersDot

예정 중인 조정

upcoming_reconciliations 엔드포인트는 CustomersDot (customers.gitlab.com)에서 네임스페이스의 예정 중인 조정을 업데이트하는 데 사용됩니다.

upcoming_reconciliations 업데이트

upcoming_reconciliations를 업데이트하려면 PUT 명령을 사용하세요. 

PUT /internal/upcoming_reconciliations
속성 유형 필수 설명
upcoming_reconciliations 배열 예 예정 중인 조정의 배열

각 배열 요소는 다음을 포함합니다:

속성 유형 필수 설명
namespace_id 정수 예 조정할 네임스페이스의 ID
next_reconciliation_date 날짜 예 다음 조정의 날짜
display_alert_from 날짜 예 다가오는 조정의 경고 표시 시작 날짜

예시 요청: 

curl --request PUT --header "PRIVATE-TOKEN: <admin_access_token>" --header "Content-Type: application/json" \
     --data '{"upcoming_reconciliations": [{"namespace_id": 127, "next_reconciliation_date": "13 Jun 2021", "display_alert_from": "06 Jun 2021"}, {"namespace_id": 129, "next_reconciliation_date": "12 Jun 2021", "display_alert_from": "05 Jun 2021"}]}' \
     "https://gitlab.com/api/v4/internal/upcoming_reconciliations"

예시 응답: 

200

upcoming_reconciliation 삭제

upcoming_reconciliation을 삭제하려면 DELETE 명령을 사용하세요. 

DELETE /internal/upcoming_reconciliations
속성 유형 필수 설명
namespace_id 정수 예 더 이상 예정 중인 조정이 없는 GitLab.com 네임스페이스의 ID

예시 요청: 

curl --request DELETE \
  --url "http://localhost:3000/api/v4/internal/upcoming_reconciliations?namespace_id=22" \
  --header 'PRIVATE-TOKEN: <admin_access_token>'

예시 응답: 

204

알려진 사용자

  • CustomersDot

그룹 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 ID 생성의 선행 조건입니다.

이 그룹 SCIM API는:

  • SCIM 제공자 통합을위한 시스템 사용을 위한 것입니다.
  • RFC7644 프로토콜을 구현합니다.
  • 그룹의 SCIM 제공 사용자 디렉터리을 가져옵니다.
  • 그룹의 SCIM 제공 사용자를 만들고, 삭제하고, 업데이트합니다.

인스턴스 SCIM API도 동일한 작업을 인스턴스에서 수행합니다.

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

  • 내부 API가 아닙니다.
  • RFC7644 프로토콜을 구현하지 않습니다.
  • 그룹 내에서 SCIM ID를 가져오고, 검사하고, 업데이트하고, 삭제하지 않습니다.
note
이 API는 Gitlab-Shell-Api-Request 헤더가 필요하지 않습니다.

SCIM 프로비저닝된 사용자 디렉터리 가져오기

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

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

매개변수:

속성 유형 필수 설명
filter string 아니오 filter 표현식입니다.
group_path string 예 그룹의 전체 경로입니다.
startIndex 정수 아니오 결과를 반환할 시작 위치를 나타내는 1을 기준으로 하는 인덱스입니다. 1보다 작은 값은 1로 해석됩니다.
count 정수 아니오 원하는 최대 쿼리 결과 수입니다.
note
페이지네이션은 다른 곳에서 사용되는 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": "Test User",
      "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 string 예 사용자의 외부 UID입니다.
group_path string 예 그룹의 전체 경로입니다.

예제 요청: 

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 string 예 사용자의 외부 UID입니다.
userName string 예 사용자의 사용자 이름입니다.
emails JSON 문자열 예 업무 이메일입니다.
name JSON 문자열 예 사용자의 이름입니다.
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 상태 코드를 반환합니다.

note
사용자를 위한 그룹 SCIM 식별을 만든 후, 관리자 영역에서 해당 SCIM 식별을 볼 수 있습니다.

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

업데이트할 수 있는 필드:

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

매개변수:

속성 유형 필수 설명
id string 예 사용자의 외부 UID입니다.
group_path string 예 그룹의 전체 경로입니다.
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 string yes 사용자의 외부 UID입니다.
group_path string yes 그룹의 전체 경로입니다.

예시 요청: 

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 프로비저닝된 사용자 디렉터리을 가져옵니다.
  • 그룹에 대해 SCIM 프로비저닝된 사용자를 생성, 삭제 및 업데이트합니다.

그룹 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 no 사용 가능한 필터 표현식입니다.
startIndex integer no 결과를 반환할 시작 위치를 나타내는 1부터 시작하는 인덱스입니다. 1보다 작은 값은 1로 해석됩니다.
count integer no 원하는 쿼리 결과의 최대 개수입니다.
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 yes 사용자의 외부 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 yes 사용자의 외부 UID입니다.
userName string yes 사용자의 사용자 이름입니다.
emails JSON string yes 업무 이메일입니다.
name JSON string yes 사용자의 이름입니다.
meta string no 리소스 유형 (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 string yes 사용자의 외부 UID입니다.
Operations JSON string yes 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으로 단일 사용자 차단하기

사용자는 ‘차단’ 상태로 설정되어 로그아웃됩니다. 이는 사용자가 로그인하거나 코드를 푸시하거나 끌 수 없음을 의미합니다. 

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

매개변수:

속성 유형 필수 설명
id string yes 사용자의 외부 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 상태 코드와 빈 응답이 반환됩니다.

사용 가능한 필터

RFC7644 필터링 섹션에서 지정된 표현과 일치합니다.

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

예시: 

id eq a-b-c-d

사용 가능한 연산

RFC7644 업데이트 섹션에 지정된 연산을 수행합니다.

연산자 설명
Replace 해당 속성의 값이 업데이트됩니다.
Add 해당 속성에 새 값을 추가합니다.

예시: 

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