내부 API는 여러 GitLab 구성 요소가 사용합니다. 다른 소비자는 사용할 수 없습니다. 이 문서는 GitLab 코드베이스를 작업하는 사람을 대상으로 합니다.

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

GitLab Subscriptions 내부 API는 전용 페이지를 참고합니다.

Orbit 내부 API는 전용 페이지를 참고합니다.

새 엔드포인트 추가#

API 엔드포인트는 기본적으로 적절한 인증과 인가를 갖추어 외부에서 접근할 수 있어야 합니다. 새 내부 엔드포인트를 추가하기 전에, 해당 API가 더 넓은 GitLab 커뮤니티에 도움이 되는지, 외부에서 접근할 수 있게 만들 수 있는지 검토합니다.

때로 내부 API 엔드포인트를 선호하는 이유 중 하나는 엔드포인트를 사용하는 데 외부 주체가 가질 수 없는 내부 데이터가 필요한 경우입니다. 예를 들어 내부 Pages API에서는 요청이 내부 요청임을 식별하는 시크릿 토큰을 사용하거나, 더 넓은 커뮤니티가 사용할 수 없는 공개 키로 요청에 서명할 수 있습니다.

무언가를 내부 API로 분리하는 또 다른 이유는 해당 API 엔드포인트에 대한 요청이 엣지(공개) 로드 밸런서를 절대 거치면 안 되는 경우입니다. 이렇게 하면 내부 로드 밸런서를 통해 해당 엔드포인트에는 내부 요청만 들어올 수 있음을 알 수 있으므로, 엔드포인트에 접근하는 방식에 대해 서로 다른 속도 제한 규칙과 정책을 구성할 수 있습니다.

인증#

이 메서드는 모두 공유 시크릿을 사용해 인증합니다. 이 시크릿은 config/gitlab.yml에 구성된 경로의 파일에 저장됩니다. 기본적으로 GitLab Rails 앱의 루트에 있으며 파일 이름은 .gitlab_shell_secret입니다.

해당 토큰으로 인증하려면 클라이언트는 다음을 수행합니다.

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

Git 인증#

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

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

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

이 엔드포인트는 다루는 범위가 넓어 별도 페이지에서 더 자세히 설명합니다.

POST /internal/allowed

요청 예시:

curl --request POST --header "Gitlab-Shell-Api-Request: " \
     --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이 호출하는 엔드포인트입니다.

요청 예시:

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

Authorized Keys 확인#

GitLab Shell의 authorized keys 확인이 이 엔드포인트를 호출하며, 이 확인은 빠른 SSH 키 조회를 위해 OpenSSH 또는 GitLab SSHD가 호출합니다.

GET /internal/authorized_keys

요청 예시:

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

Authorized Certs#

GitLab Shell이 SSH 인증 기관(CA) 핑거프린트와 사용자 식별자를 GitLab 사용자로 확인하기 위해 이 엔드포인트를 호출합니다. CA는 두 가지 범위에 등록할 수 있습니다.

• 그룹 수준. 라이선스가 필요한 Premium 기능(ssh_certificates)이며, 사용자가 해당 그룹의 엔터프라이즈 사용자여야 합니다.
• 인스턴스 수준. 기본적으로 비활성화된 instance_ssh_certificates 기능 플래그가 필요하며, GitLab.com에서는 사용할 수 없습니다.

엔드포인트는 그룹 범위를 먼저 확인합니다. 그룹 CA가 핑거프린트와 일치하고 사용자를 인가하면, 응답에는 그룹 결과와 그룹 namespace가 포함됩니다. 그룹 범위의 모든 실패는 인스턴스 범위로 넘어갑니다. 핑거프린트와 일치하는 그룹 CA가 없는 경우, 사용자가 그룹의 멤버가 아닌 경우, 사용자가 그룹의 엔터프라이즈 사용자가 아닌 경우, 그룹에 ssh_certificates 라이선스가 없는 경우가 모두 해당합니다. 같은 핑거프린트를 여러 그룹이 등록할 수 있으므로, 그룹이 핑거프린트를 선점했더라도 관리자가 같은 CA에 부여한 인스턴스 전체 신뢰가 차단되지는 않습니다.

두 범위가 모두 실패하면, 엔드포인트는 핑거프린트와 일치한 범위의 오류를 반환합니다. 어느 범위에서도 일치하는 CA가 없으면 응답은 404이며 Certificate Not Found입니다. 인스턴스 CA가 핑거프린트와 일치하지만 사용자 식별자로 사용자를 찾을 수 없으면, 응답은 404이며 User Not Found입니다.

GET /internal/authorized_certs

요청 예시:

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

그룹 CA에 대한 응답 예시:

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

namespace가 이미 그룹을 식별하지만, 그룹 CA가 일치한 경우에도 instance 필드는 false입니다. 이 필드는 추가 필드이므로 이 필드를 무시하는 이전 GitLab Shell도 계속 동작합니다. instance를 읽어, namespace가 비어 있는 그룹 범위 응답을 인스턴스 전체 신뢰로 취급하지 않고 거부하는 방안이 이슈 867에서 제안되었습니다.

인스턴스 CA에 대한 응답 예시:

{
  "success": true,
  "instance": true,
  "username": "root"
}

인스턴스 수준 CA는 그룹에 한정되지 않으므로 응답에 namespace 키가 없습니다.

알려진 사용처#

• GitLab Shell

사용자 ID 또는 키로 사용자 가져오기#

사용자가 ssh git@gitlab.com을 실행할 때 사용하는 엔드포인트입니다. SSH 키와 연결된 사용자를 찾습니다.

GET /internal/discover

요청 예시:

curl --request GET --header "Gitlab-Shell-Api-Request: " "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: " "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 복구 코드를 받을 수 있게 합니다.

GET /internal/two_factor_recovery_codes

요청 예시:

curl --request POST --header "Gitlab-Shell-Api-Request: " \
     --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에서 호출하며, 사용자가 새 개인 액세스 토큰을 생성할 수 있게 합니다.

POST /internal/personal_access_token

요청 예시:

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

Error Tracking 요청 인증#

오류 추적 Go REST API 애플리케이션이 프로젝트를 인증하기 위해 이 엔드포인트를 호출합니다.

POST /internal/error_tracking/allowed

요청 예시:

curl --request POST --header "Gitlab-Shell-Api-Request: " \
     --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 훅이 호출합니다.

POST /internal/pre_receive

요청 예시:

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

응답 예시:

{
  "reference_counter_increased": true
}

PostReceive#

푸시를 받은 뒤 Gitaly가 호출합니다. Sidekiq에서 PostReceive 워커를 트리거하고, 전달된 푸시 옵션을 처리하며, 사용자에게 표시해야 하는 메시지를 포함한 응답을 구성합니다.

POST /internal/post_receive

요청 예시:

curl --request POST --header "Gitlab-Shell-Api-Request: " \
     --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
}

Kubernetes용 GitLab 에이전트 엔드포인트#

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

이 엔드포인트는 모두 JWT로 인증합니다. JWT 시크릿은 config/gitlab.yml에 지정한 파일에 저장됩니다. 기본 위치는 GitLab Rails 앱의 루트이며 파일 이름은 .gitlab_kas_secret입니다.

Kubernetes용 GitLab 에이전트 정보#

Kubernetes용 GitLab 에이전트 서버(kas)가 지정한 에이전트 토큰의 에이전트 정보를 가져오기 위해 호출합니다. kas가 에이전트 구성을 가져오고 업데이트할 수 있도록 에이전트 프로젝트의 Gitaly 연결 정보를 반환합니다.

GET /internal/kubernetes/agent_info

요청 예시:

curl --request GET --header "Gitlab-Kas-Api-Request: " \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info"

Kubernetes용 GitLab 에이전트 프로젝트 정보#

Kubernetes용 GitLab 에이전트 서버(kas)가 지정한 에이전트 토큰의 프로젝트 정보를 가져오기 위해 호출합니다. 요청한 프로젝트의 Gitaly 연결을 반환합니다. GitLab kas는 이를 사용해 에이전트가 프로젝트 리포지터리에서 Kubernetes 리소스를 가져와 동기화하도록 구성합니다.

공개 프로젝트만 지원합니다. 비공개 프로젝트에서 에이전트를 인가하는 기능은 아직 구현되지 않았습니다.

GET /internal/kubernetes/project_info

요청 예시:

curl --request GET --header "Gitlab-Kas-Api-Request: " \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7"

Kubernetes용 GitLab 에이전트 사용량 메트릭#

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

POST /internal/kubernetes/usage_metrics

요청 예시:

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

Kubernetes용 GitLab 에이전트 이벤트#

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

POST /internal/kubernetes/agent_events

요청 예시:

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

Starboard 취약점 생성#

Kubernetes용 GitLab 에이전트 서버(kas)가 Starboard 취약점 보고서로부터 보안 취약점을 생성하기 위해 호출합니다. 이 요청은 멱등성을 가집니다. 같은 데이터로 여러 번 요청해도 하나의 취약점만 생성됩니다. 응답에는 생성된 취약점 발견 항목의 UUID가 포함됩니다.

PUT internal/kubernetes/modules/starboard_vulnerability

요청 예시:

curl --request PUT --header "Gitlab-Kas-Api-Request: " \
     --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"
}

Starboard 취약점 해결#

Kubernetes용 GitLab 에이전트 서버(kas)가 Starboard 보안 취약점을 해결 처리하기 위해 호출합니다. 발견 항목 UUID 목록을 받아, 목록에 없는 모든 Starboard 취약점을 해결됨으로 표시합니다.

POST internal/kubernetes/modules/starboard_vulnerability/scan_result

요청 예시:

curl --request POST --header "Gitlab-Kas-Api-Request: " \
     --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"] }'

스캔 실행 정책#

Kubernetes용 GitLab 에이전트 서버(kas)가 에이전트 토큰에 해당하는 프로젝트에 구성된 policies_configuration을 가져오기 위해 호출합니다. GitLab kas는 이를 사용해 정책에 따라 Kubernetes 클러스터의 이미지를 스캔하도록 에이전트를 구성합니다.

GET /internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies

요청 예시:

curl --request GET --header "Gitlab-Kas-Api-Request: " \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies"

응답 예시:

{
  "policies": [
    {
      "name": "Policy",
      "description": "Policy description",
      "enabled": true,
      "yaml": "---\nname: Policy\ndescription: 'Policy description'\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"
    }
  ]
}

정책 구성#

Kubernetes용 GitLab 에이전트 서버(kas)가 에이전트 토큰에 해당하는 프로젝트에 구성된 policies_configuration을 가져오기 위해 호출합니다. GitLab kas는 이를 사용해 구성에 따라 Kubernetes 클러스터의 이미지를 스캔하도록 에이전트를 구성합니다.

GET /internal/kubernetes/modules/starboard_vulnerability/policies_configuration

요청 예시:

curl --request GET --header "Gitlab-Kas-Api-Request: " \
     --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"
    }
  ]
}

검색#

다음 엔드포인트는 Zoekt 같은 GitLab 검색 서비스가 사용합니다.

Zoekt#

다음 엔드포인트는 Zoekt가 하트비트와 인덱싱 콜백 응답을 보내기 위해 호출합니다.

하트비트 전송 및 인덱싱 작업 가져오기#

이 엔드포인트를 사용해 노드의 Last seen at 타임스탬프를 계속 업데이트하고 Zoekt의 미처리 작업을 가져옵니다.

POST /internal/search/zoekt/:uuid/heartbeat

요청 예시:

curl --location "https://example.com/api/v4/internal/search/3869fe21-36d1-4612-9676-0b783ef2dcd7/heartbeat" \
--header "Gitlab-Shell-Api-Request: " \
--header "Content-Type: application/json" \
--data '{
    "node.url": "http://localhost:6090",
    "node.name": "foo.local",
    "disk.all": "994662584320",
    "disk.used": "532673712128"
}'

응답 예시:

{
  "id": 1,
  "truncate": true,
  "tasks": [
    {
      "name": "index",
      "payload": {
        "GitalyConnectionInfo": {
          "Address": "unix:/praefect.socket",
          "Token": null,
          "Storage": "default",
          "Path": "@hashed/79/02/7902699be42c8a8e46fbbb4501726517e86b22c56a189f7625a6da49081d9043.git",
          "Callback": {
            "name": "index",
            "Payload": {
              "task_id": 1,
              "schema_version": 2531
            }
          },
          "RepoId": 1,
          "FileSizeLimit": 1048576,
          "Parallelism": 1,
          "Timeout": "1800s",
          "FileCountLimit": 500000,
          "TrigramMax": 20000,
          "MissingRepo": false,
          "Metadata": {
            "project_id": "1",
            "traversal_ids": "3-",
            "visibility_level": "10",
            "repository_access_level": "20",
            "forked": "f",
            "archived": "f"
          },
          "Force": true
        }
      }
    }
  ],
  "pull_frequency": "5s",
  "stop_indexing": false
}

인덱싱 작업 처리 후 콜백 전송#

이 엔드포인트를 사용해 인덱싱 작업을 처리한 뒤 페이로드 데이터가 담긴 콜백을 전송합니다.

POST /internal/search/zoekt/:uuid/callback

요청 예시:

curl --location "https://example.com/api/v4/internal/search/3869fe21-36d1-4612-9676-0b783ef2dcd7/callback" \
--header "Gitlab-Shell-Api-Request: " \
--header "Content-Type: application/json" \
--data '{
    "name": "index",
    "success": true,
    "payload": { "schema_version": 2531, "task_id": 48 },
    "additional_payload": { "repo_stats": { "index_file_count": 1, "size_in_bytes": 41800 } }
}'

응답 예시:

{ "message": "202 Accepted" }

스토리지 한도 예외#

네임스페이스 스토리지 한도 예외 엔드포인트는 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

요청 예시:

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#

히스토리

• 사용자 프로비저닝 해제가 GitLab 19.0에서 동기 방식에서 비동기 방식으로 변경되었습니다.

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

이 API를 사용하려면 해당 그룹에 Group SSO를 활성화합니다. 이 API는 Group SSO용 SCIM이 활성화된 경우에만 사용됩니다. SCIM ID를 생성하기 위한 사전 요구 사항입니다.

이 그룹 SCIM API는 다음과 같습니다.

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

인스턴스 SCIM API는 인스턴스에 대해 같은 기능을 제공합니다.

이 그룹 SCIM API는 SCIM API와 다릅니다. SCIM API는 다음과 같습니다.

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

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

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

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

매개변수:

특정 식별자로 필터링하는 요청 예시:

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

매개변수:

요청 예시:

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/

매개변수:

요청 예시:

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 프로비저닝 단일 사용자 업데이트#

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

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

매개변수:

사용자의 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 ID와 그룹 멤버십을 제거합니다.

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

매개변수:

요청 예시:

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#

히스토리

• 그룹 동기화 지원이 GitLab 18.0에서 추가되었습니다.

인스턴스 SCIM API는 RFC7644 프로토콜을 부분적으로 구현합니다. 이 API는 사용자와 그룹을 관리하는 엔드포인트를 제공합니다. 기본 URL은 <http|https>:///api/scim/v2입니다. 이 API는 SCIM 공급자 통합을 위한 시스템용이므로 예고 없이 변경될 수 있습니다.

이 API를 사용하려면 인스턴스에 SAML SSO를 활성화합니다.

이 인스턴스 SCIM API는 다음과 같습니다.

• SCIM 공급자 통합을 위한 시스템용입니다.
• RFC7644 프로토콜을 구현합니다.
• SCIM 프로비저닝 사용자 목록을 가져옵니다.
• SCIM 프로비저닝 사용자를 생성, 삭제, 업데이트합니다.
• SAML 그룹 링크를 통해 그룹 멤버십을 관리합니다.

그룹 SCIM API는 그룹에 대해 같은 기능을 제공합니다.

이 인스턴스 SCIM API는 SCIM API와 다릅니다. SCIM API는 다음과 같습니다.

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

사용자 엔드포인트#

사용자 엔드포인트를 사용해 SCIM 프로비저닝 사용자를 관리합니다.

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

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

GET /api/scim/v2/application/Users

매개변수:

요청 예시:

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
        }
      ],
      "groups": [
        {
          "value": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
          "display": "Developers",
          "type": "direct"
        }
      ]
    }
  ]
}

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

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

매개변수:

요청 예시:

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
    }
  ],
  "groups": [
    {
      "value": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
      "display": "Developers",
      "type": "direct"
    }
  ]
}

groups의 각 항목은 사용자가 속한 SCIM 그룹을 나타냅니다. 이 속성은 읽기 전용입니다. 그룹 멤버십을 변경하려면 그룹 엔드포인트를 사용합니다.

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

POST /api/scim/v2/application/Users

매개변수:

요청 예시:

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 프로비저닝 단일 사용자 업데이트#

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

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

매개변수:

요청 예시:

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"},{"op":"Update","path":"id","value":"foo"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공하면 상태 코드 204와 함께 빈 응답을 반환합니다.

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

사용자는 blocked 상태가 되고 로그아웃됩니다. 즉, 사용자는 로그인하거나 코드를 푸시하거나 풀할 수 없습니다.

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

매개변수:

요청 예시:

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와 함께 빈 응답을 반환합니다.

그룹 엔드포인트#

그룹 엔드포인트를 사용해 GitLab을 SCIM ID 공급자와 자동으로 동기화합니다.

이 API는 SAML 그룹 링크를 사용해 IdP 그룹을 GitLab 그룹과 연결합니다. 이 엔드포인트를 사용하기 전에 동기화할 그룹에 필요한 SAML 그룹 링크를 먼저 생성해야 합니다.

SCIM 그룹 목록 가져오기#

이 엔드포인트는 SCIM ID가 할당된 그룹의 목록을 반환합니다.

GET /api/scim/v2/application/Groups

매개변수:

요청 예시:

curl "https://gitlab.example.com/api/scim/v2/application/Groups?filter=displayName%20eq%20%22Developers%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:Group"
      ],
      "id": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
      "displayName": "Developers",
      "members": [
        {
          "value": "2435223452",
          "display": "Sidney Jones",
          "type": "User"
        }
      ],
      "meta": {
        "resourceType": "Group"
      }
    }
  ]
}

SCIM 단일 그룹 가져오기#

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

매개변수:

요청 예시:

curl "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

응답 예시:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
  "displayName": "Developers",
  "members": [
    {
      "value": "2435223452",
      "display": "Sidney Jones",
      "type": "User"
    }
  ],
  "meta": {
    "resourceType": "Group"
  }
}

members의 각 항목은 SCIM 그룹에 속한 사용자를 나타냅니다.

SCIM 그룹 생성#

이 엔드포인트는 SCIM 그룹 ID를 이름이 같은 기존 SAML 그룹 링크와 연결합니다.

POST /api/scim/v2/application/Groups

매개변수:

요청 예시:

curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/application/Groups" \
     --data '{"displayName":"Developers","schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

응답 예시:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
  "displayName": "Developers",
  "members": [],
  "meta": {
    "resourceType": "Group"
  }
}

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

SCIM 그룹 업데이트#

SCIM 그룹의 멤버를 업데이트합니다. SCIM 그룹과 연결된 GitLab 그룹에서 사용자를 추가하거나 제거하는 데 사용합니다.

PATCH /api/scim/v2/application/Groups/:id

매개변수:

지원하는 연산:

• 경로 members를 사용한 add: 그룹에 멤버 추가
• 경로 members를 사용한 remove: 그룹에서 멤버 제거

멤버를 추가하는 요청 예시:

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --data '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations":[{"op":"add","path":"members","value":[{"value":"f0b1d561c-21ff-4092-beab-8154b17f82f2"}]}]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

멤버를 제거하는 요청 예시:

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --data '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations":[{"op":"remove","path":"members","value":[{"value":"f0b1d561c-21ff-4092-beab-8154b17f82f2"}]}]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공하면 상태 코드 204와 함께 빈 응답을 반환합니다.

SCIM 그룹 교체#

SCIM 그룹의 모든 멤버를 새 멤버 집합으로 교체합니다.

PUT /api/scim/v2/application/Groups/:id

매개변수:

요청 예시:

curl --verbose --request PUT "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --data '{"schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"],"displayName":"Developers","members":[{"value":"f0b1d561c-21ff-4092-beab-8154b17f82f2"}]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

응답에는 업데이트된 그룹 정보가 포함됩니다.

SCIM 그룹 삭제#

SCIM 그룹 ID를 지워 기존 SAML 그룹 링크에서 SCIM 관리를 제거합니다. 이 엔드포인트는 SCIM 그룹 멤버십 추적 레코드를 정리하는 백그라운드 작업도 예약합니다.

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

매개변수:

요청 예시:

curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공하면 상태 코드 204와 함께 빈 응답을 반환합니다.

사용 가능한 필터#

RFC7644 필터링 절에 명시된 표현식과 일치시킵니다.

예시:

id eq a-b-c-d

사용 가능한 연산#

RFC7644 업데이트 절에 명시된 연산을 수행합니다.

예시:

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