InfoGrab DocsInfoGrab Docs

그룹 API

요약

이 API로 GitLab 그룹을 조회하고 관리합니다. 엔드포인트 응답은 그룹에서 인증된 사용자의 권한에 따라 달라질 수 있습니다. 그룹의 세부 정보를 조회합니다. 응답의 projects 및 shared_projects 속성은 deprecated 처리되었으며 API v5에서 제거될 예정입니다.

이 API로 GitLab 그룹을 조회하고 관리합니다. 자세한 내용은 그룹을 참고합니다.

엔드포인트 응답은 그룹에서 인증된 사용자의 권한에 따라 달라질 수 있습니다.

그룹 조회#

그룹의 세부 정보를 조회합니다. 그룹이 공개적으로 접근 가능하면 이 엔드포인트는 인증 없이도 접근할 수 있습니다. 요청한 사용자가 관리자이면 추가 정보가 반환됩니다. 인증한 경우, 사용자가 관리자이거나 Owner 권한을 가지고 있으면 해당 그룹의 runners_token과 enabled_git_access_protocol도 반환합니다.

GET /groups/:id

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용).
with_projects boolean no 지정한 그룹에 속한 프로젝트의 세부 정보를 포함합니다(기본값 true). (Deprecated 처리되었으며 API v5에서 제거될 예정입니다. 그룹 내 모든 프로젝트의 세부 정보를 가져오려면 그룹 프로젝트 목록 조회 엔드포인트를 사용합니다.)
Note

응답의 projects 및 shared_projects 속성은 deprecated 처리되었으며 API v5에서 제거될 예정입니다. 그룹 내 모든 프로젝트의 세부 정보를 가져오려면 그룹 프로젝트 목록 조회 또는 그룹 공유 프로젝트 목록 조회 엔드포인트를 사용합니다.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4"

이 엔드포인트는 최대 100개의 프로젝트와 공유 프로젝트를 반환합니다. 그룹 내 모든 프로젝트의 세부 정보를 가져오려면 그룹 프로젝트 목록 조회 엔드포인트를 사용합니다.

응답 예시:

{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "visibility": "public",
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Twitter",
  "full_path": "twitter",
  "runners_token": "ba324ca7b1c77fc20bb9",
  "file_template_project_id": 1,
  "parent_id": null,
  "enabled_git_access_protocol": "all",
  "created_at": "2020-01-15T12:36:29.590Z",
  "shared_with_groups": [
    {
      "group_id": 28,
      "group_name": "H5bp",
      "group_full_path": "h5bp",
      "group_access_level": 20,
      "expires_at": null
    }
  ],
  "prevent_sharing_groups_outside_hierarchy": false,
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": false,
  "only_allow_merge_if_all_discussions_are_resolved": false,
  "projects": [ // Deprecated and will be removed in API v5
    {
      "id": 7,
      "description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "public",
      "ssh_url_to_repo": "git@gitlab.example.com:twitter/typeahead-js.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/typeahead-js.git",
      "web_url": "https://gitlab.example.com/twitter/typeahead-js",
      "name": "Typeahead.Js",
      "name_with_namespace": "Twitter / Typeahead.Js",
      "path": "typeahead-js",
      "path_with_namespace": "twitter/typeahead-js",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:25.578Z",
      "last_activity_at": "2016-06-17T07:47:25.881Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 3,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    },
    {
      "id": 6,
      "description": "Aspernatur omnis repudiandae qui voluptatibus eaque.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "internal",
      "ssh_url_to_repo": "git@gitlab.example.com:twitter/flight.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/flight.git",
      "web_url": "https://gitlab.example.com/twitter/flight",
      "name": "Flight",
      "name_with_namespace": "Twitter / Flight",
      "path": "flight",
      "path_with_namespace": "twitter/flight",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:24.661Z",
      "last_activity_at": "2016-06-17T07:47:24.838Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 8,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    }
  ],
  "shared_projects": [ // Deprecated and will be removed in API v5
    {
      "id": 8,
      "description": "Velit eveniet provident fugiat saepe eligendi autem.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "private",
      "ssh_url_to_repo": "git@gitlab.example.com:h5bp/html5-boilerplate.git",
      "http_url_to_repo": "https://gitlab.example.com/h5bp/html5-boilerplate.git",
      "web_url": "https://gitlab.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "H5bp / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:27.089Z",
      "last_activity_at": "2016-06-17T07:47:27.310Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "H5bp",
        "path": "h5bp",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 4,
      "public_jobs": true,
      "shared_with_groups": [
        {
          "group_id": 4,
          "group_name": "Twitter",
          "group_full_path": "twitter",
          "group_access_level": 30,
          "expires_at": null
        },
        {
          "group_id": 3,
          "group_name": "Gitlab Org",
          "group_full_path": "gitlab-org",
          "group_access_level": 10,
          "expires_at": "2018-08-14"
        }
      ]
    }
  ],
  "ip_restriction_ranges": null,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false,
  "require_sha_for_merge": false,
  "lock_require_sha_for_merge": false
}

prevent_sharing_groups_outside_hierarchy 속성은 최상위 그룹에만 존재합니다.

GitLab Premium 또는 Ultimate 사용자에게는 다음 속성도 표시됩니다.

  • shared_runners_minutes_limit
  • extra_shared_runners_minutes_limit
  • marked_for_deletion_on
  • membership_lock
  • wiki_access_level
  • duo_features_enabled
  • lock_duo_features_enabled
  • duo_availability
  • experiment_features_enabled

추가 응답 속성:

{
  "id": 4,
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  "marked_for_deletion_on": "2020-04-03",
  "membership_lock": false,
  "wiki_access_level": "disabled",
  "duo_features_enabled": true,
  "lock_duo_features_enabled": false,
  "duo_availability": "default_on",
  "experiment_features_enabled": false,
  "ai_settings": {
    "duo_agent_platform_enabled": true,
    "duo_workflow_mcp_enabled": false,
    "foundational_agents_default_enabled": true,
    "ai_catalog_restricted_to_group_hierarchy": false,
    "ai_usage_data_collection_enabled": false,
    "prompt_injection_protection_level": "no_checks",
    "web_search_enabled": false,
    "include_recommended_allowed": false,
    "allow_all_unix_sockets": false,
    "allow_project_extension": true,
    "minimum_access_level_execute": "developer",
    "minimum_access_level_execute_async": "developer",
    "minimum_access_level_manage": "maintainer",
    "minimum_access_level_enable_on_projects": "maintainer"
  },
  ...
}

ai_settings 객체에는 그룹의 AI 관련 설정이 담겨 있습니다. 자세한 내용은 ai_settings에 대한 응답 속성을 참고합니다.

ai_settings에 대한 응답 속성#

히스토리
  • GitLab 19.2에서 도입되었습니다.

ai_settings 객체는 그룹에서 GitLab Duo Agent Platform을 사용할 수 있을 때, 그룹을 읽을 수 있는 사용자의 응답에 포함됩니다. 이 객체에는 다음 속성이 있습니다.

속성 유형 설명
ai_catalog_restricted_to_group_hierarchy boolean true 인 경우 AI 카탈로그가 이 최상위 그룹 계층의 항목으로 제한됩니다. Premium 및 Ultimate 전용.
ai_usage_data_collection_enabled boolean true 인 경우 이 그룹에 대해 AI 사용 데이터 수집이 활성화됩니다. GitLab.com 전용.
allow_all_unix_sockets boolean true 인 경우 GitLab Duo Agent Platform에 대해 모든 Unix 소켓이 허용됩니다.
allow_project_extension boolean true 인 경우 프로젝트가 GitLab Duo Agent Platform의 네트워크 액세스 도메인 허용 목록을 확장할 수 있습니다.
duo_agent_platform_enabled boolean true 인 경우 이 그룹에 대해 GitLab Duo Agent Platform 기능이 활성화됩니다. Premium 및 Ultimate. GitLab Credits가 있는 GitLab.com의 Free 등급에서도 사용 가능.
duo_workflow_mcp_enabled boolean true 인 경우 GitLab Duo Agent Platform에 대한 MCP 지원이 활성화됩니다. Premium 및 Ultimate. GitLab Credits가 있는 GitLab.com의 Free 등급에서도 사용 가능.
foundational_agents_default_enabled boolean true 인 경우 이 그룹에 대해 새로운 파운데이셔널 에이전트가 기본적으로 활성화됩니다. Premium 및 Ultimate. GitLab Credits가 있는 GitLab.com의 Free 등급에서도 사용 가능.
include_recommended_allowed boolean true 인 경우 GitLab Duo Agent Platform의 네트워크 액세스 허용 목록에 권장 도메인이 포함됩니다.
minimum_access_level_enable_on_projects string 프로젝트에서 GitLab Duo Agent Platform을 활성화하는 데 필요한 최소 액세스 수준. developer, maintainer, owner 중 하나. dap_group_customizable_permissions 기능 플래그가 활성화된 경우 반환됩니다.
minimum_access_level_execute string 사용자가 GitLab Duo Agent Platform 기능과 상호 작용하는 데 필요한 최소 액세스 수준. guest, planner, reporter, developer, maintainer, owner 중 하나. dap_group_customizable_permissions 기능 플래그가 활성화된 경우 반환됩니다.
minimum_access_level_execute_async string CI/CD에서 GitLab Duo Agent Platform 기능을 실행하는 데 필요한 최소 액세스 수준. developer, maintainer, owner 중 하나. dap_group_customizable_permissions 기능 플래그가 활성화된 경우 반환됩니다.
minimum_access_level_manage string GitLab Duo Agent Platform을 관리하는 데 필요한 최소 액세스 수준. developer, maintainer, owner 중 하나. dap_group_customizable_permissions 기능 플래그가 활성화된 경우 반환됩니다.
prompt_injection_protection_level string 프롬프트 인젝션 보호 수준. no_checks, log_only, interrupt 중 하나.
web_search_enabled boolean true 인 경우 이 그룹의 GitLab Duo Chat에서 웹 검색이 활성화됩니다.

with_projects=false 파라미터를 추가하면 프로젝트가 반환되지 않습니다.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4?with_projects=false"

응답 예시:

{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "visibility": "public",
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Twitter",
  "full_path": "twitter",
  "file_template_project_id": 1,
  "parent_id": null
}

그룹 목록 조회#

전체 그룹 목록 조회#

인증된 사용자에게 보이는 그룹을 조회합니다. 인증 없이 접근하면 공개 그룹만 반환됩니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

인증 없이 접근하는 경우 이 엔드포인트는 키셋 페이지네이션도 지원합니다.

파라미터:

Attribute Type Required Description
skip_groups array of integers no 전달한 그룹 ID를 건너뜁니다.
all_available boolean no true 인 경우 접근 가능한 모든 그룹을 반환합니다. false 인 경우 사용자가 멤버인 그룹만 반환합니다. 기본값은 일반 사용자의 경우 false, 관리자의 경우 true 입니다. 인증되지 않은 요청은 항상 모든 공개 그룹을 반환합니다. owned 및 min_access_level 속성이 우선합니다.
search string no 검색 조건과 일치하는 인가된 그룹 목록을 반환합니다.
order_by string no 그룹을 name, path, id, similarity 기준으로 정렬합니다. 기본값은 name 입니다.
sort string no 그룹을 asc 또는 desc 순으로 정렬합니다. 기본값은 asc 입니다.
statistics boolean no 그룹 통계를 포함합니다(관리자 전용).
최상위 그룹의 경우 응답은 UI에 표시되는 전체 root_storage_statistics 데이터를 반환합니다. GitLab 17.4에서 도입되었습니다.
visibility string no 가시성이 public, internal, private 인 그룹으로 제한합니다.
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용).
owned boolean no 현재 사용자가 명시적으로 소유한 그룹으로 제한합니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 그룹으로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
top_level_only boolean no 모든 하위 그룹을 제외하고 최상위 그룹으로 제한합니다.
repository_storage string no 그룹이 사용하는 리포지터리 스토리지로 필터링합니다(관리자 전용). Premium 및 Ultimate 전용.
marked_for_deletion_on date no 그룹이 삭제 대상으로 표시된 날짜로 필터링합니다. GitLab 17.1에서 도입되었습니다. Premium 및 Ultimate 전용.
active boolean no 보관되지 않았고 삭제 대상으로 표시되지 않은 그룹으로 제한합니다.
archived boolean no 보관된 그룹으로 제한합니다. GitLab 18.2에서 도입되었습니다. 
GET /groups

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": null,
    "created_at": "2020-01-15T12:36:29.590Z",
    "ip_restriction_ranges": null
  }
]

statistics=true 파라미터를 추가하고 인증된 사용자가 관리자이면 추가 그룹 통계가 반환됩니다. 최상위 그룹의 경우 root_storage_statistics도 함께 추가됩니다.

GET /groups?statistics=true

statistics=true 파라미터를 사용하고 인증된 사용자가 관리자이면 응답에 컨테이너 레지스트리 스토리지 크기 정보가 포함됩니다.

  • container_registry_size: 그룹과 그 하위 그룹의 모든 컨테이너 리포지터리가 사용하는 총 스토리지 크기(바이트). 그룹의 프로젝트와 하위 그룹에 속한 모든 리포지터리 크기의 합으로 계산됩니다. 컨테이너 레지스트리 메타데이터 데이터베이스가 활성화된 경우에만 사용할 수 있습니다.
  • container_registry_size_is_estimated: 크기가 모든 리포지터리의 실제 데이터를 기반으로 한 정확한 계산인지(false), 성능 제약으로 인한 추정치인지(true)를 나타냅니다.

GitLab Self-Managed 인스턴스에서 컨테이너 레지스트리 크기 속성을 포함하려면 컨테이너 레지스트리 메타데이터 데이터베이스를 활성화해야 합니다.

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": null,
    "created_at": "2020-01-15T12:36:29.590Z",
    "statistics": {
      "storage_size": 363,
      "repository_size": 33,
      "wiki_size": 100,
      "lfs_objects_size": 123,
      "job_artifacts_size": 57,
      "pipeline_artifacts_size": 0,
      "packages_size": 0,
      "snippets_size": 50,
      "uploads_size": 0
    },
    "root_storage_statistics": {
      "build_artifacts_size": 0,
      "container_registry_size": 0,
      "container_registry_size_is_estimated": false,
      "dependency_proxy_size": 0,
      "lfs_objects_size": 0,
      "packages_size": 0,
      "pipeline_artifacts_size": 0,
      "repository_size": 0,
      "snippets_size": 0,
      "storage_size": 0,
      "uploads_size": 0,
      "wiki_size": 0
  },
    "wiki_access_level": "private",
    "duo_features_enabled": true,
    "lock_duo_features_enabled": false,
    "duo_availability": "default_on",
    "experiment_features_enabled": false,
  }
]

GitLab Premium 또는 Ultimate 사용자에게는 wiki_access_level, duo_features_enabled, lock_duo_features_enabled,

duo_availability, experiment_features_enabled 속성도 표시됩니다.

아래에 설명한 대로 이름 또는 경로로 그룹을 검색할 수 있습니다.

사용자 지정 속성으로 다음과 같이 필터링할 수 있습니다.

GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_value

그룹 페이지네이션#

API 결과가 페이지네이션 처리되므로 기본적으로 한 번에 20개의 그룹만 표시됩니다.

더 많은 결과(최대 100개)를 가져오려면 API 호출에 다음 인수를 전달합니다.

/groups?per_page=100

페이지를 전환하려면 다음을 추가합니다.

/groups?per_page=100&page=2

그룹 검색#

이름 또는 경로에 특정 문자열이 포함된 그룹을 검색합니다.

GET /groups?search=foobar

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group"
  }
]

그룹 세부 정보 목록 조회#

프로젝트 목록 조회#

그룹 내 프로젝트를 조회합니다. 인증 없이 접근하면 공개 프로젝트만 반환됩니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

GET /groups/:id/projects

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
active boolean no 프로젝트 상태로 제한합니다. true 인 경우 활성 프로젝트를 반환합니다. false 인 경우 보관되었거나 삭제 대상으로 표시된 프로젝트를 반환합니다. GitLab 18.8에서 도입되었습니다.
archived boolean no 보관 상태로 제한합니다.
visibility string no 가시성 public, internal, private로 제한합니다.
order_by string no id, name, path, created_at, updated_at, similarity1, star_count, last_activity_at 필드 기준으로 정렬한 프로젝트를 반환합니다. 기본값은 created_at 입니다.
sort string no 프로젝트를 asc 또는 desc 순으로 정렬해 반환합니다. 기본값은 desc 입니다.
search string no 검색 조건과 일치하는 인가된 프로젝트 목록을 반환합니다.
simple boolean no 각 프로젝트의 제한된 필드만 반환합니다. 인증 없이 요청하면 단순 필드만 반환되므로 이 옵션은 동작하지 않습니다.
owned boolean no 현재 사용자가 소유한 프로젝트로 제한합니다.
starred boolean no 현재 사용자가 별표 표시한 프로젝트로 제한합니다.
topic string no 해당 토픽과 일치하는 프로젝트를 반환합니다.
with_issues_enabled boolean no 이슈 기능이 활성화된 프로젝트로 제한합니다. 기본값은 false 입니다.
with_merge_requests_enabled boolean no 머지 리퀘스트 기능이 활성화된 프로젝트로 제한합니다. 기본값은 false 입니다.
with_shared boolean no 이 그룹에 공유된 프로젝트를 포함합니다. 기본값은 true 입니다.
include_subgroups boolean no 이 그룹의 하위 그룹에 있는 프로젝트를 포함합니다. 기본값은 false 입니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 프로젝트로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용).
with_security_reports boolean no 빌드 중 하나라도 보안 리포트 아티팩트가 있는 프로젝트만 반환합니다. 즉 "보안 리포트가 활성화된 프로젝트"를 의미합니다. 기본값은 false 입니다. Ultimate 전용.

응답 예시:

[
  {
    "id": 9,
    "description": "foo",
    "default_branch": "main",
    "tag_list": [], //deprecated, use `topics` instead
    "topics": [],
    "archived": false,
    "visibility": "internal",
    "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
    "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
    "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
    "name": "Html5 Boilerplate",
    "name_with_namespace": "Experimental / Html5 Boilerplate",
    "path": "html5-boilerplate",
    "path_with_namespace": "h5bp/html5-boilerplate",
    "issues_enabled": true,
    "merge_requests_enabled": true,
    "wiki_enabled": true,
    "jobs_enabled": true,
    "snippets_enabled": true,
    "created_at": "2016-04-05T21:40:50.169Z",
    "last_activity_at": "2016-04-06T16:52:08.432Z",
    "shared_runners_enabled": true,
    "creator_id": 1,
    "namespace": {
      "id": 5,
      "name": "Experimental",
      "path": "h5bp",
      "kind": "group"
    },
    "avatar_url": null,
    "star_count": 1,
    "forks_count": 0,
    "open_issues_count": 3,
    "public_jobs": true,
    "shared_with_groups": [],
    "request_access_enabled": false
  }
]
Note

그룹에 속한 프로젝트와 그룹에 공유된 프로젝트를 구분하려면 namespace 속성을 사용합니다. 프로젝트가 그룹에 공유된 경우, 해당 프로젝트의 namespace는 요청 대상 그룹과 다릅니다.

공유 프로젝트 목록 조회#

그룹에 공유된 프로젝트를 조회합니다. 인증 없이 접근하면 공개된 공유 프로젝트만 반환됩니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

GET /groups/:id/projects/shared

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
archived boolean no 보관 상태로 제한합니다.
visibility string no 가시성 public, internal, private로 제한합니다.
order_by string no id, name, path, created_at, updated_at, star_count, last_activity_at 필드 기준으로 정렬한 프로젝트를 반환합니다. 기본값은 created_at 입니다.
sort string no 프로젝트를 asc 또는 desc 순으로 정렬해 반환합니다. 기본값은 desc 입니다.
search string no 검색 조건과 일치하는 인가된 프로젝트 목록을 반환합니다.
simple boolean no 각 프로젝트의 제한된 필드만 반환합니다. 인증 없이 요청하면 단순 필드만 반환되므로 이 옵션은 동작하지 않습니다.
starred boolean no 현재 사용자가 별표 표시한 프로젝트로 제한합니다.
with_issues_enabled boolean no 이슈 기능이 활성화된 프로젝트로 제한합니다. 기본값은 false 입니다.
with_merge_requests_enabled boolean no 머지 리퀘스트 기능이 활성화된 프로젝트로 제한합니다. 기본값은 false 입니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 프로젝트로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용).

응답 예시:

[
   {
      "id":8,
      "description":"Shared project for Html5 Boilerplate",
      "name":"Html5 Boilerplate",
      "name_with_namespace":"H5bp / Html5 Boilerplate",
      "path":"html5-boilerplate",
      "path_with_namespace":"h5bp/html5-boilerplate",
      "created_at":"2020-04-27T06:13:22.642Z",
      "default_branch":"main",
      "tag_list":[], //deprecated, use `topics` instead
      "topics":[],
      "ssh_url_to_repo":"ssh://git@gitlab.com/h5bp/html5-boilerplate.git",
      "http_url_to_repo":"https://gitlab.com/h5bp/html5-boilerplate.git",
      "web_url":"https://gitlab.com/h5bp/html5-boilerplate",
      "readme_url":"https://gitlab.com/h5bp/html5-boilerplate/-/blob/main/README.md",
      "avatar_url":null,
      "star_count":0,
      "forks_count":4,
      "last_activity_at":"2020-04-27T06:13:22.642Z",
      "namespace":{
         "id":28,
         "name":"H5bp",
         "path":"h5bp",
         "kind":"group",
         "full_path":"h5bp",
         "parent_id":null,
         "avatar_url":null,
         "web_url":"https://gitlab.com/groups/h5bp"
      },
      "_links":{
         "self":"https://gitlab.com/api/v4/projects/8",
         "issues":"https://gitlab.com/api/v4/projects/8/issues",
         "merge_requests":"https://gitlab.com/api/v4/projects/8/merge_requests",
         "repo_branches":"https://gitlab.com/api/v4/projects/8/repository/branches",
         "labels":"https://gitlab.com/api/v4/projects/8/labels",
         "events":"https://gitlab.com/api/v4/projects/8/events",
         "members":"https://gitlab.com/api/v4/projects/8/members"
      },
      "empty_repo":false,
      "archived":false,
      "visibility":"public",
      "resolve_outdated_diff_discussions":false,
      "container_registry_enabled":true,
      "container_expiration_policy":{
         "cadence":"7d",
         "enabled":true,
         "keep_n":null,
         "older_than":null,
         "name_regex":null,
         "name_regex_keep":null,
         "next_run_at":"2020-05-04T06:13:22.654Z"
      },
      "issues_enabled":true,
      "merge_requests_enabled":true,
      "wiki_enabled":true,
      "jobs_enabled":true,
      "snippets_enabled":true,
      "can_create_merge_request_in":true,
      "issues_access_level":"enabled",
      "repository_access_level":"enabled",
      "merge_requests_access_level":"enabled",
      "forking_access_level":"enabled",
      "wiki_access_level":"enabled",
      "builds_access_level":"enabled",
      "snippets_access_level":"enabled",
      "pages_access_level":"enabled",
      "security_and_compliance_access_level":"enabled",
      "emails_disabled":null,
      "emails_enabled": null,
      "shared_runners_enabled":true,
      "lfs_enabled":true,
      "creator_id":1,
      "import_status":"failed",
      "open_issues_count":10,
      "ci_default_git_depth":50,
      "ci_forward_deployment_enabled":true,
      "ci_forward_deployment_rollback_allowed": true,
      "ci_allow_fork_pipelines_to_run_in_parent_project":true,
      "public_jobs":true,
      "build_timeout":3600,
      "auto_cancel_pending_pipelines":"enabled",
      "ci_config_path":null,
      "shared_with_groups":[
         {
            "group_id":24,
            "group_name":"Commit451",
            "group_full_path":"Commit451",
            "group_access_level":30,
            "expires_at":null
         }
      ],
      "only_allow_merge_if_pipeline_succeeds":false,
      "request_access_enabled":true,
      "only_allow_merge_if_all_discussions_are_resolved":false,
      "remove_source_branch_after_merge":true,
      "printing_merge_request_link_enabled":true,
      "merge_method":"merge",
      "suggestion_commit_message":null,
      "auto_devops_enabled":true,
      "auto_devops_deploy_strategy":"continuous",
      "autoclose_referenced_issues":true,
      "repository_storage":"default"
   }
]

공유 프로젝트 삭제#

그룹에 공유된 프로젝트를 삭제합니다. 그룹에서 Owner 권한이 필요합니다.

DELETE /groups/:id/shared_projects/:project_id

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
project_id integer yes 프로젝트의 ID.

성공하면 204 No Content를 반환합니다.

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/shared_projects/2"

전체 SAML 사용자 목록 조회#

히스토리
  • GitLab 18.1에서 도입되었습니다.

지정한 최상위 그룹의 모든 SAML 사용자를 조회합니다.

page 및 per_page 페이지네이션 파라미터로 결과를 필터링합니다.

GET /groups/:id/saml_users

지원 속성:

Attribute Type Required Description
id integer or string yes 최상위 그룹의 ID 또는 URL 인코딩된 경로.
username string no 지정한 사용자 이름을 가진 사용자를 반환합니다.
search string no 이름, 이메일, 사용자 이름이 일치하는 사용자를 반환합니다. 일부 값만 입력하면 결과 범위를 넓힐 수 있습니다.
active boolean no 활성 사용자만 반환합니다.
blocked boolean no 차단된 사용자만 반환합니다.
created_after datetime no 지정한 시각 이후에 생성된 사용자를 반환합니다. 형식: ISO 8601(YYYY-MM-DDTHH:MM:SSZ).
created_before datetime no 지정한 시각 이전에 생성된 사용자를 반환합니다. 형식: ISO 8601(YYYY-MM-DDTHH:MM:SSZ).

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/saml_users"

응답 예시:

[
  {
    "id": 66,
    "username": "user22",
    "name": "Sidney Jones22",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?s=80&d=identicon",
    "web_url": "http://my.gitlab.com/user22",
    "created_at": "2021-09-10T12:48:22.381Z",
    "bio": "",
    "location": null,
    "public_email": "",
    "linkedin": "",
    "twitter": "",
    "website_url": "",
    "organization": null,
    "job_title": "",
    "pronouns": null,
    "bot": false,
    "work_information": null,
    "followers": 0,
    "following": 0,
    "local_time": null,
    "last_sign_in_at": null,
    "confirmed_at": "2021-09-10T12:48:22.330Z",
    "last_activity_on": null,
    "email": "user22@example.org",
    "theme_id": 1,
    "color_scheme_id": 1,
    "projects_limit": 100000,
    "current_sign_in_at": null,
    "identities": [
      {
        "provider": "group_saml",
        "extern_uid": "2435223452345",
        "saml_provider_id": 1
      }
    ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": false,
    "external": false,
    "private_profile": false,
    "commit_email": "user22@example.org",
    "shared_runners_minutes_limit": null,
    "extra_shared_runners_minutes_limit": null,
    "scim_identities": [
      {
        "extern_uid": "2435223452345",
        "group_id": 1,
        "active": true
      }
    ]
  },
  ...
]

프로비저닝된 사용자 목록 조회#

그룹이 프로비저닝한 사용자를 조회합니다. 하위 그룹은 포함하지 않습니다.

그룹에서 Maintainer 또는 Owner 권한이 필요합니다.

GET /groups/:id/provisioned_users

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
username string no 특정 사용자 이름을 가진 사용자 한 명을 반환합니다.
search string no 이름, 이메일, 사용자 이름으로 사용자를 검색합니다.
active boolean no 활성 사용자만 반환합니다.
blocked boolean no 차단된 사용자만 반환합니다.
created_after datetime no 지정한 시각 이후에 생성된 사용자를 반환합니다.
created_before datetime no 지정한 시각 이전에 생성된 사용자를 반환합니다.

응답 예시:

[
  {
    "id": 66,
    "username": "user22",
    "name": "John Doe22",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?s=80&d=identicon",
    "web_url": "http://my.gitlab.com/user22",
    "created_at": "2021-09-10T12:48:22.381Z",
    "bio": "",
    "location": null,
    "public_email": "",
    "linkedin": "",
    "twitter": "",
    "website_url": "",
    "organization": null,
    "job_title": "",
    "pronouns": null,
    "bot": false,
    "work_information": null,
    "followers": 0,
    "following": 0,
    "local_time": null,
    "last_sign_in_at": null,
    "confirmed_at": "2021-09-10T12:48:22.330Z",
    "last_activity_on": null,
    "email": "user22@example.org",
    "theme_id": 1,
    "color_scheme_id": 1,
    "projects_limit": 100000,
    "current_sign_in_at": null,
    "identities": [ ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": false,
    "external": false,
    "private_profile": false,
    "commit_email": "user22@example.org",
    "shared_runners_minutes_limit": null,
    "extra_shared_runners_minutes_limit": null
  },
  ...
]

하위 그룹 목록 조회#

그룹에서 볼 수 있는 직계 하위 그룹을 조회합니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

이 목록을 다음과 같이 요청하는 경우:

  • 인증하지 않은 사용자로 요청하면 응답에 공개 그룹만 반환됩니다.
  • 인증한 사용자로 요청하면 응답에 본인이 멤버로 속한 그룹만 반환되며 공개 그룹은 포함되지 않습니다.

파라미터:

Attribute Type Required Description
id integer or string yes 바로 위 상위 그룹의 ID 또는 URL 인코딩된 경로.
skip_groups array of integers no 전달한 그룹 ID를 건너뜁니다.
all_available boolean no 접근 권한이 있는 모든 그룹을 표시합니다(인증된 사용자는 기본값 false, 관리자는 true). owned 및 min_access_level 속성이 우선합니다.
search string no 검색 조건과 일치하는 인가된 그룹 목록을 반환합니다. 하위 그룹의 짧은 경로만 검색하며 전체 경로는 검색하지 않습니다.
order_by string no 그룹을 name, path, id 기준으로 정렬합니다. 기본값은 name 입니다.
sort string no 그룹을 asc 또는 desc 순으로 정렬합니다. 기본값은 asc 입니다.
statistics boolean no 그룹 통계를 포함합니다(관리자 전용).
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용).
owned boolean no 현재 사용자가 명시적으로 소유한 그룹으로 제한합니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 그룹으로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
all_available boolean no true 인 경우 접근 가능한 모든 그룹을 반환합니다. false 인 경우 사용자가 멤버인 그룹만 반환합니다. 기본값은 일반 사용자의 경우 false, 관리자의 경우 true 입니다. 인증되지 않은 요청은 항상 모든 공개 그룹을 반환합니다. owned 및 min_access_level 속성이 우선합니다.
active boolean no 보관되지 않았고 삭제 대상으로 표시되지 않은 그룹으로 제한합니다. 
GET /groups/:id/subgroups

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://gitlab.example.com/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  }
]

GitLab Premium 또는 Ultimate 사용자에게는 wiki_access_level, duo_features_enabled, lock_duo_features_enabled, duo_availability, experiment_features_enabled 속성도 표시됩니다.

하위 그룹 목록 조회#

그룹에서 볼 수 있는 하위 그룹을 조회합니다. 인증 없이 접근하면 공개 그룹만 반환됩니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

파라미터:

Attribute Type Required Description
id integer or string yes 바로 위 상위 그룹의 ID 또는 URL 인코딩된 경로.
skip_groups array of integers no 전달한 그룹 ID를 건너뜁니다.
all_available boolean no true 인 경우 접근 가능한 모든 그룹을 반환합니다. false 인 경우 사용자가 멤버인 그룹만 반환합니다. 기본값은 일반 사용자의 경우 false, 관리자의 경우 true 입니다. 인증되지 않은 요청은 항상 모든 공개 그룹을 반환합니다. owned 및 min_access_level 속성이 우선합니다.
search string no 검색 조건과 일치하는 인가된 그룹 목록을 반환합니다. 하위 그룹의 짧은 경로만 검색하며 전체 경로는 검색하지 않습니다.
order_by string no 그룹을 name, path, id 기준으로 정렬합니다. 기본값은 name 입니다.
sort string no 그룹을 asc 또는 desc 순으로 정렬합니다. 기본값은 asc 입니다.
statistics boolean no 그룹 통계를 포함합니다(관리자 전용).
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용).
owned boolean no 현재 사용자가 명시적으로 소유한 그룹으로 제한합니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 그룹으로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
active boolean no 보관되지 않았고 삭제 대상으로 표시되지 않은 그룹으로 제한합니다. 
GET /groups/:id/descendant_groups

[
  {
    "id": 2,
    "name": "Bar Group",
    "path": "bar",
    "description": "A subgroup of Foo Group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/bar.jpg",
    "web_url": "http://gitlab.example.com/groups/foo/bar",
    "request_access_enabled": false,
    "full_name": "Bar Group",
    "full_path": "foo/bar",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  },
  {
    "id": 3,
    "name": "Baz Group",
    "path": "baz",
    "description": "A subgroup of Bar Group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/baz.jpg",
    "web_url": "http://gitlab.example.com/groups/foo/bar/baz",
    "request_access_enabled": false,
    "full_name": "Baz Group",
    "full_path": "foo/bar/baz",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  }
]

GitLab Premium 또는 Ultimate 사용자에게는 wiki_access_level, duo_features_enabled, lock_duo_features_enabled, duo_availability, experiment_features_enabled 속성도 표시됩니다.

공유된 그룹 목록 조회#

지정한 그룹이 초대받은 그룹을 조회합니다. 인증 없이 접근하면 공개된 공유 그룹만 반환됩니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
skip_groups array of integers no 지정한 그룹 ID를 건너뜁니다.
search string no 검색 조건과 일치하는 인가된 그룹 목록을 반환합니다.
order_by string no 그룹을 name, path, id, similarity 기준으로 정렬합니다. 기본값은 name 입니다.
sort string no 그룹을 asc 또는 desc 순으로 정렬합니다. 기본값은 asc 입니다.
visibility string no 가시성이 public, internal, private 인 그룹으로 제한합니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 그룹으로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용). 
GET /groups/:id/groups/shared

응답 예시:

[
  {
    "id": 101,
    "web_url": "http://gitlab.example.com/groups/some_path",
    "name": "group1",
    "path": "some_path",
    "description": "",
    "visibility": "public",
    "share_with_group_lock": "false",
    "require_two_factor_authentication": "false",
    "two_factor_grace_period": 48,
    "project_creation_level": "maintainer",
    "auto_devops_enabled": "nil",
    "subgroup_creation_level": "maintainer",
    "emails_disabled": "false",
    "emails_enabled": "true",
    "mentions_disabled": "nil",
    "lfs_enabled": "true",
    "math_rendering_limits_enabled": "true",
    "lock_math_rendering_limits_enabled": "false",
    "default_branch": "nil",
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
        "allowed_to_push": [
          {
              "access_level": 30
          }
        ],
        "allow_force_push": "true",
        "allowed_to_merge": [
          {
              "access_level": 30
          }
        ],
        "developer_can_initial_push": "false",
        "code_owner_approval_required": "false"
    },
    "avatar_url": "http://gitlab.example.com/uploads/-/system/group/avatar/101/banana_sample.gif",
    "request_access_enabled": "true",
    "full_name": "group1",
    "full_path": "some_path",
    "created_at": "2024-06-06T09:39:30.056Z",
    "parent_id": "nil",
    "organization_id": 1,
    "shared_runners_setting": "enabled",
    "ldap_cn": "nil",
    "ldap_access": "nil",
    "wiki_access_level": "enabled"
  }
]

초대된 그룹 목록 조회#

그룹에 초대된 그룹을 조회합니다. 인증 없이 접근하면 공개된 초대 그룹만 반환됩니다. 이 엔드포인트는 사용자별(인증된 사용자) 또는 IP 별(인증되지 않은 사용자)로 분당 60회 요청으로 속도가 제한됩니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
search string no 검색 조건과 일치하는 인가된 그룹 목록을 반환합니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 그룹으로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
relation array of strings no 관계(직접 또는 상속)로 그룹을 필터링합니다.
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용). 
GET /groups/:id/invited_groups

응답 예시:

[
  {
    "id": 33,
    "web_url": "http://gitlab.example.com/groups/flightjs",
    "name": "Flightjs",
    "path": "flightjs",
    "description": "Illo dolorum tempore eligendi minima ducimus provident.",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "maintainer",
    "emails_disabled": false,
    "emails_enabled": true,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "math_rendering_limits_enabled": true,
    "lock_math_rendering_limits_enabled": false,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
        {
          "access_level": 40
        }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
        {
          "access_level": 40
        }
      ],
      "developer_can_initial_push": false
    },
    "avatar_url": null,
    "request_access_enabled": true,
    "full_name": "Flightjs",
    "full_path": "flightjs",
    "created_at": "2024-07-09T10:31:08.307Z",
    "parent_id": null,
    "organization_id": 1,
    "shared_runners_setting": "enabled",
    "ldap_cn": null,
    "ldap_access": null,
    "wiki_access_level": "enabled"
  }
]

감사 이벤트 목록 조회#

그룹 감사 이벤트는 그룹 감사 이벤트 API로 조회할 수 있습니다.

그룹 관리#

그룹 생성#

Note

GitLab.com에서는 상위 그룹이 없는 그룹을 만들 때 GitLab UI를 사용해야 합니다. 이 작업에는 API를 사용할 수 없습니다.

새 프로젝트 그룹을 생성합니다. 그룹을 생성할 수 있는 사용자만 사용할 수 있습니다.

POST /groups

파라미터:

Attribute Type Required Description
name string yes 그룹의 이름.
path string yes 그룹의 경로.
auto_devops_enabled boolean no 이 그룹 내 모든 프로젝트에 Auto DevOps 파이프라인을 기본값으로 적용합니다.
avatar mixed no 그룹 아바타로 사용할 이미지 파일.
default_branch string no 그룹 내 프로젝트의 기본 브랜치 이름.
default_branch_protection integer no GitLab 17.0에서 deprecated 처리되었습니다. 대신 default_branch_protection_defaults를 사용합니다.
default_branch_protection_defaults hash no GitLab 17.0에서 도입되었습니다. 사용 가능한 옵션은 default_branch_protection_defaults 옵션을 참고합니다.
description string no 그룹의 설명.
enabled_git_access_protocol string no Git 액세스에 활성화할 프로토콜. 허용되는 값은 ssh, http, 두 프로토콜을 모두 허용하는 all 입니다.
emails_disabled boolean no (GitLab 16.5에서 deprecated 처리되었습니다.) 이메일 알림을 비활성화합니다. 대신 emails_enabled를 사용합니다.
emails_enabled boolean no 이메일 알림을 활성화합니다.
lfs_enabled boolean no 이 그룹 내 프로젝트의 Large File Storage(LFS)를 활성화하거나 비활성화합니다.
mentions_disabled boolean no 그룹이 멘션되는 기능을 비활성화합니다.
organization_id integer no 그룹의 조직 ID.
parent_id integer no 중첩 그룹을 생성할 때 사용할 상위 그룹 ID.
project_creation_level string no Developer가 그룹에서 프로젝트를 생성할 수 있는지 결정합니다. administrator(관리자 모드가 활성화된 사용자), noone(아무도 불가), maintainer(Maintainer 권한을 가진 사용자), developer(Developer 또는 Maintainer 권한을 가진 사용자) 중 하나입니다.
request_access_enabled boolean no 사용자가 멤버 액세스를 요청할 수 있도록 허용합니다.
require_two_factor_authentication boolean no 이 그룹의 모든 사용자에게 2단계 인증 설정을 요구합니다.
share_with_group_lock boolean no 이 그룹 내 프로젝트를 다른 그룹과 공유하지 못하도록 막습니다.
subgroup_creation_level string no 하위 그룹 생성을 허용합니다. owner(Owner 권한을 가진 사용자) 또는 maintainer(Maintainer 권한을 가진 사용자) 중 하나입니다.
two_factor_grace_period integer no 2단계 인증이 강제되기까지의 시간(시간 단위).
visibility string no 그룹의 가시성. private, internal, public 중 하나입니다.
membership_lock boolean no 이 그룹 내 프로젝트에 사용자를 추가할 수 없습니다. Premium 및 Ultimate 전용.
extra_shared_runners_minutes_limit integer no 관리자만 설정할 수 있습니다. 이 그룹의 추가 컴퓨팅 분. GitLab Self-Managed, Premium 및 Ultimate 전용.
shared_runners_minutes_limit integer no 관리자만 설정할 수 있습니다. 이 그룹의 월별 최대 컴퓨팅 분. nil(기본값, 시스템 기본값 상속), 0(무제한), > 0 중 하나입니다. GitLab Self-Managed, Premium 및 Ultimate 전용.
wiki_access_level string no 위키 액세스 수준. disabled, private, enabled 중 하나입니다. Premium 및 Ultimate 전용.
duo_availability string no GitLab Duo 사용 가능 여부 설정. 유효한 값은 default_on, default_off, never_on 입니다. 참고: UI에서 never_on은 "Always Off" 로 표시됩니다.
experiment_features_enabled boolean no 이 그룹의 실험 기능을 활성화합니다.
ai_settings_attributes hash no 이 그룹의 AI 관련 설정. 사용 가능한 옵션은 ai_settings_attributes 옵션을 참고합니다. GitLab Duo 기능이 활성화되어 있어야 합니다.

default_branch_protection 옵션#

default_branch_protection 속성은 다음 표와 같이 Developer 또는 Maintainer 권한을 가진 사용자가 해당 기본 브랜치에 푸시할 수 있는지를 결정합니다.

Value Description
0 보호 없음. Developer 또는 Maintainer 권한을 가진 사용자가 다음을 수행할 수 있습니다.
- 새 커밋 푸시.
- 변경 사항 강제 푸시.
- 브랜치 삭제.
1 부분 보호. Developer 또는 Maintainer 권한을 가진 사용자가 다음을 수행할 수 있습니다.
- 새 커밋 푸시.
2 전체 보호. Maintainer 권한을 가진 사용자만 다음을 수행할 수 있습니다.
- 새 커밋 푸시.
3 푸시 보호. Maintainer 권한을 가진 사용자가 다음을 수행할 수 있습니다.
- 새 커밋 푸시.
- 변경 사항 강제 푸시.
- 머지 리퀘스트 수락.
Developer 권한을 가진 사용자가 다음을 수행할 수 있습니다.
- 머지 리퀘스트 수락.
4 최초 푸시 이후 전체 보호. Developer 권한을 가진 사용자가 다음을 수행할 수 있습니다.
- 빈 리포지터리에 커밋 푸시.
Maintainer 권한을 가진 사용자가 다음을 수행할 수 있습니다.
- 새 커밋 푸시.
- 머지 리퀘스트 수락.

default_branch_protection_defaults 옵션#

히스토리
  • GitLab 17.0에서 도입되었습니다.

default_branch_protection_defaults 속성은 기본 브랜치 보호의 기본값을 설명합니다. 모든 파라미터는 선택 사항입니다.

Key Type Description
allowed_to_push array 푸시가 허용된 액세스 수준의 배열. Developer(30) 또는 Maintainer(40)를 지원합니다.
allow_force_push boolean 푸시 권한이 있는 모든 사용자에게 강제 푸시를 허용합니다.
allowed_to_merge array 머지가 허용된 액세스 수준의 배열. Developer(30) 또는 Maintainer(40)를 지원합니다.
developer_can_initial_push boolean Developer에게 최초 푸시를 허용합니다.
code_owner_approval_required boolean Code Owner 승인을 요구합니다.

하위 그룹 생성#

새 그룹 생성과 비슷합니다. 그룹 목록 조회 호출에서 얻은 parent_id가 필요합니다. 그다음 원하는 값을 입력합니다.

  • subgroup_path
  • subgroup_name
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"path": "<subgroup_path>", "name": "<subgroup_name>", "parent_id": <parent_group_id> }' \
  --url "https://gitlab.example.com/api/v4/groups/"

그룹 삭제 예약#

히스토리
  • GitLab 18.0에서 GitLab Premium에서 GitLab Free로 이동되었습니다.

그룹을 삭제 예약합니다. 그룹은 보존 기간이 끝날 때 삭제됩니다.

  • GitLab.com에서는 그룹이 30일간 보존됩니다.
  • GitLab Self-Managed에서는 보존 기간이 인스턴스 설정으로 제어됩니다.

이 엔드포인트는 이전에 삭제 예약된 하위 그룹을 즉시 삭제할 수도 있습니다.

사전 요구 사항:

  • 관리자이거나 그룹에서 Owner 권한이 있어야 합니다.
DELETE /groups/:id
Attribute Type Required Description
id integer or string Yes 그룹의 ID 또는 URL 인코딩된 경로.
full_path string Conditional 하위 그룹의 전체 경로. 하위 그룹 삭제를 확인하는 데 사용합니다. permanently_remove가 true 이면 이 속성은 필수입니다. 하위 그룹 경로는 그룹 세부 정보에서 확인합니다.
permanently_remove boolean/string No true 이면 이미 삭제 예약된 하위 그룹을 즉시 삭제합니다. 최상위 그룹은 삭제할 수 없습니다.

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

요청 예시:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Accept: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/:id"
Note

구독에 연결된 GitLab.com 그룹은 삭제할 수 없습니다. 먼저 구독을 다른 그룹과 연결해야 합니다.

그룹 영구 삭제#

설정된 보존 기간을 건너뛰고 그룹과 해당 데이터를 영구적으로 삭제합니다.

사전 요구 사항:

  • 관리자이거나 그룹에서 Owner 권한이 있어야 합니다.
DELETE /groups/:id
Attribute Type Required Description
id integer or string Yes 그룹의 ID 또는 URL 인코딩된 경로.
full_path string Yes 삭제 예약 후 변경된 하위 그룹의 전체 경로. permanently_remove가 true 이면 이 속성은 필수입니다. 변경된 전체 경로는 그룹 조회로 확인합니다.
permanently_remove boolean/string Yes true 이면 이미 삭제 예약된 하위 그룹을 영구적으로 삭제합니다. 최상위 그룹은 삭제할 수 없습니다.

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

삭제 예약된 그룹을 영구적으로 삭제하려면 다음을 수행합니다.

  1. API 호출로 그룹을 삭제 예약합니다.
  2. 두 번째 API 호출로 그룹을 삭제합니다.

예시:

# Schedule a group for deletion
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Accept: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/:id"

# Permanently delete a group scheduled for deletion
# Use the modified full_path of the subgroup
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"full_path": "<path-after-soft-delete>", "permanently_remove": "true"}' \
  --url "https://gitlab.example.com/api/v4/groups/:id"

삭제 예약된 그룹 복원#

이전에 삭제 표시된 그룹을 복원합니다.

POST /groups/:id/restore

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.

그룹 보관#

히스토리
  • GitLab 18.0에서 archive_group이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 18.9에서 일반 공급되었습니다. 기능 플래그 archive_group 이 제거되었습니다.

그룹을 보관합니다.

사전 요구 사항:

  • 관리자이거나 그룹에서 Owner 권한이 있어야 합니다.

그룹이 이미 보관된 상태이면 이 엔드포인트는 422 처리 불가 엔티티 오류를 반환합니다.

POST /groups/:id/archive

파라미터:

Attribute Type Required Description
id integer or string yes 인증된 사용자가 소유한 그룹의 ID 또는 URL 인코딩된 경로.

응답 예시:

{
  "id": 96,
  "web_url": "https://gitlab.example.com/groups/test-1",
  "name": "test-1",
  "path": "test-1",
  "description": "",
  "visibility": "public",
  "share_with_group_lock": false,
  "require_two_factor_authentication": false,
  "two_factor_grace_period": 48,
  "project_creation_level": "developer",
  "auto_devops_enabled": null,
  "subgroup_creation_level": "maintainer",
  "emails_disabled": false,
  "emails_enabled": true,
  "mentions_disabled": null,
  "lfs_enabled": true,
  "archived": true,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false,
  "require_sha_for_merge": false,
  "lock_require_sha_for_merge": false,
  "default_branch": null,
  "default_branch_protection": 2,
  "default_branch_protection_defaults": {
    "allowed_to_push": [
      {
        "access_level": 40
      }
    ],
    "allow_force_push": false,
    "allowed_to_merge": [
      {
        "access_level": 40
      }
    ],
    "developer_can_initial_push": false
  },
  "avatar_url": null,
  "request_access_enabled": true,
  "full_name": "test-1",
  "full_path": "test-1",
  "created_at": "2025-03-25T12:05:24.813Z",
  "parent_id": null,
  "organization_id": 1,
  "shared_runners_setting": "enabled",
  "max_artifacts_size": null,
  "ldap_cn": null,
  "ldap_access": null,
  "wiki_access_level": "enabled",
  "shared_with_groups": [],
  "prevent_sharing_groups_outside_hierarchy": false,
  "shared_runners_minutes_limit": null,
  "extra_shared_runners_minutes_limit": null,
  "prevent_forking_outside_group": null,
  "membership_lock": false
}

그룹 보관 해제#

히스토리
  • GitLab 18.0에서 archive_group이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 18.9에서 일반 공급되었습니다. 기능 플래그 archive_group 이 제거되었습니다.

그룹의 보관을 해제합니다.

사전 요구 사항:

  • 관리자이거나 그룹에서 Owner 권한이 있어야 합니다.

그룹이 보관된 상태가 아니면 이 엔드포인트는 422 처리 불가 엔티티 오류를 반환합니다.

POST /groups/:id/unarchive

파라미터:

Attribute Type Required Description
id integer or string yes 인증된 사용자가 소유한 그룹의 ID 또는 URL 인코딩된 경로.

응답 예시:

{
  "id": 96,
  "web_url": "https://gitlab.example.com/groups/test-1",
  "name": "test-1",
  "path": "test-1",
  "description": "",
  "visibility": "public",
  "share_with_group_lock": false,
  "require_two_factor_authentication": false,
  "two_factor_grace_period": 48,
  "project_creation_level": "developer",
  "auto_devops_enabled": null,
  "subgroup_creation_level": "maintainer",
  "emails_disabled": false,
  "emails_enabled": true,
  "mentions_disabled": null,
  "lfs_enabled": true,
  "archived": false,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false,
  "require_sha_for_merge": false,
  "lock_require_sha_for_merge": false,
  "default_branch": null,
  "default_branch_protection": 2,
  "default_branch_protection_defaults": {
    "allowed_to_push": [
      {
        "access_level": 40
      }
    ],
    "allow_force_push": false,
    "allowed_to_merge": [
      {
        "access_level": 40
      }
    ],
    "developer_can_initial_push": false
  },
  "avatar_url": null,
  "request_access_enabled": true,
  "full_name": "test-1",
  "full_path": "test-1",
  "created_at": "2025-03-25T12:05:24.813Z",
  "parent_id": null,
  "organization_id": 1,
  "shared_runners_setting": "enabled",
  "max_artifacts_size": null,
  "ldap_cn": null,
  "ldap_access": null,
  "wiki_access_level": "enabled",
  "shared_with_groups": [],
  "prevent_sharing_groups_outside_hierarchy": false,
  "shared_runners_minutes_limit": null,
  "extra_shared_runners_minutes_limit": null,
  "prevent_forking_outside_group": null,
  "membership_lock": false
}

그룹 이전#

히스토리
  • 비동기 이전이 GitLab 19.0에서 groups_and_projects_async_transfer라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • 비동기 이전이 GitLab 19.4에서 정식 출시되었습니다. 기능 플래그 groups_and_projects_async_transfer가 제거되었습니다.

그룹을 새 상위 그룹으로 이전하거나 하위 그룹을 최상위 그룹으로 전환합니다.

사전 요구 사항:

POST /groups/:id/transfer

파라미터:

Attribute Type Required Description
id integer yes 이전할 그룹의 ID.
group_id integer no 새 상위 그룹의 ID. 지정하지 않으면 그룹이 최상위 그룹으로 전환됩니다.

성공하면 201 Created와 이전 전 상태의 그룹을 반환합니다.

요청 예시:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4/transfer?group_id=7"

이전이 성공했는지 확인하려면 parent_id가 새 상위 그룹의 ID와 일치할 때까지 그룹을 조회합니다. 최상위 그룹의 값은 null입니다.

이전이 실패하면 이전을 요청한 사용자에게 transfer_failed 액션이 있는 할 일 항목이 생성됩니다. 할 일 항목을 가져오려면 모든 할 일 항목 나열을 참고합니다.

그룹 이전 가능한 위치 목록 조회#

지정된 그룹을 이전할 수 있는 모든 상위 그룹을 나열합니다.

GET /groups/:id/transfer_locations
Attribute Type Required Description
id integer or string Yes 이전할 그룹의 ID 또는 URL 인코딩된 경로.
search string No 검색할 특정 그룹의 이름.

요청 예시:

curl --request GET \
    --url "https://gitlab.example.com/api/v4/groups/1/transfer_locations"

응답 예시:

[
  {
    "id": 27,
    "web_url": "https://gitlab.example.com/groups/gitlab",
    "name": "GitLab",
    "avatar_url": null,
    "full_name": "GitLab",
    "full_path": "GitLab"
  },
  {
    "id": 31,
    "web_url": "https://gitlab.example.com/groups/foobar",
    "name": "FooBar",
    "avatar_url": null,
    "full_name": "FooBar",
    "full_path": "FooBar"
  }
]

프로젝트를 그룹으로 이전#

프로젝트를 다른 그룹 네임스페이스로 이전합니다. 또는 프로젝트를 새 네임스페이스로 이전 엔드포인트를 사용할 수도 있습니다.

Note

프로젝트 리포지터리에 태그가 지정된 패키지가 있으면 이전 과정이 실패할 수 있습니다.

사전 요구 사항:

  • 인스턴스의 관리자여야 합니다.
POST /groups/:id/projects/:project_id

파라미터:

Attribute Type Required Description
id integer or string yes 타깃 그룹의 ID 또는 URL 인코딩된 경로.
project_id integer or string yes 프로젝트의 ID 또는 URL 인코딩된 경로. 
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4/projects/56"

그룹 초대#

이 엔드포인트는 그룹 초대에 사용합니다. 자세한 내용은 그룹에 그룹 초대를 참고합니다.

그룹 초대 생성#

지정된 그룹에 타깃 그룹을 추가하는 그룹 초대를 생성합니다.

POST /groups/:id/share

파라미터:

Attribute Type Required Description
id integer or string yes 타깃 그룹의 ID 또는 URL 인코딩된 경로.
group_id integer yes 초대할 그룹의 ID.
group_access integer yes 초대된 그룹에 할당할 기본 access_level. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
expires_at date (ISO 8601) no 그룹 초대가 만료되는 날짜.
member_role_id integer no 초대된 그룹에 할당할 사용자 지정 역할의 ID. 정의한 경우 group_access는 사용자 지정 역할을 만들 때 사용한 기본 역할과 일치해야 합니다.

성공하면 200과 그룹 세부 정보를 반환합니다.

그룹 초대 삭제#

그룹 초대를 삭제하고 지정된 그룹에서 타깃 그룹에 대한 액세스를 제거합니다.

DELETE /groups/:id/share/:group_id
Attribute Type Required Description
id integer or string yes 타깃 그룹의 ID 또는 URL 인코딩된 경로.
group_id integer yes 초대를 취소할 그룹의 ID.

성공하면 204와 빈 콘텐츠를 반환합니다.

그룹 속성 업데이트#

히스토리
  • GitLab 18.0에서 일반 공급되었습니다. 기능 플래그 limit_unique_project_downloads_per_namespace_user가 제거되었습니다.
  • GitLab 18.2에서 use_web_based_commit_signing_enabled라는 기능 플래그와 함께 web_based_commit_signing_enabled가 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 18.10에서 web_based_commit_signing_enabled가 일반 공급되었습니다. 기능 플래그 use_web_based_commit_signing_enabled가 제거되었습니다.
  • GitLab 18.5에서 allow_personal_snippets_setting이라는 기능 플래그와 함께 allow_personal_snippets가 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 18.9에서 allow_personal_snippets가 일반 공급되었습니다. 기능 플래그 allow_personal_snippets_setting 이 제거되었습니다.
  • GitLab 19.0에서 use_built_in_project_templates_enabled라는 기능 플래그와 함께 built_in_project_templates_enabled 및 lock_built_in_project_templates_enabled가 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 19.2에서 built_in_project_templates_enabled 및 lock_built_in_project_templates_enabled가 일반 공급되었습니다. 기능 플래그 use_built_in_project_templates_enabled가 제거되었습니다.
  • GitLab 19.2에서 ai_audit_events_storage_enabled 및 lock_ai_audit_events_storage_enabled가 도입되었습니다.

지정된 그룹의 속성을 업데이트합니다.

사전 요구 사항:

  • 관리자이거나 그룹에서 Owner 권한이 있어야 합니다.
PUT /groups/:id
Attribute Type Required Description
id integer yes 그룹의 ID.
name string no 그룹의 이름.
path string no 그룹의 경로.
auto_devops_enabled boolean no 이 그룹 내 모든 프로젝트에 Auto DevOps 파이프라인을 기본값으로 적용합니다.
avatar mixed no 그룹 아바타용 이미지 파일.
built_in_project_templates_enabled boolean no 사용자가 그룹에서 프로젝트를 생성할 때 기본 제공 프로젝트 템플릿을 활성화합니다. Premium 및 Ultimate 전용. GitLab 19.0에서 use_built_in_project_templates_enabled라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다. GitLab 19.2에서 일반 공급되었습니다. 기능 플래그 use_built_in_project_templates_enabled가 제거되었습니다.
lock_built_in_project_templates_enabled boolean no 모든 하위 그룹에 built_in_project_templates_enabled 설정을 강제합니다. Premium 및 Ultimate 전용. GitLab 19.0에서 use_built_in_project_templates_enabled라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다. GitLab 19.2에서 일반 공급되었습니다. 기능 플래그 use_built_in_project_templates_enabled가 제거되었습니다.
default_branch string no 그룹 프로젝트의 기본 브랜치 이름.
default_branch_protection integer no GitLab 17.0에서 지원 중단되었습니다. 대신 default_branch_protection_defaults를 사용합니다.
default_branch_protection_defaults hash no GitLab 17.0에서 도입되었습니다. 사용 가능한 옵션은 default_branch_protection_defaults 옵션을 참고합니다.
description string no 그룹의 설명.
enabled_git_access_protocol string no Git 액세스에 사용하도록 활성화된 프로토콜. 허용되는 값은 ssh, http, 두 프로토콜을 모두 허용하는 all 입니다.
emails_disabled boolean no (GitLab 16.5에서 지원 중단되었습니다.) 이메일 알림을 비활성화합니다. 대신 emails_enabled를 사용합니다.
emails_enabled boolean no 이메일 알림을 활성화합니다.
lfs_enabled boolean no 이 그룹의 프로젝트에 대해 Large File Storage(LFS)를 활성화하거나 비활성화합니다.
mentions_disabled boolean no 그룹이 멘션되는 기능을 비활성화합니다.
prevent_sharing_groups_outside_hierarchy boolean no 그룹 계층 외부로의 그룹 공유 방지를 참고합니다. 이 속성은 최상위 그룹에서만 사용할 수 있습니다.
project_creation_level string no 개발자가 그룹에서 프로젝트를 생성할 수 있는지 결정합니다. noone(아무도 없음), maintainer(Maintainer 권한이 있는 사용자), developer(Developer 또는 Maintainer 권한이 있는 사용자) 중 하나입니다.
request_access_enabled boolean no 사용자가 멤버 액세스를 요청할 수 있도록 허용합니다.
require_two_factor_authentication boolean no 이 그룹의 모든 사용자에게 2단계 인증 설정을 요구합니다.
shared_runners_setting string no shared_runners_setting 옵션을 참고합니다. 그룹의 하위 그룹과 프로젝트에 대해 인스턴스 러너를 활성화하거나 비활성화합니다.
share_with_group_lock boolean no 이 그룹 내에서 프로젝트를 다른 그룹과 공유하지 못하도록 합니다.
step_up_auth_required_oauth_provider string no 단계 상승 인증에 필요한 OAuth 공급자. 비활성화하려면 빈 문자열을 전달합니다. GitLab 18.4에서 도입되었습니다. omniauth_step_up_auth_for_namespace 기능 플래그가 활성화된 경우 사용할 수 있습니다.
subgroup_creation_level string no 하위 그룹 생성이 허용되는 대상. owner(Owner 권한이 있는 사용자) 또는 maintainer(Maintainer 권한이 있는 사용자) 중 하나입니다.
two_factor_grace_period integer no 2단계 인증이 강제되기까지의 시간(시간 단위).
visibility string no 그룹의 공개 수준. private, internal, public 중 하나입니다.
extra_shared_runners_minutes_limit integer no 관리자만 설정할 수 있습니다. 이 그룹의 추가 컴퓨팅 분. GitLab Self-Managed, Premium 및 Ultimate 전용.
file_template_project_id integer no 사용자 지정 파일 템플릿을 불러올 프로젝트의 ID. Premium 및 Ultimate 전용.
membership_lock boolean no 이 그룹의 프로젝트에 사용자를 추가할 수 없습니다. Premium 및 Ultimate 전용.
prevent_forking_outside_group boolean no 활성화하면 사용자가 이 그룹의 프로젝트를 외부 네임스페이스로 포크할 수 없습니다. Premium 및 Ultimate 전용.
shared_runners_minutes_limit integer no 관리자만 설정할 수 있습니다. 이 그룹의 월간 최대 컴퓨팅 분. nil(기본값, 시스템 기본값 상속), 0(무제한) 또는 > 0 일 수 있습니다. GitLab Self-Managed, Premium 및 Ultimate 전용.
unique_project_download_limit integer no 사용자가 차단되기 전까지 지정된 기간 동안 다운로드할 수 있는 고유 프로젝트의 최대 수. 최상위 그룹에서만 사용할 수 있습니다. 기본값: 0, 최댓값: 10,000. Ultimate 전용.
unique_project_download_limit_interval_in_seconds integer no 사용자가 차단되기 전까지 최대 개수의 프로젝트를 다운로드할 수 있는 기간. 최상위 그룹에서만 사용할 수 있습니다. 기본값: 0, 최댓값: 864,000초(10일). Ultimate 전용.
unique_project_download_limit_allowlist array of strings no 고유 프로젝트 다운로드 제한에서 제외되는 사용자 이름 목록. 최상위 그룹에서만 사용할 수 있습니다. 기본값: [], 최댓값: 사용자 이름 100개. Ultimate 전용.
unique_project_download_limit_alertlist array of integers no 고유 프로젝트 다운로드 제한을 초과했을 때 이메일을 받는 사용자 ID 목록. 최상위 그룹에서만 사용할 수 있습니다. 기본값: [], 최댓값: 사용자 ID 100개. Ultimate 전용.
auto_ban_user_on_excessive_projects_download boolean no 활성화하면 사용자가 unique_project_download_limit 및 unique_project_download_limit_interval_in_seconds로 지정한 최대 고유 프로젝트 수보다 많이 다운로드할 때 그룹에서 자동으로 차단됩니다. Ultimate 전용.
ip_restriction_ranges string no 그룹 액세스를 제한할 IP 주소 또는 서브넷 마스크의 쉼표로 구분된 목록. Premium 및 Ultimate 전용.
allowed_email_domains_list string no 그룹 액세스를 허용할 이메일 주소 도메인의 쉼표로 구분된 목록. 17.4에서 도입되었습니다. GitLab Premium 및 Ultimate 전용.
wiki_access_level string no 위키 액세스 수준. disabled, private, enabled 중 하나입니다. Premium 및 Ultimate 전용.
duo_availability string no GitLab Duo 가용성 설정. 유효한 값은 default_on, default_off, never_on 입니다. 참고: UI에서 never_on은 "Always Off" 로 표시됩니다.
experiment_features_enabled boolean no 이 그룹에 대해 실험 기능을 활성화합니다.
ai_settings_attributes hash no 이 그룹의 AI 관련 설정. 사용 가능한 옵션은 ai_settings_attributes 옵션을 참고합니다. GitLab Duo 기능이 활성화되어 있어야 합니다.
math_rendering_limits_enabled boolean no 이 그룹에 수식 렌더링 제한이 사용되는지 여부를 나타냅니다.
lock_math_rendering_limits_enabled boolean no 모든 하위 그룹에 대해 수식 렌더링 제한이 잠겨 있는지 여부를 나타냅니다.
require_sha_for_merge boolean no 이 그룹의 머지 리퀘스트가 머지 리퀘스트 병합 엔드포인트 호출에 유효한 커밋 SHA를 요구하는지 여부를 나타냅니다. GitLab 19.5에서 도입되었습니다.
lock_require_sha_for_merge boolean no 모든 하위 그룹에 require_sha_for_merge 설정을 강제합니다. GitLab 19.5에서 도입되었습니다.
duo_features_enabled boolean no 이 그룹에 대해 GitLab Duo 기능이 활성화되어 있는지 여부를 나타냅니다. GitLab Self-Managed, Premium 및 Ultimate 전용.
lock_duo_features_enabled boolean no GitLab Duo 기능 활성화 설정이 모든 하위 그룹에 강제되는지 여부를 나타냅니다. GitLab Self-Managed, Premium 및 Ultimate 전용.
ai_audit_events_storage_enabled boolean no 그룹에 대해 AI 감사 이벤트가 저장되는지 여부를 나타냅니다. GitLab 19.2에서 도입되었습니다. Premium 및 Ultimate 전용.
lock_ai_audit_events_storage_enabled boolean no AI 감사 이벤트 저장 설정이 모든 하위 그룹과 프로젝트에 강제되는지 여부를 나타냅니다. GitLab 19.2에서 도입되었습니다. Premium 및 Ultimate 전용.
max_artifacts_size integer No 개별 job 아티팩트의 최대 파일 크기(메가바이트).
web_based_commit_signing_enabled boolean No GitLab UI에서 생성한 커밋에 대해 웹 기반 커밋 서명을 활성화합니다. GitLab.com의 최상위 그룹에서만 사용할 수 있습니다. 그룹에 대해 활성화하면 그룹의 모든 프로젝트에 적용됩니다.
only_allow_merge_if_pipeline_succeeds boolean no 파이프라인이 성공한 경우에만 머지 리퀘스트 머지를 허용합니다. 그룹에 대해 활성화하면 그룹의 모든 프로젝트에 적용됩니다. Premium 및 Ultimate 전용.
allow_merge_on_skipped_pipeline boolean no 파이프라인을 건너뛴 경우에도 머지 리퀘스트 머지를 허용합니다. only_allow_merge_if_pipeline_succeeds가 true 인 경우에만 적용됩니다. Premium 및 Ultimate 전용.

| only_allow_merge_if_all_discussions_are_resolved | boolean | no | 모든 토론이 해결된 경우에만 머지 리퀘스트 머지를 허용합니다. 그룹에 대해 활성화하면 그룹의 모든 프로젝트에 적용됩니다. Premium 및 Ultimate 전용. | | allow_personal_snippets | boolean | no | 이 그룹의 엔터프라이즈 사용자가 개인 스니펫을 생성할 수 있도록 허용합니다. 비활성화하면 엔터프라이즈 사용자는 개인 네임스페이스에서 스니펫을 생성할 수 없습니다. |

Note

응답의 projects 및 shared_projects 속성은 지원이 중단되었으며 API v5에서 제거될 예정입니다. 그룹 내 모든 프로젝트의 세부 정보를 가져오려면 그룹의 프로젝트 목록 조회 또는 그룹의 공유 프로젝트 목록 조회 엔드포인트를 사용합니다.

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5?name=Experimental"

이 엔드포인트는 최대 100개의 프로젝트와 공유 프로젝트를 반환합니다. 그룹 내 모든 프로젝트의 세부 정보를 가져오려면 그룹의 프로젝트 목록 조회 엔드포인트를 대신 사용합니다.

응답 예시:

{
  "id": 5,
  "name": "Experimental",
  "path": "h5bp",
  "description": "foo",
  "visibility": "internal",
  "avatar_url": null,
  "web_url": "http://gitlab.example.com/groups/h5bp",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Foobar Group",
  "full_path": "h5bp",
  "file_template_project_id": 1,
  "parent_id": null,
  "enabled_git_access_protocol": "all",
  "created_at": "2020-01-15T12:36:29.590Z",
  "prevent_sharing_groups_outside_hierarchy": false,
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": false,
  "only_allow_merge_if_all_discussions_are_resolved": false,
  "allow_personal_snippets": true,
  "projects": [ // Deprecated and will be removed in API v5
    {
      "id": 9,
      "description": "foo",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "public": false,
      "archived": false,
      "visibility": "internal",
      "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
      "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
      "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "Experimental / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": true,
      "created_at": "2016-04-05T21:40:50.169Z",
      "last_activity_at": "2016-04-06T16:52:08.432Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "Experimental",
        "path": "h5bp",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 1,
      "forks_count": 0,
      "open_issues_count": 3,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    }
  ],
  "ip_restriction_ranges": null,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false,
  "require_sha_for_merge": false,
  "lock_require_sha_for_merge": false
}

prevent_sharing_groups_outside_hierarchy 속성은 최상위 그룹에 대해서만 응답에 포함됩니다.

GitLab Premium 또는 Ultimate 사용자에게는 wiki_access_level, duo_features_enabled, lock_duo_features_enabled, duo_availability, experiment_features_enabled 속성도 함께 표시됩니다.

shared_runners_setting 옵션#

shared_runners_setting 속성은 그룹의 하위 그룹과 프로젝트에 대해 인스턴스 러너가 활성화되는지 여부를 결정합니다.

Value Description
enabled 이 그룹의 모든 프로젝트와 하위 그룹에 대해 인스턴스 러너를 활성화합니다.
disabled_and_overridable 이 그룹의 모든 프로젝트와 하위 그룹에 대해 인스턴스 러너를 비활성화하지만, 하위 그룹이 이 설정을 재정의할 수 있도록 허용합니다.
disabled_and_unoverridable 이 그룹의 모든 프로젝트와 하위 그룹에 대해 인스턴스 러너를 비활성화하며, 하위 그룹이 이 설정을 재정의하지 못하도록 합니다.
disabled_with_override (지원 중단. disabled_and_overridable을 사용합니다.) 이 그룹의 모든 프로젝트와 하위 그룹에 대해 인스턴스 러너를 비활성화하지만, 하위 그룹이 이 설정을 재정의할 수 있도록 허용합니다.

ai_settings_attributes 옵션#

히스토리
  • GitLab 18.1에서 duo_workflow_mcp_enabled가 도입되었습니다.
  • GitLab 18.6에서 foundational_agents_default_enabled가 도입되었습니다.
  • GitLab 18.7에서 duo_agent_platform_enabled가 도입되었습니다.
  • GitLab 18.7에서 minimum_access_level_execute, minimum_access_level_execute_async, minimum_access_level_manage, minimum_access_level_enable_on_projects가 도입되었습니다.
  • GitLab 18.8에서 prompt_injection_protection_level 이 도입되었습니다.
  • GitLab 18.9에서 ai_usage_data_collection_enabled가 도입되었습니다.
  • GitLab 19.0에서 include_recommended_allowed, allow_all_unix_sockets, allow_project_extension 이 도입되었습니다.
  • GitLab 19.0에서 ai_catalog_restricted_to_group_hierarchy가 도입되었습니다.
  • GitLab 19.4에서 web_search_enabled가 도입되었습니다.

ai_settings_attributes 해시는 그룹의 AI 관련 설정을 구성합니다. 모든 속성은 선택 사항입니다.

Attribute Type Description
ai_catalog_restricted_to_group_hierarchy boolean true 인 경우 AI 카탈로그를 이 최상위 그룹 계층의 항목으로 제한합니다. 최상위 그룹에서만 설정할 수 있습니다. Premium 및 Ultimate 전용.
ai_usage_data_collection_enabled boolean true 인 경우 이 그룹에 대해 AI 사용 데이터 수집을 활성화합니다. GitLab.com 전용.
allow_all_unix_sockets boolean true 인 경우 GitLab Duo Agent Platform에 대해 모든 Unix 소켓을 허용합니다.
allow_project_extension boolean true 인 경우 프로젝트가 GitLab Duo Agent Platform의 네트워크 액세스 도메인 허용 목록을 확장할 수 있습니다.
duo_agent_platform_enabled boolean true 인 경우 이 그룹에 대해 GitLab Duo Agent Platform 기능을 활성화합니다. Premium 및 Ultimate. GitLab Credits가 있는 GitLab.com의 Free 등급에서도 사용 가능.
duo_workflow_mcp_enabled boolean true 인 경우 GitLab Duo Agent Platform에 대한 MCP 지원을 활성화합니다. Premium 및 Ultimate. GitLab Credits가 있는 GitLab.com의 Free 등급에서도 사용 가능.
foundational_agents_default_enabled boolean true 인 경우 이 그룹에 대해 새로운 파운데이셔널 에이전트가 기본적으로 활성화됩니다. Premium 및 Ultimate. GitLab Credits가 있는 GitLab.com의 Free 등급에서도 사용 가능.
include_recommended_allowed boolean true 인 경우 GitLab Duo Agent Platform의 네트워크 액세스 허용 목록에 권장 도메인을 포함합니다.
minimum_access_level_enable_on_projects integer 프로젝트에서 GitLab Duo Agent Platform을 활성화하는 데 필요한 최소 액세스 수준. 유효한 값: 30(Developer), 40(Maintainer), 50(Owner). dap_group_customizable_permissions 기능 플래그가 활성화된 경우 사용할 수 있습니다.
minimum_access_level_execute integer 사용자가 GitLab Duo Agent Platform 기능을 사용하는 데 필요한 최소 액세스 수준. 유효한 값: 10(Guest), 15(Planner), 20(Reporter), 30(Developer), 40(Maintainer), 50(Owner). dap_group_customizable_permissions 기능 플래그가 활성화된 경우 사용할 수 있습니다.
minimum_access_level_execute_async integer CI/CD에서 GitLab Duo Agent Platform 기능을 실행하는 데 필요한 최소 액세스 수준. 유효한 값: 30(Developer), 40(Maintainer), 50(Owner). dap_group_customizable_permissions 기능 플래그가 활성화된 경우 사용할 수 있습니다.
minimum_access_level_manage integer GitLab Duo Agent Platform을 관리하는 데 필요한 최소 액세스 수준. 유효한 값: 30(Developer), 40(Maintainer), 50(Owner). dap_group_customizable_permissions 기능 플래그가 활성화된 경우 사용할 수 있습니다.
prompt_injection_protection_level string 프롬프트 인젝션 보호 수준. 유효한 값: no_checks, log_only, interrupt.
web_search_enabled boolean true 인 경우 이 그룹의 GitLab Duo Chat에서 웹 검색을 활성화합니다. 최상위 그룹에서만 설정할 수 있습니다.

그룹 아바타 업데이트#

그룹 아바타를 업데이트합니다.

그룹 아바타 다운로드#

그룹 아바타를 가져옵니다. 그룹이 공개적으로 접근 가능한 경우 이 엔드포인트는 인증 없이도 접근할 수 있습니다.

GET /groups/:id/avatar
Attribute Type Required Description
id integer or string yes 그룹의 ID.

예시:

curl --request GET \
  --header "PRIVATE-TOKEN: $GITLAB_LOCAL_TOKEN" \
  --remote-header-name \
  --remote-name \
  --url "https://gitlab.example.com/api/v4/groups/4/avatar"

그룹 아바타 업로드#

파일 시스템에서 아바타 파일을 업로드하려면 --form 인수를 사용합니다. 이렇게 하면 curl 이 Content-Type: multipart/form-data 헤더를 사용해 데이터를 전송합니다. file= 파라미터는 파일 시스템의 파일을 가리켜야 하며 앞에 @를 붙여야 합니다. 예시:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "avatar=@/tmp/example.png" \
  --url "https://gitlab.example.com/api/v4/groups/22"

그룹 아바타 제거#

그룹 아바타를 제거하려면 avatar 속성에 빈 값을 사용합니다.

요청 예시:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "avatar=" \
  --url "https://gitlab.example.com/api/v4/groups/22"

그룹과 LDAP 동기화#

지정된 그룹을 연결된 LDAP 그룹과 동기화합니다.

사전 요구 사항:

  • 관리자이거나 그룹에서 Owner 권한이 있어야 합니다.
POST /groups/:id/ldap_sync
Attribute Type Required Description
id integer or string Yes 그룹의 ID 또는 URL 인코딩된 경로.

자격증명 인벤토리 관리#

히스토리
  • GitLab 18.6에서 manage_pat_by_group_owners_ready라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 18.7에서 일반 공급되었습니다. 기능 플래그 manage_pat_by_group_owners_ready가 제거되었습니다.

GitLab.com의 엔터프라이즈 사용자 자격 증명을 조회, 취소, 교체합니다.

사전 요구 사항:

  • 그룹에서 Owner 권한이 있어야 합니다.

그룹의 전체 개인 액세스 토큰 목록 조회#

히스토리
  • GitLab 19.4에서 응답의 last_used_ips가 도입되었습니다.

최상위 그룹의 엔터프라이즈 사용자와 연결된 모든 개인 액세스 토큰을 나열합니다.

GET /groups/:id/manage/personal_access_tokens
Attribute Type Required Description
id integer or string Yes 그룹의 ID 또는 URL 인코딩된 경로.
created_after datetime (ISO 8601) No 정의한 경우 지정된 시간 이후에 생성된 토큰을 반환합니다.
created_before datetime (ISO 8601) No 정의한 경우 지정된 시간 이전에 생성된 토큰을 반환합니다.
last_used_after datetime (ISO 8601) No 정의한 경우 지정된 시간 이후에 마지막으로 사용된 토큰을 반환합니다.
last_used_before datetime (ISO 8601) No 정의한 경우 지정된 시간 이전에 마지막으로 사용된 토큰을 반환합니다.
revoked boolean No true 이면 취소된 토큰만 반환합니다.
search string No 정의한 경우 이름에 지정된 값이 포함된 토큰을 반환합니다.
state string No 정의한 경우 지정된 상태의 토큰을 반환합니다. 가능한 값: active, inactive.
sort string No 정의한 경우 지정된 값으로 결과를 정렬합니다. 가능한 값: created_asc, created_desc, expires_asc, expires_desc, last_used_asc, last_used_desc, name_asc, name_desc.

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <group_owner_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/personal_access_tokens"

응답 예시:

[
  {
    "id": 1,
    "name": "Test Token",
    "revoked": false,
    "created_at": "2020-07-23T14:31:47.729Z",
    "description": "Test Token description",
    "scopes": [
        "api"
    ],
    "user_id": 3,
    "last_used_at": "2021-10-06T17:58:37.550Z",
    "last_used_ips": ["192.0.2.10"],
    "active": true,
    "expires_at": "2025-11-08"
  }
]

그룹의 전체 그룹 및 프로젝트 액세스 토큰 목록 조회#

최상위 그룹과 연결된 모든 그룹 및 프로젝트 액세스 토큰을 나열합니다.

GET /groups/:id/manage/resource_access_tokens
Attribute Type Required Description
id integer or string Yes 그룹의 ID 또는 URL 인코딩된 경로.
created_after datetime (ISO 8601) No 정의한 경우 지정된 시간 이후에 생성된 토큰을 반환합니다.
created_before datetime (ISO 8601) No 정의한 경우 지정된 시간 이전에 생성된 토큰을 반환합니다.
last_used_after datetime (ISO 8601) No 정의한 경우 지정된 시간 이후에 마지막으로 사용된 토큰을 반환합니다.
last_used_before datetime (ISO 8601) No 정의한 경우 지정된 시간 이전에 마지막으로 사용된 토큰을 반환합니다.
revoked boolean No true 이면 취소된 토큰만 반환합니다.
search string No 정의한 경우 이름에 지정된 값이 포함된 토큰을 반환합니다.
state string No 정의한 경우 지정된 상태의 토큰을 반환합니다. 가능한 값: active, inactive.
sort string No 정의한 경우 지정된 값으로 결과를 정렬합니다. 가능한 값: created_asc, created_desc, expires_asc, expires_desc, last_used_asc, last_used_desc, name_asc, name_desc.

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <group_owner_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/resource_access_tokens"

응답 예시:

[
  {
    "id": 12767703,
    "name": "Test Group Token",
    "revoked": false,
    "created_at": "2025-01-07T00:25:02.128Z",
    "description": "",
    "scopes": [
        "read_registry"
    ],
    "user_id": 25365147,
    "last_used_at": null,
    "active": true,
    "expires_at": "2025-06-19",
    "access_level": 10,
    "resource_type": "group",
    "resource_id": 77449520
  }
]

그룹의 전체 SSH 키 목록 조회#

최상위 그룹의 엔터프라이즈 사용자와 연결된 모든 SSH 공개 키를 나열합니다.

GET /groups/:id/manage/ssh_keys
Attribute Type Required Description
id integer or string Yes 그룹의 ID 또는 URL 인코딩된 경로.
created_after datetime (ISO 8601) No 정의한 경우 지정된 시간 이후에 생성된 SSH 키를 반환합니다.
created_before datetime (ISO 8601) No 정의한 경우 지정된 시간 이전에 생성된 SSH 키를 반환합니다.
expires_before datetime (ISO 8601) No 정의한 경우 지정된 시간 이전에 만료되는 SSH 키를 반환합니다.
expires_after datetime (ISO 8601) No 정의한 경우 지정된 시간 이후에 만료되는 SSH 키를 반환합니다. 
curl --request GET \
  --header "PRIVATE-TOKEN: <group_owner_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/ssh_keys"

응답 예시:

[
  {
    "id":3,
    "title":"Sample key 3",
    "created_at":"2024-12-23T05:40:11.891Z",
    "expires_at":null,
    "last_used_at":"2024-12-23T05:40:11.891Z",
    "usage_type":"auth_and_signing",
    "user_id":3
  }
]

엔터프라이즈 사용자의 개인 액세스 토큰 취소#

엔터프라이즈 사용자의 지정된 개인 액세스 토큰을 취소합니다.

DELETE groups/:id/manage/personal_access_tokens/:id
Attribute Type Required Description
id integer or string Yes 개인 액세스 토큰의 ID 또는 키워드 self. 
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/personal_access_tokens/<personal_access_token_id>"

성공하면 204: No Content를 반환합니다.

그 밖에 가능한 응답:

  • 취소에 실패한 경우 400: Bad Request.
  • 액세스 토큰이 유효하지 않은 경우 401: Unauthorized.
  • 액세스 토큰에 필요한 권한이 없는 경우 403: Forbidden.

엔터프라이즈 사용자의 그룹 또는 프로젝트 액세스 토큰 취소#

최상위 그룹과 연결된 엔터프라이즈 사용자의 지정된 그룹 또는 프로젝트 액세스 토큰을 취소합니다.

DELETE groups/:id/manage/resource_access_tokens/:id
Attribute Type Required Description
id integer or string Yes 리소스 액세스 토큰의 ID 또는 키워드 self. 
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/resource_access_tokens/<personal_access_token_id>"

성공하면 204: No Content를 반환합니다.

그 밖에 가능한 응답:

  • 취소에 실패한 경우 400: Bad Request.
  • 액세스 토큰이 유효하지 않은 경우 401: Unauthorized.
  • 액세스 토큰에 필요한 권한이 없는 경우 403: Forbidden.

엔터프라이즈 사용자의 SSH 키 삭제#

최상위 그룹과 연결된 엔터프라이즈 사용자의 지정된 SSH 공개 키를 삭제합니다.

DELETE /groups/:id/manage/ssh_keys/:key_id

지원되는 속성:

Attribute Type Required Description
key_id integer Yes 기존 키의 ID.

성공하면 204: No Content를 반환합니다.

그 밖에 가능한 응답:

  • SSH 키가 삭제되지 않은 경우 400: Bad Request.
  • SSH 키가 유효하지 않은 경우 401: Unauthorized.
  • 사용자에게 필요한 권한이 없는 경우 403: Forbidden.

엔터프라이즈 사용자의 개인 액세스 토큰 교체#

히스토리
  • GitLab 19.4에서 응답의 last_used_ips가 도입되었습니다.
  • GitLab 19.5에서 응답의 granular_scopes가 도입되었습니다.

최상위 그룹과 연결된 엔터프라이즈 사용자의 지정된 개인 액세스 토큰을 교체합니다. 이전 토큰은 취소되고 1주일 후에 만료되는 새 토큰이 생성됩니다.

POST groups/:id/manage/personal_access_tokens/:id/rotate
Attribute Type Required Description
id integer or string Yes 개인 액세스 토큰의 ID 또는 키워드 self.
expires_at date No ISO 형식(YYYY-MM-DD)으로 지정하는 액세스 토큰의 만료 날짜. 교체 날짜로부터 1년 이내여야 합니다. 정의하지 않으면 토큰은 1주일 후에 만료됩니다. 
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/manage/personal_access_tokens/<personal_access_token_id>/rotate"

응답 예시:

{
    "id": 42,
    "name": "Rotated Token",
    "revoked": false,
    "created_at": "2023-08-01T15:00:00.000Z",
    "description": "Test Token description",
    "scopes": ["api"],
    "user_id": 1337,
    "last_used_at": null,
    "last_used_ips": [],
    "active": true,
    "expires_at": "2023-08-15",
    "token": "s3cr3t"
}
Note

세분화된 범위가 있는 토큰을 교체하면 새 토큰의 granular_scopes 속성에 해당 범위가 반환됩니다. 자세한 내용은 모든 개인 액세스 토큰 나열을 참고합니다.

성공하면 200: OK를 반환합니다.

그 밖에 가능한 응답:

  • 교체에 실패한 경우 400: Bad Request.
  • 다음 조건 중 하나라도 해당하면 401: Unauthorized.
    • 토큰이 존재하지 않습니다.
    • 토큰이 만료되었습니다.
    • 토큰이 취소되었습니다.
    • 지정된 토큰에 대한 액세스 권한이 없습니다.
  • 토큰이 자체 교체를 허용하지 않는 경우 403: Forbidden.
  • 사용자에게 Owner 권한이 있지만 토큰이 존재하지 않는 경우 404: Not Found.
  • 토큰이 개인 액세스 토큰이 아닌 경우 405: Method Not Allowed.

엔터프라이즈 사용자의 그룹 또는 프로젝트 액세스 토큰 교체#

최상위 그룹과 연결된 엔터프라이즈 사용자의 지정된 그룹 또는 프로젝트 액세스 토큰을 교체합니다. 이전 토큰은 취소되고 1주일 후에 만료되는 새 토큰이 생성됩니다.

POST groups/:id/manage/resource_access_tokens/:id/rotate
Attribute Type Required Description
id integer or string Yes 개인 액세스 토큰의 ID 또는 키워드 self.
expires_at date No ISO 형식(YYYY-MM-DD)으로 지정하는 액세스 토큰의 만료 날짜. 교체 날짜로부터 1년 이내여야 합니다. 정의하지 않으면 토큰은 1주일 후에 만료됩니다. 
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/manage/resource_access_tokens/<resource_access_token_id>/rotate"

응답 예시:

{
    "id": 42,
    "name": "Rotated Token",
    "revoked": false,
    "created_at": "2023-08-01T15:00:00.000Z",
    "description": "Test Token description",
    "scopes": ["api"],
    "user_id": 1337,
    "last_used_at": null,
    "active": true,
    "expires_at": "2023-08-15",
    "token": "s3cr3t"
}

성공하면 200: OK를 반환합니다.

그 밖에 가능한 응답:

  • 교체에 실패한 경우 400: Bad Request.
  • 다음 조건 중 하나라도 해당하면 401: Unauthorized.
    • 토큰이 존재하지 않습니다.
    • 토큰이 만료되었습니다.
    • 토큰이 취소되었습니다.
    • 지정된 토큰에 대한 액세스 권한이 없습니다.
  • 토큰이 자체 교체를 허용하지 않거나 봇 사용자 토큰이 아닌 경우 403: Forbidden.
  • 사용자에게 Owner 권한이 있지만 토큰이 존재하지 않는 경우 404: Not Found.

Footnotes

  1. search URL 파라미터로 계산한 유사도 점수를 기준으로 결과를 정렬합니다. order_by=similarity를 사용하면 sort 파라미터는 무시됩니다. search 파라미터를 제공하지 않으면 API는 name 기준으로 정렬한 프로젝트를 반환합니다. ↩

그룹 API

GitLab v19.5
Tier: Premium, Ultimate
Offering: GitLab.com
원문 보기

요약

이 API로 GitLab 그룹을 조회하고 관리합니다. 엔드포인트 응답은 그룹에서 인증된 사용자의 권한에 따라 달라질 수 있습니다. 그룹의 세부 정보를 조회합니다. 응답의 projects 및 shared_projects 속성은 deprecated 처리되었으며 API v5에서 제거될 예정입니다.

이 API로 GitLab 그룹을 조회하고 관리합니다. 자세한 내용은 그룹을 참고합니다.

엔드포인트 응답은 그룹에서 인증된 사용자의 권한에 따라 달라질 수 있습니다.

그룹 조회#

그룹의 세부 정보를 조회합니다. 그룹이 공개적으로 접근 가능하면 이 엔드포인트는 인증 없이도 접근할 수 있습니다. 요청한 사용자가 관리자이면 추가 정보가 반환됩니다. 인증한 경우, 사용자가 관리자이거나 Owner 권한을 가지고 있으면 해당 그룹의 runners_token과 enabled_git_access_protocol도 반환합니다.

GET /groups/:id

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용).
with_projects boolean no 지정한 그룹에 속한 프로젝트의 세부 정보를 포함합니다(기본값 true). (Deprecated 처리되었으며 API v5에서 제거될 예정입니다. 그룹 내 모든 프로젝트의 세부 정보를 가져오려면 그룹 프로젝트 목록 조회 엔드포인트를 사용합니다.)
Note

응답의 projects 및 shared_projects 속성은 deprecated 처리되었으며 API v5에서 제거될 예정입니다. 그룹 내 모든 프로젝트의 세부 정보를 가져오려면 그룹 프로젝트 목록 조회 또는 그룹 공유 프로젝트 목록 조회 엔드포인트를 사용합니다.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4"

이 엔드포인트는 최대 100개의 프로젝트와 공유 프로젝트를 반환합니다. 그룹 내 모든 프로젝트의 세부 정보를 가져오려면 그룹 프로젝트 목록 조회 엔드포인트를 사용합니다.

응답 예시:

{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "visibility": "public",
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Twitter",
  "full_path": "twitter",
  "runners_token": "ba324ca7b1c77fc20bb9",
  "file_template_project_id": 1,
  "parent_id": null,
  "enabled_git_access_protocol": "all",
  "created_at": "2020-01-15T12:36:29.590Z",
  "shared_with_groups": [
    {
      "group_id": 28,
      "group_name": "H5bp",
      "group_full_path": "h5bp",
      "group_access_level": 20,
      "expires_at": null
    }
  ],
  "prevent_sharing_groups_outside_hierarchy": false,
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": false,
  "only_allow_merge_if_all_discussions_are_resolved": false,
  "projects": [ // Deprecated and will be removed in API v5
    {
      "id": 7,
      "description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "public",
      "ssh_url_to_repo": "git@gitlab.example.com:twitter/typeahead-js.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/typeahead-js.git",
      "web_url": "https://gitlab.example.com/twitter/typeahead-js",
      "name": "Typeahead.Js",
      "name_with_namespace": "Twitter / Typeahead.Js",
      "path": "typeahead-js",
      "path_with_namespace": "twitter/typeahead-js",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:25.578Z",
      "last_activity_at": "2016-06-17T07:47:25.881Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 3,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    },
    {
      "id": 6,
      "description": "Aspernatur omnis repudiandae qui voluptatibus eaque.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "internal",
      "ssh_url_to_repo": "git@gitlab.example.com:twitter/flight.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/flight.git",
      "web_url": "https://gitlab.example.com/twitter/flight",
      "name": "Flight",
      "name_with_namespace": "Twitter / Flight",
      "path": "flight",
      "path_with_namespace": "twitter/flight",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:24.661Z",
      "last_activity_at": "2016-06-17T07:47:24.838Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 8,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    }
  ],
  "shared_projects": [ // Deprecated and will be removed in API v5
    {
      "id": 8,
      "description": "Velit eveniet provident fugiat saepe eligendi autem.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "private",
      "ssh_url_to_repo": "git@gitlab.example.com:h5bp/html5-boilerplate.git",
      "http_url_to_repo": "https://gitlab.example.com/h5bp/html5-boilerplate.git",
      "web_url": "https://gitlab.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "H5bp / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:27.089Z",
      "last_activity_at": "2016-06-17T07:47:27.310Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "H5bp",
        "path": "h5bp",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 4,
      "public_jobs": true,
      "shared_with_groups": [
        {
          "group_id": 4,
          "group_name": "Twitter",
          "group_full_path": "twitter",
          "group_access_level": 30,
          "expires_at": null
        },
        {
          "group_id": 3,
          "group_name": "Gitlab Org",
          "group_full_path": "gitlab-org",
          "group_access_level": 10,
          "expires_at": "2018-08-14"
        }
      ]
    }
  ],
  "ip_restriction_ranges": null,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false,
  "require_sha_for_merge": false,
  "lock_require_sha_for_merge": false
}

prevent_sharing_groups_outside_hierarchy 속성은 최상위 그룹에만 존재합니다.

GitLab Premium 또는 Ultimate 사용자에게는 다음 속성도 표시됩니다.

  • shared_runners_minutes_limit
  • extra_shared_runners_minutes_limit
  • marked_for_deletion_on
  • membership_lock
  • wiki_access_level
  • duo_features_enabled
  • lock_duo_features_enabled
  • duo_availability
  • experiment_features_enabled

추가 응답 속성:

{
  "id": 4,
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  "marked_for_deletion_on": "2020-04-03",
  "membership_lock": false,
  "wiki_access_level": "disabled",
  "duo_features_enabled": true,
  "lock_duo_features_enabled": false,
  "duo_availability": "default_on",
  "experiment_features_enabled": false,
  "ai_settings": {
    "duo_agent_platform_enabled": true,
    "duo_workflow_mcp_enabled": false,
    "foundational_agents_default_enabled": true,
    "ai_catalog_restricted_to_group_hierarchy": false,
    "ai_usage_data_collection_enabled": false,
    "prompt_injection_protection_level": "no_checks",
    "web_search_enabled": false,
    "include_recommended_allowed": false,
    "allow_all_unix_sockets": false,
    "allow_project_extension": true,
    "minimum_access_level_execute": "developer",
    "minimum_access_level_execute_async": "developer",
    "minimum_access_level_manage": "maintainer",
    "minimum_access_level_enable_on_projects": "maintainer"
  },
  ...
}

ai_settings 객체에는 그룹의 AI 관련 설정이 담겨 있습니다. 자세한 내용은 ai_settings에 대한 응답 속성을 참고합니다.

ai_settings에 대한 응답 속성#

히스토리
  • GitLab 19.2에서 도입되었습니다.

ai_settings 객체는 그룹에서 GitLab Duo Agent Platform을 사용할 수 있을 때, 그룹을 읽을 수 있는 사용자의 응답에 포함됩니다. 이 객체에는 다음 속성이 있습니다.

속성 유형 설명
ai_catalog_restricted_to_group_hierarchy boolean true 인 경우 AI 카탈로그가 이 최상위 그룹 계층의 항목으로 제한됩니다. Premium 및 Ultimate 전용.
ai_usage_data_collection_enabled boolean true 인 경우 이 그룹에 대해 AI 사용 데이터 수집이 활성화됩니다. GitLab.com 전용.
allow_all_unix_sockets boolean true 인 경우 GitLab Duo Agent Platform에 대해 모든 Unix 소켓이 허용됩니다.
allow_project_extension boolean true 인 경우 프로젝트가 GitLab Duo Agent Platform의 네트워크 액세스 도메인 허용 목록을 확장할 수 있습니다.
duo_agent_platform_enabled boolean true 인 경우 이 그룹에 대해 GitLab Duo Agent Platform 기능이 활성화됩니다. Premium 및 Ultimate. GitLab Credits가 있는 GitLab.com의 Free 등급에서도 사용 가능.
duo_workflow_mcp_enabled boolean true 인 경우 GitLab Duo Agent Platform에 대한 MCP 지원이 활성화됩니다. Premium 및 Ultimate. GitLab Credits가 있는 GitLab.com의 Free 등급에서도 사용 가능.
foundational_agents_default_enabled boolean true 인 경우 이 그룹에 대해 새로운 파운데이셔널 에이전트가 기본적으로 활성화됩니다. Premium 및 Ultimate. GitLab Credits가 있는 GitLab.com의 Free 등급에서도 사용 가능.
include_recommended_allowed boolean true 인 경우 GitLab Duo Agent Platform의 네트워크 액세스 허용 목록에 권장 도메인이 포함됩니다.
minimum_access_level_enable_on_projects string 프로젝트에서 GitLab Duo Agent Platform을 활성화하는 데 필요한 최소 액세스 수준. developer, maintainer, owner 중 하나. dap_group_customizable_permissions 기능 플래그가 활성화된 경우 반환됩니다.
minimum_access_level_execute string 사용자가 GitLab Duo Agent Platform 기능과 상호 작용하는 데 필요한 최소 액세스 수준. guest, planner, reporter, developer, maintainer, owner 중 하나. dap_group_customizable_permissions 기능 플래그가 활성화된 경우 반환됩니다.
minimum_access_level_execute_async string CI/CD에서 GitLab Duo Agent Platform 기능을 실행하는 데 필요한 최소 액세스 수준. developer, maintainer, owner 중 하나. dap_group_customizable_permissions 기능 플래그가 활성화된 경우 반환됩니다.
minimum_access_level_manage string GitLab Duo Agent Platform을 관리하는 데 필요한 최소 액세스 수준. developer, maintainer, owner 중 하나. dap_group_customizable_permissions 기능 플래그가 활성화된 경우 반환됩니다.
prompt_injection_protection_level string 프롬프트 인젝션 보호 수준. no_checks, log_only, interrupt 중 하나.
web_search_enabled boolean true 인 경우 이 그룹의 GitLab Duo Chat에서 웹 검색이 활성화됩니다.

with_projects=false 파라미터를 추가하면 프로젝트가 반환되지 않습니다.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4?with_projects=false"

응답 예시:

{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "visibility": "public",
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Twitter",
  "full_path": "twitter",
  "file_template_project_id": 1,
  "parent_id": null
}

그룹 목록 조회#

전체 그룹 목록 조회#

인증된 사용자에게 보이는 그룹을 조회합니다. 인증 없이 접근하면 공개 그룹만 반환됩니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

인증 없이 접근하는 경우 이 엔드포인트는 키셋 페이지네이션도 지원합니다.

파라미터:

Attribute Type Required Description
skip_groups array of integers no 전달한 그룹 ID를 건너뜁니다.
all_available boolean no true 인 경우 접근 가능한 모든 그룹을 반환합니다. false 인 경우 사용자가 멤버인 그룹만 반환합니다. 기본값은 일반 사용자의 경우 false, 관리자의 경우 true 입니다. 인증되지 않은 요청은 항상 모든 공개 그룹을 반환합니다. owned 및 min_access_level 속성이 우선합니다.
search string no 검색 조건과 일치하는 인가된 그룹 목록을 반환합니다.
order_by string no 그룹을 name, path, id, similarity 기준으로 정렬합니다. 기본값은 name 입니다.
sort string no 그룹을 asc 또는 desc 순으로 정렬합니다. 기본값은 asc 입니다.
statistics boolean no 그룹 통계를 포함합니다(관리자 전용).
최상위 그룹의 경우 응답은 UI에 표시되는 전체 root_storage_statistics 데이터를 반환합니다. GitLab 17.4에서 도입되었습니다.
visibility string no 가시성이 public, internal, private 인 그룹으로 제한합니다.
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용).
owned boolean no 현재 사용자가 명시적으로 소유한 그룹으로 제한합니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 그룹으로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
top_level_only boolean no 모든 하위 그룹을 제외하고 최상위 그룹으로 제한합니다.
repository_storage string no 그룹이 사용하는 리포지터리 스토리지로 필터링합니다(관리자 전용). Premium 및 Ultimate 전용.
marked_for_deletion_on date no 그룹이 삭제 대상으로 표시된 날짜로 필터링합니다. GitLab 17.1에서 도입되었습니다. Premium 및 Ultimate 전용.
active boolean no 보관되지 않았고 삭제 대상으로 표시되지 않은 그룹으로 제한합니다.
archived boolean no 보관된 그룹으로 제한합니다. GitLab 18.2에서 도입되었습니다. 
GET /groups

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": null,
    "created_at": "2020-01-15T12:36:29.590Z",
    "ip_restriction_ranges": null
  }
]

statistics=true 파라미터를 추가하고 인증된 사용자가 관리자이면 추가 그룹 통계가 반환됩니다. 최상위 그룹의 경우 root_storage_statistics도 함께 추가됩니다.

GET /groups?statistics=true

statistics=true 파라미터를 사용하고 인증된 사용자가 관리자이면 응답에 컨테이너 레지스트리 스토리지 크기 정보가 포함됩니다.

  • container_registry_size: 그룹과 그 하위 그룹의 모든 컨테이너 리포지터리가 사용하는 총 스토리지 크기(바이트). 그룹의 프로젝트와 하위 그룹에 속한 모든 리포지터리 크기의 합으로 계산됩니다. 컨테이너 레지스트리 메타데이터 데이터베이스가 활성화된 경우에만 사용할 수 있습니다.
  • container_registry_size_is_estimated: 크기가 모든 리포지터리의 실제 데이터를 기반으로 한 정확한 계산인지(false), 성능 제약으로 인한 추정치인지(true)를 나타냅니다.

GitLab Self-Managed 인스턴스에서 컨테이너 레지스트리 크기 속성을 포함하려면 컨테이너 레지스트리 메타데이터 데이터베이스를 활성화해야 합니다.

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": null,
    "created_at": "2020-01-15T12:36:29.590Z",
    "statistics": {
      "storage_size": 363,
      "repository_size": 33,
      "wiki_size": 100,
      "lfs_objects_size": 123,
      "job_artifacts_size": 57,
      "pipeline_artifacts_size": 0,
      "packages_size": 0,
      "snippets_size": 50,
      "uploads_size": 0
    },
    "root_storage_statistics": {
      "build_artifacts_size": 0,
      "container_registry_size": 0,
      "container_registry_size_is_estimated": false,
      "dependency_proxy_size": 0,
      "lfs_objects_size": 0,
      "packages_size": 0,
      "pipeline_artifacts_size": 0,
      "repository_size": 0,
      "snippets_size": 0,
      "storage_size": 0,
      "uploads_size": 0,
      "wiki_size": 0
  },
    "wiki_access_level": "private",
    "duo_features_enabled": true,
    "lock_duo_features_enabled": false,
    "duo_availability": "default_on",
    "experiment_features_enabled": false,
  }
]

GitLab Premium 또는 Ultimate 사용자에게는 wiki_access_level, duo_features_enabled, lock_duo_features_enabled,

duo_availability, experiment_features_enabled 속성도 표시됩니다.

아래에 설명한 대로 이름 또는 경로로 그룹을 검색할 수 있습니다.

사용자 지정 속성으로 다음과 같이 필터링할 수 있습니다.

GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_value

그룹 페이지네이션#

API 결과가 페이지네이션 처리되므로 기본적으로 한 번에 20개의 그룹만 표시됩니다.

더 많은 결과(최대 100개)를 가져오려면 API 호출에 다음 인수를 전달합니다.

/groups?per_page=100

페이지를 전환하려면 다음을 추가합니다.

/groups?per_page=100&page=2

그룹 검색#

이름 또는 경로에 특정 문자열이 포함된 그룹을 검색합니다.

GET /groups?search=foobar

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group"
  }
]

그룹 세부 정보 목록 조회#

프로젝트 목록 조회#

그룹 내 프로젝트를 조회합니다. 인증 없이 접근하면 공개 프로젝트만 반환됩니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

GET /groups/:id/projects

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
active boolean no 프로젝트 상태로 제한합니다. true 인 경우 활성 프로젝트를 반환합니다. false 인 경우 보관되었거나 삭제 대상으로 표시된 프로젝트를 반환합니다. GitLab 18.8에서 도입되었습니다.
archived boolean no 보관 상태로 제한합니다.
visibility string no 가시성 public, internal, private로 제한합니다.
order_by string no id, name, path, created_at, updated_at, similarity1, star_count, last_activity_at 필드 기준으로 정렬한 프로젝트를 반환합니다. 기본값은 created_at 입니다.
sort string no 프로젝트를 asc 또는 desc 순으로 정렬해 반환합니다. 기본값은 desc 입니다.
search string no 검색 조건과 일치하는 인가된 프로젝트 목록을 반환합니다.
simple boolean no 각 프로젝트의 제한된 필드만 반환합니다. 인증 없이 요청하면 단순 필드만 반환되므로 이 옵션은 동작하지 않습니다.
owned boolean no 현재 사용자가 소유한 프로젝트로 제한합니다.
starred boolean no 현재 사용자가 별표 표시한 프로젝트로 제한합니다.
topic string no 해당 토픽과 일치하는 프로젝트를 반환합니다.
with_issues_enabled boolean no 이슈 기능이 활성화된 프로젝트로 제한합니다. 기본값은 false 입니다.
with_merge_requests_enabled boolean no 머지 리퀘스트 기능이 활성화된 프로젝트로 제한합니다. 기본값은 false 입니다.
with_shared boolean no 이 그룹에 공유된 프로젝트를 포함합니다. 기본값은 true 입니다.
include_subgroups boolean no 이 그룹의 하위 그룹에 있는 프로젝트를 포함합니다. 기본값은 false 입니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 프로젝트로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용).
with_security_reports boolean no 빌드 중 하나라도 보안 리포트 아티팩트가 있는 프로젝트만 반환합니다. 즉 "보안 리포트가 활성화된 프로젝트"를 의미합니다. 기본값은 false 입니다. Ultimate 전용.

응답 예시:

[
  {
    "id": 9,
    "description": "foo",
    "default_branch": "main",
    "tag_list": [], //deprecated, use `topics` instead
    "topics": [],
    "archived": false,
    "visibility": "internal",
    "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
    "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
    "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
    "name": "Html5 Boilerplate",
    "name_with_namespace": "Experimental / Html5 Boilerplate",
    "path": "html5-boilerplate",
    "path_with_namespace": "h5bp/html5-boilerplate",
    "issues_enabled": true,
    "merge_requests_enabled": true,
    "wiki_enabled": true,
    "jobs_enabled": true,
    "snippets_enabled": true,
    "created_at": "2016-04-05T21:40:50.169Z",
    "last_activity_at": "2016-04-06T16:52:08.432Z",
    "shared_runners_enabled": true,
    "creator_id": 1,
    "namespace": {
      "id": 5,
      "name": "Experimental",
      "path": "h5bp",
      "kind": "group"
    },
    "avatar_url": null,
    "star_count": 1,
    "forks_count": 0,
    "open_issues_count": 3,
    "public_jobs": true,
    "shared_with_groups": [],
    "request_access_enabled": false
  }
]
Note

그룹에 속한 프로젝트와 그룹에 공유된 프로젝트를 구분하려면 namespace 속성을 사용합니다. 프로젝트가 그룹에 공유된 경우, 해당 프로젝트의 namespace는 요청 대상 그룹과 다릅니다.

공유 프로젝트 목록 조회#

그룹에 공유된 프로젝트를 조회합니다. 인증 없이 접근하면 공개된 공유 프로젝트만 반환됩니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

GET /groups/:id/projects/shared

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
archived boolean no 보관 상태로 제한합니다.
visibility string no 가시성 public, internal, private로 제한합니다.
order_by string no id, name, path, created_at, updated_at, star_count, last_activity_at 필드 기준으로 정렬한 프로젝트를 반환합니다. 기본값은 created_at 입니다.
sort string no 프로젝트를 asc 또는 desc 순으로 정렬해 반환합니다. 기본값은 desc 입니다.
search string no 검색 조건과 일치하는 인가된 프로젝트 목록을 반환합니다.
simple boolean no 각 프로젝트의 제한된 필드만 반환합니다. 인증 없이 요청하면 단순 필드만 반환되므로 이 옵션은 동작하지 않습니다.
starred boolean no 현재 사용자가 별표 표시한 프로젝트로 제한합니다.
with_issues_enabled boolean no 이슈 기능이 활성화된 프로젝트로 제한합니다. 기본값은 false 입니다.
with_merge_requests_enabled boolean no 머지 리퀘스트 기능이 활성화된 프로젝트로 제한합니다. 기본값은 false 입니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 프로젝트로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용).

응답 예시:

[
   {
      "id":8,
      "description":"Shared project for Html5 Boilerplate",
      "name":"Html5 Boilerplate",
      "name_with_namespace":"H5bp / Html5 Boilerplate",
      "path":"html5-boilerplate",
      "path_with_namespace":"h5bp/html5-boilerplate",
      "created_at":"2020-04-27T06:13:22.642Z",
      "default_branch":"main",
      "tag_list":[], //deprecated, use `topics` instead
      "topics":[],
      "ssh_url_to_repo":"ssh://git@gitlab.com/h5bp/html5-boilerplate.git",
      "http_url_to_repo":"https://gitlab.com/h5bp/html5-boilerplate.git",
      "web_url":"https://gitlab.com/h5bp/html5-boilerplate",
      "readme_url":"https://gitlab.com/h5bp/html5-boilerplate/-/blob/main/README.md",
      "avatar_url":null,
      "star_count":0,
      "forks_count":4,
      "last_activity_at":"2020-04-27T06:13:22.642Z",
      "namespace":{
         "id":28,
         "name":"H5bp",
         "path":"h5bp",
         "kind":"group",
         "full_path":"h5bp",
         "parent_id":null,
         "avatar_url":null,
         "web_url":"https://gitlab.com/groups/h5bp"
      },
      "_links":{
         "self":"https://gitlab.com/api/v4/projects/8",
         "issues":"https://gitlab.com/api/v4/projects/8/issues",
         "merge_requests":"https://gitlab.com/api/v4/projects/8/merge_requests",
         "repo_branches":"https://gitlab.com/api/v4/projects/8/repository/branches",
         "labels":"https://gitlab.com/api/v4/projects/8/labels",
         "events":"https://gitlab.com/api/v4/projects/8/events",
         "members":"https://gitlab.com/api/v4/projects/8/members"
      },
      "empty_repo":false,
      "archived":false,
      "visibility":"public",
      "resolve_outdated_diff_discussions":false,
      "container_registry_enabled":true,
      "container_expiration_policy":{
         "cadence":"7d",
         "enabled":true,
         "keep_n":null,
         "older_than":null,
         "name_regex":null,
         "name_regex_keep":null,
         "next_run_at":"2020-05-04T06:13:22.654Z"
      },
      "issues_enabled":true,
      "merge_requests_enabled":true,
      "wiki_enabled":true,
      "jobs_enabled":true,
      "snippets_enabled":true,
      "can_create_merge_request_in":true,
      "issues_access_level":"enabled",
      "repository_access_level":"enabled",
      "merge_requests_access_level":"enabled",
      "forking_access_level":"enabled",
      "wiki_access_level":"enabled",
      "builds_access_level":"enabled",
      "snippets_access_level":"enabled",
      "pages_access_level":"enabled",
      "security_and_compliance_access_level":"enabled",
      "emails_disabled":null,
      "emails_enabled": null,
      "shared_runners_enabled":true,
      "lfs_enabled":true,
      "creator_id":1,
      "import_status":"failed",
      "open_issues_count":10,
      "ci_default_git_depth":50,
      "ci_forward_deployment_enabled":true,
      "ci_forward_deployment_rollback_allowed": true,
      "ci_allow_fork_pipelines_to_run_in_parent_project":true,
      "public_jobs":true,
      "build_timeout":3600,
      "auto_cancel_pending_pipelines":"enabled",
      "ci_config_path":null,
      "shared_with_groups":[
         {
            "group_id":24,
            "group_name":"Commit451",
            "group_full_path":"Commit451",
            "group_access_level":30,
            "expires_at":null
         }
      ],
      "only_allow_merge_if_pipeline_succeeds":false,
      "request_access_enabled":true,
      "only_allow_merge_if_all_discussions_are_resolved":false,
      "remove_source_branch_after_merge":true,
      "printing_merge_request_link_enabled":true,
      "merge_method":"merge",
      "suggestion_commit_message":null,
      "auto_devops_enabled":true,
      "auto_devops_deploy_strategy":"continuous",
      "autoclose_referenced_issues":true,
      "repository_storage":"default"
   }
]

공유 프로젝트 삭제#

그룹에 공유된 프로젝트를 삭제합니다. 그룹에서 Owner 권한이 필요합니다.

DELETE /groups/:id/shared_projects/:project_id

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
project_id integer yes 프로젝트의 ID.

성공하면 204 No Content를 반환합니다.

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/shared_projects/2"

전체 SAML 사용자 목록 조회#

히스토리
  • GitLab 18.1에서 도입되었습니다.

지정한 최상위 그룹의 모든 SAML 사용자를 조회합니다.

page 및 per_page 페이지네이션 파라미터로 결과를 필터링합니다.

GET /groups/:id/saml_users

지원 속성:

Attribute Type Required Description
id integer or string yes 최상위 그룹의 ID 또는 URL 인코딩된 경로.
username string no 지정한 사용자 이름을 가진 사용자를 반환합니다.
search string no 이름, 이메일, 사용자 이름이 일치하는 사용자를 반환합니다. 일부 값만 입력하면 결과 범위를 넓힐 수 있습니다.
active boolean no 활성 사용자만 반환합니다.
blocked boolean no 차단된 사용자만 반환합니다.
created_after datetime no 지정한 시각 이후에 생성된 사용자를 반환합니다. 형식: ISO 8601(YYYY-MM-DDTHH:MM:SSZ).
created_before datetime no 지정한 시각 이전에 생성된 사용자를 반환합니다. 형식: ISO 8601(YYYY-MM-DDTHH:MM:SSZ).

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/saml_users"

응답 예시:

[
  {
    "id": 66,
    "username": "user22",
    "name": "Sidney Jones22",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?s=80&d=identicon",
    "web_url": "http://my.gitlab.com/user22",
    "created_at": "2021-09-10T12:48:22.381Z",
    "bio": "",
    "location": null,
    "public_email": "",
    "linkedin": "",
    "twitter": "",
    "website_url": "",
    "organization": null,
    "job_title": "",
    "pronouns": null,
    "bot": false,
    "work_information": null,
    "followers": 0,
    "following": 0,
    "local_time": null,
    "last_sign_in_at": null,
    "confirmed_at": "2021-09-10T12:48:22.330Z",
    "last_activity_on": null,
    "email": "user22@example.org",
    "theme_id": 1,
    "color_scheme_id": 1,
    "projects_limit": 100000,
    "current_sign_in_at": null,
    "identities": [
      {
        "provider": "group_saml",
        "extern_uid": "2435223452345",
        "saml_provider_id": 1
      }
    ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": false,
    "external": false,
    "private_profile": false,
    "commit_email": "user22@example.org",
    "shared_runners_minutes_limit": null,
    "extra_shared_runners_minutes_limit": null,
    "scim_identities": [
      {
        "extern_uid": "2435223452345",
        "group_id": 1,
        "active": true
      }
    ]
  },
  ...
]

프로비저닝된 사용자 목록 조회#

그룹이 프로비저닝한 사용자를 조회합니다. 하위 그룹은 포함하지 않습니다.

그룹에서 Maintainer 또는 Owner 권한이 필요합니다.

GET /groups/:id/provisioned_users

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
username string no 특정 사용자 이름을 가진 사용자 한 명을 반환합니다.
search string no 이름, 이메일, 사용자 이름으로 사용자를 검색합니다.
active boolean no 활성 사용자만 반환합니다.
blocked boolean no 차단된 사용자만 반환합니다.
created_after datetime no 지정한 시각 이후에 생성된 사용자를 반환합니다.
created_before datetime no 지정한 시각 이전에 생성된 사용자를 반환합니다.

응답 예시:

[
  {
    "id": 66,
    "username": "user22",
    "name": "John Doe22",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?s=80&d=identicon",
    "web_url": "http://my.gitlab.com/user22",
    "created_at": "2021-09-10T12:48:22.381Z",
    "bio": "",
    "location": null,
    "public_email": "",
    "linkedin": "",
    "twitter": "",
    "website_url": "",
    "organization": null,
    "job_title": "",
    "pronouns": null,
    "bot": false,
    "work_information": null,
    "followers": 0,
    "following": 0,
    "local_time": null,
    "last_sign_in_at": null,
    "confirmed_at": "2021-09-10T12:48:22.330Z",
    "last_activity_on": null,
    "email": "user22@example.org",
    "theme_id": 1,
    "color_scheme_id": 1,
    "projects_limit": 100000,
    "current_sign_in_at": null,
    "identities": [ ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": false,
    "external": false,
    "private_profile": false,
    "commit_email": "user22@example.org",
    "shared_runners_minutes_limit": null,
    "extra_shared_runners_minutes_limit": null
  },
  ...
]

하위 그룹 목록 조회#

그룹에서 볼 수 있는 직계 하위 그룹을 조회합니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

이 목록을 다음과 같이 요청하는 경우:

  • 인증하지 않은 사용자로 요청하면 응답에 공개 그룹만 반환됩니다.
  • 인증한 사용자로 요청하면 응답에 본인이 멤버로 속한 그룹만 반환되며 공개 그룹은 포함되지 않습니다.

파라미터:

Attribute Type Required Description
id integer or string yes 바로 위 상위 그룹의 ID 또는 URL 인코딩된 경로.
skip_groups array of integers no 전달한 그룹 ID를 건너뜁니다.
all_available boolean no 접근 권한이 있는 모든 그룹을 표시합니다(인증된 사용자는 기본값 false, 관리자는 true). owned 및 min_access_level 속성이 우선합니다.
search string no 검색 조건과 일치하는 인가된 그룹 목록을 반환합니다. 하위 그룹의 짧은 경로만 검색하며 전체 경로는 검색하지 않습니다.
order_by string no 그룹을 name, path, id 기준으로 정렬합니다. 기본값은 name 입니다.
sort string no 그룹을 asc 또는 desc 순으로 정렬합니다. 기본값은 asc 입니다.
statistics boolean no 그룹 통계를 포함합니다(관리자 전용).
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용).
owned boolean no 현재 사용자가 명시적으로 소유한 그룹으로 제한합니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 그룹으로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
all_available boolean no true 인 경우 접근 가능한 모든 그룹을 반환합니다. false 인 경우 사용자가 멤버인 그룹만 반환합니다. 기본값은 일반 사용자의 경우 false, 관리자의 경우 true 입니다. 인증되지 않은 요청은 항상 모든 공개 그룹을 반환합니다. owned 및 min_access_level 속성이 우선합니다.
active boolean no 보관되지 않았고 삭제 대상으로 표시되지 않은 그룹으로 제한합니다. 
GET /groups/:id/subgroups

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://gitlab.example.com/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  }
]

GitLab Premium 또는 Ultimate 사용자에게는 wiki_access_level, duo_features_enabled, lock_duo_features_enabled, duo_availability, experiment_features_enabled 속성도 표시됩니다.

하위 그룹 목록 조회#

그룹에서 볼 수 있는 하위 그룹을 조회합니다. 인증 없이 접근하면 공개 그룹만 반환됩니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

파라미터:

Attribute Type Required Description
id integer or string yes 바로 위 상위 그룹의 ID 또는 URL 인코딩된 경로.
skip_groups array of integers no 전달한 그룹 ID를 건너뜁니다.
all_available boolean no true 인 경우 접근 가능한 모든 그룹을 반환합니다. false 인 경우 사용자가 멤버인 그룹만 반환합니다. 기본값은 일반 사용자의 경우 false, 관리자의 경우 true 입니다. 인증되지 않은 요청은 항상 모든 공개 그룹을 반환합니다. owned 및 min_access_level 속성이 우선합니다.
search string no 검색 조건과 일치하는 인가된 그룹 목록을 반환합니다. 하위 그룹의 짧은 경로만 검색하며 전체 경로는 검색하지 않습니다.
order_by string no 그룹을 name, path, id 기준으로 정렬합니다. 기본값은 name 입니다.
sort string no 그룹을 asc 또는 desc 순으로 정렬합니다. 기본값은 asc 입니다.
statistics boolean no 그룹 통계를 포함합니다(관리자 전용).
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용).
owned boolean no 현재 사용자가 명시적으로 소유한 그룹으로 제한합니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 그룹으로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
active boolean no 보관되지 않았고 삭제 대상으로 표시되지 않은 그룹으로 제한합니다. 
GET /groups/:id/descendant_groups

[
  {
    "id": 2,
    "name": "Bar Group",
    "path": "bar",
    "description": "A subgroup of Foo Group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/bar.jpg",
    "web_url": "http://gitlab.example.com/groups/foo/bar",
    "request_access_enabled": false,
    "full_name": "Bar Group",
    "full_path": "foo/bar",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  },
  {
    "id": 3,
    "name": "Baz Group",
    "path": "baz",
    "description": "A subgroup of Bar Group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/baz.jpg",
    "web_url": "http://gitlab.example.com/groups/foo/bar/baz",
    "request_access_enabled": false,
    "full_name": "Baz Group",
    "full_path": "foo/bar/baz",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  }
]

GitLab Premium 또는 Ultimate 사용자에게는 wiki_access_level, duo_features_enabled, lock_duo_features_enabled, duo_availability, experiment_features_enabled 속성도 표시됩니다.

공유된 그룹 목록 조회#

지정한 그룹이 초대받은 그룹을 조회합니다. 인증 없이 접근하면 공개된 공유 그룹만 반환됩니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
skip_groups array of integers no 지정한 그룹 ID를 건너뜁니다.
search string no 검색 조건과 일치하는 인가된 그룹 목록을 반환합니다.
order_by string no 그룹을 name, path, id, similarity 기준으로 정렬합니다. 기본값은 name 입니다.
sort string no 그룹을 asc 또는 desc 순으로 정렬합니다. 기본값은 asc 입니다.
visibility string no 가시성이 public, internal, private 인 그룹으로 제한합니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 그룹으로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용). 
GET /groups/:id/groups/shared

응답 예시:

[
  {
    "id": 101,
    "web_url": "http://gitlab.example.com/groups/some_path",
    "name": "group1",
    "path": "some_path",
    "description": "",
    "visibility": "public",
    "share_with_group_lock": "false",
    "require_two_factor_authentication": "false",
    "two_factor_grace_period": 48,
    "project_creation_level": "maintainer",
    "auto_devops_enabled": "nil",
    "subgroup_creation_level": "maintainer",
    "emails_disabled": "false",
    "emails_enabled": "true",
    "mentions_disabled": "nil",
    "lfs_enabled": "true",
    "math_rendering_limits_enabled": "true",
    "lock_math_rendering_limits_enabled": "false",
    "default_branch": "nil",
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
        "allowed_to_push": [
          {
              "access_level": 30
          }
        ],
        "allow_force_push": "true",
        "allowed_to_merge": [
          {
              "access_level": 30
          }
        ],
        "developer_can_initial_push": "false",
        "code_owner_approval_required": "false"
    },
    "avatar_url": "http://gitlab.example.com/uploads/-/system/group/avatar/101/banana_sample.gif",
    "request_access_enabled": "true",
    "full_name": "group1",
    "full_path": "some_path",
    "created_at": "2024-06-06T09:39:30.056Z",
    "parent_id": "nil",
    "organization_id": 1,
    "shared_runners_setting": "enabled",
    "ldap_cn": "nil",
    "ldap_access": "nil",
    "wiki_access_level": "enabled"
  }
]

초대된 그룹 목록 조회#

그룹에 초대된 그룹을 조회합니다. 인증 없이 접근하면 공개된 초대 그룹만 반환됩니다. 이 엔드포인트는 사용자별(인증된 사용자) 또는 IP 별(인증되지 않은 사용자)로 분당 60회 요청으로 속도가 제한됩니다.

API 결과는 페이지네이션 처리되므로 이 요청은 기본적으로 한 번에 20개의 결과를 반환합니다.

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.
search string no 검색 조건과 일치하는 인가된 그룹 목록을 반환합니다.
min_access_level integer no 현재 사용자가 지정한 액세스 수준 이상을 가진 그룹으로 제한합니다. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
relation array of strings no 관계(직접 또는 상속)로 그룹을 필터링합니다.
with_custom_attributes boolean no 응답에 사용자 지정 속성을 포함합니다(관리자 전용). 
GET /groups/:id/invited_groups

응답 예시:

[
  {
    "id": 33,
    "web_url": "http://gitlab.example.com/groups/flightjs",
    "name": "Flightjs",
    "path": "flightjs",
    "description": "Illo dolorum tempore eligendi minima ducimus provident.",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "maintainer",
    "emails_disabled": false,
    "emails_enabled": true,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "math_rendering_limits_enabled": true,
    "lock_math_rendering_limits_enabled": false,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
        {
          "access_level": 40
        }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
        {
          "access_level": 40
        }
      ],
      "developer_can_initial_push": false
    },
    "avatar_url": null,
    "request_access_enabled": true,
    "full_name": "Flightjs",
    "full_path": "flightjs",
    "created_at": "2024-07-09T10:31:08.307Z",
    "parent_id": null,
    "organization_id": 1,
    "shared_runners_setting": "enabled",
    "ldap_cn": null,
    "ldap_access": null,
    "wiki_access_level": "enabled"
  }
]

감사 이벤트 목록 조회#

그룹 감사 이벤트는 그룹 감사 이벤트 API로 조회할 수 있습니다.

그룹 관리#

그룹 생성#

Note

GitLab.com에서는 상위 그룹이 없는 그룹을 만들 때 GitLab UI를 사용해야 합니다. 이 작업에는 API를 사용할 수 없습니다.

새 프로젝트 그룹을 생성합니다. 그룹을 생성할 수 있는 사용자만 사용할 수 있습니다.

POST /groups

파라미터:

Attribute Type Required Description
name string yes 그룹의 이름.
path string yes 그룹의 경로.
auto_devops_enabled boolean no 이 그룹 내 모든 프로젝트에 Auto DevOps 파이프라인을 기본값으로 적용합니다.
avatar mixed no 그룹 아바타로 사용할 이미지 파일.
default_branch string no 그룹 내 프로젝트의 기본 브랜치 이름.
default_branch_protection integer no GitLab 17.0에서 deprecated 처리되었습니다. 대신 default_branch_protection_defaults를 사용합니다.
default_branch_protection_defaults hash no GitLab 17.0에서 도입되었습니다. 사용 가능한 옵션은 default_branch_protection_defaults 옵션을 참고합니다.
description string no 그룹의 설명.
enabled_git_access_protocol string no Git 액세스에 활성화할 프로토콜. 허용되는 값은 ssh, http, 두 프로토콜을 모두 허용하는 all 입니다.
emails_disabled boolean no (GitLab 16.5에서 deprecated 처리되었습니다.) 이메일 알림을 비활성화합니다. 대신 emails_enabled를 사용합니다.
emails_enabled boolean no 이메일 알림을 활성화합니다.
lfs_enabled boolean no 이 그룹 내 프로젝트의 Large File Storage(LFS)를 활성화하거나 비활성화합니다.
mentions_disabled boolean no 그룹이 멘션되는 기능을 비활성화합니다.
organization_id integer no 그룹의 조직 ID.
parent_id integer no 중첩 그룹을 생성할 때 사용할 상위 그룹 ID.
project_creation_level string no Developer가 그룹에서 프로젝트를 생성할 수 있는지 결정합니다. administrator(관리자 모드가 활성화된 사용자), noone(아무도 불가), maintainer(Maintainer 권한을 가진 사용자), developer(Developer 또는 Maintainer 권한을 가진 사용자) 중 하나입니다.
request_access_enabled boolean no 사용자가 멤버 액세스를 요청할 수 있도록 허용합니다.
require_two_factor_authentication boolean no 이 그룹의 모든 사용자에게 2단계 인증 설정을 요구합니다.
share_with_group_lock boolean no 이 그룹 내 프로젝트를 다른 그룹과 공유하지 못하도록 막습니다.
subgroup_creation_level string no 하위 그룹 생성을 허용합니다. owner(Owner 권한을 가진 사용자) 또는 maintainer(Maintainer 권한을 가진 사용자) 중 하나입니다.
two_factor_grace_period integer no 2단계 인증이 강제되기까지의 시간(시간 단위).
visibility string no 그룹의 가시성. private, internal, public 중 하나입니다.
membership_lock boolean no 이 그룹 내 프로젝트에 사용자를 추가할 수 없습니다. Premium 및 Ultimate 전용.
extra_shared_runners_minutes_limit integer no 관리자만 설정할 수 있습니다. 이 그룹의 추가 컴퓨팅 분. GitLab Self-Managed, Premium 및 Ultimate 전용.
shared_runners_minutes_limit integer no 관리자만 설정할 수 있습니다. 이 그룹의 월별 최대 컴퓨팅 분. nil(기본값, 시스템 기본값 상속), 0(무제한), > 0 중 하나입니다. GitLab Self-Managed, Premium 및 Ultimate 전용.
wiki_access_level string no 위키 액세스 수준. disabled, private, enabled 중 하나입니다. Premium 및 Ultimate 전용.
duo_availability string no GitLab Duo 사용 가능 여부 설정. 유효한 값은 default_on, default_off, never_on 입니다. 참고: UI에서 never_on은 "Always Off" 로 표시됩니다.
experiment_features_enabled boolean no 이 그룹의 실험 기능을 활성화합니다.
ai_settings_attributes hash no 이 그룹의 AI 관련 설정. 사용 가능한 옵션은 ai_settings_attributes 옵션을 참고합니다. GitLab Duo 기능이 활성화되어 있어야 합니다.

default_branch_protection 옵션#

default_branch_protection 속성은 다음 표와 같이 Developer 또는 Maintainer 권한을 가진 사용자가 해당 기본 브랜치에 푸시할 수 있는지를 결정합니다.

Value Description
0 보호 없음. Developer 또는 Maintainer 권한을 가진 사용자가 다음을 수행할 수 있습니다.
- 새 커밋 푸시.
- 변경 사항 강제 푸시.
- 브랜치 삭제.
1 부분 보호. Developer 또는 Maintainer 권한을 가진 사용자가 다음을 수행할 수 있습니다.
- 새 커밋 푸시.
2 전체 보호. Maintainer 권한을 가진 사용자만 다음을 수행할 수 있습니다.
- 새 커밋 푸시.
3 푸시 보호. Maintainer 권한을 가진 사용자가 다음을 수행할 수 있습니다.
- 새 커밋 푸시.
- 변경 사항 강제 푸시.
- 머지 리퀘스트 수락.
Developer 권한을 가진 사용자가 다음을 수행할 수 있습니다.
- 머지 리퀘스트 수락.
4 최초 푸시 이후 전체 보호. Developer 권한을 가진 사용자가 다음을 수행할 수 있습니다.
- 빈 리포지터리에 커밋 푸시.
Maintainer 권한을 가진 사용자가 다음을 수행할 수 있습니다.
- 새 커밋 푸시.
- 머지 리퀘스트 수락.

default_branch_protection_defaults 옵션#

히스토리
  • GitLab 17.0에서 도입되었습니다.

default_branch_protection_defaults 속성은 기본 브랜치 보호의 기본값을 설명합니다. 모든 파라미터는 선택 사항입니다.

Key Type Description
allowed_to_push array 푸시가 허용된 액세스 수준의 배열. Developer(30) 또는 Maintainer(40)를 지원합니다.
allow_force_push boolean 푸시 권한이 있는 모든 사용자에게 강제 푸시를 허용합니다.
allowed_to_merge array 머지가 허용된 액세스 수준의 배열. Developer(30) 또는 Maintainer(40)를 지원합니다.
developer_can_initial_push boolean Developer에게 최초 푸시를 허용합니다.
code_owner_approval_required boolean Code Owner 승인을 요구합니다.

하위 그룹 생성#

새 그룹 생성과 비슷합니다. 그룹 목록 조회 호출에서 얻은 parent_id가 필요합니다. 그다음 원하는 값을 입력합니다.

  • subgroup_path
  • subgroup_name
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"path": "<subgroup_path>", "name": "<subgroup_name>", "parent_id": <parent_group_id> }' \
  --url "https://gitlab.example.com/api/v4/groups/"

그룹 삭제 예약#

히스토리
  • GitLab 18.0에서 GitLab Premium에서 GitLab Free로 이동되었습니다.

그룹을 삭제 예약합니다. 그룹은 보존 기간이 끝날 때 삭제됩니다.

  • GitLab.com에서는 그룹이 30일간 보존됩니다.
  • GitLab Self-Managed에서는 보존 기간이 인스턴스 설정으로 제어됩니다.

이 엔드포인트는 이전에 삭제 예약된 하위 그룹을 즉시 삭제할 수도 있습니다.

사전 요구 사항:

  • 관리자이거나 그룹에서 Owner 권한이 있어야 합니다.
DELETE /groups/:id
Attribute Type Required Description
id integer or string Yes 그룹의 ID 또는 URL 인코딩된 경로.
full_path string Conditional 하위 그룹의 전체 경로. 하위 그룹 삭제를 확인하는 데 사용합니다. permanently_remove가 true 이면 이 속성은 필수입니다. 하위 그룹 경로는 그룹 세부 정보에서 확인합니다.
permanently_remove boolean/string No true 이면 이미 삭제 예약된 하위 그룹을 즉시 삭제합니다. 최상위 그룹은 삭제할 수 없습니다.

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

요청 예시:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Accept: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/:id"
Note

구독에 연결된 GitLab.com 그룹은 삭제할 수 없습니다. 먼저 구독을 다른 그룹과 연결해야 합니다.

그룹 영구 삭제#

설정된 보존 기간을 건너뛰고 그룹과 해당 데이터를 영구적으로 삭제합니다.

사전 요구 사항:

  • 관리자이거나 그룹에서 Owner 권한이 있어야 합니다.
DELETE /groups/:id
Attribute Type Required Description
id integer or string Yes 그룹의 ID 또는 URL 인코딩된 경로.
full_path string Yes 삭제 예약 후 변경된 하위 그룹의 전체 경로. permanently_remove가 true 이면 이 속성은 필수입니다. 변경된 전체 경로는 그룹 조회로 확인합니다.
permanently_remove boolean/string Yes true 이면 이미 삭제 예약된 하위 그룹을 영구적으로 삭제합니다. 최상위 그룹은 삭제할 수 없습니다.

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

삭제 예약된 그룹을 영구적으로 삭제하려면 다음을 수행합니다.

  1. API 호출로 그룹을 삭제 예약합니다.
  2. 두 번째 API 호출로 그룹을 삭제합니다.

예시:

# Schedule a group for deletion
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Accept: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/:id"

# Permanently delete a group scheduled for deletion
# Use the modified full_path of the subgroup
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"full_path": "<path-after-soft-delete>", "permanently_remove": "true"}' \
  --url "https://gitlab.example.com/api/v4/groups/:id"

삭제 예약된 그룹 복원#

이전에 삭제 표시된 그룹을 복원합니다.

POST /groups/:id/restore

파라미터:

Attribute Type Required Description
id integer or string yes 그룹의 ID 또는 URL 인코딩된 경로.

그룹 보관#

히스토리
  • GitLab 18.0에서 archive_group이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 18.9에서 일반 공급되었습니다. 기능 플래그 archive_group 이 제거되었습니다.

그룹을 보관합니다.

사전 요구 사항:

  • 관리자이거나 그룹에서 Owner 권한이 있어야 합니다.

그룹이 이미 보관된 상태이면 이 엔드포인트는 422 처리 불가 엔티티 오류를 반환합니다.

POST /groups/:id/archive

파라미터:

Attribute Type Required Description
id integer or string yes 인증된 사용자가 소유한 그룹의 ID 또는 URL 인코딩된 경로.

응답 예시:

{
  "id": 96,
  "web_url": "https://gitlab.example.com/groups/test-1",
  "name": "test-1",
  "path": "test-1",
  "description": "",
  "visibility": "public",
  "share_with_group_lock": false,
  "require_two_factor_authentication": false,
  "two_factor_grace_period": 48,
  "project_creation_level": "developer",
  "auto_devops_enabled": null,
  "subgroup_creation_level": "maintainer",
  "emails_disabled": false,
  "emails_enabled": true,
  "mentions_disabled": null,
  "lfs_enabled": true,
  "archived": true,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false,
  "require_sha_for_merge": false,
  "lock_require_sha_for_merge": false,
  "default_branch": null,
  "default_branch_protection": 2,
  "default_branch_protection_defaults": {
    "allowed_to_push": [
      {
        "access_level": 40
      }
    ],
    "allow_force_push": false,
    "allowed_to_merge": [
      {
        "access_level": 40
      }
    ],
    "developer_can_initial_push": false
  },
  "avatar_url": null,
  "request_access_enabled": true,
  "full_name": "test-1",
  "full_path": "test-1",
  "created_at": "2025-03-25T12:05:24.813Z",
  "parent_id": null,
  "organization_id": 1,
  "shared_runners_setting": "enabled",
  "max_artifacts_size": null,
  "ldap_cn": null,
  "ldap_access": null,
  "wiki_access_level": "enabled",
  "shared_with_groups": [],
  "prevent_sharing_groups_outside_hierarchy": false,
  "shared_runners_minutes_limit": null,
  "extra_shared_runners_minutes_limit": null,
  "prevent_forking_outside_group": null,
  "membership_lock": false
}

그룹 보관 해제#

히스토리
  • GitLab 18.0에서 archive_group이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 18.9에서 일반 공급되었습니다. 기능 플래그 archive_group 이 제거되었습니다.

그룹의 보관을 해제합니다.

사전 요구 사항:

  • 관리자이거나 그룹에서 Owner 권한이 있어야 합니다.

그룹이 보관된 상태가 아니면 이 엔드포인트는 422 처리 불가 엔티티 오류를 반환합니다.

POST /groups/:id/unarchive

파라미터:

Attribute Type Required Description
id integer or string yes 인증된 사용자가 소유한 그룹의 ID 또는 URL 인코딩된 경로.

응답 예시:

{
  "id": 96,
  "web_url": "https://gitlab.example.com/groups/test-1",
  "name": "test-1",
  "path": "test-1",
  "description": "",
  "visibility": "public",
  "share_with_group_lock": false,
  "require_two_factor_authentication": false,
  "two_factor_grace_period": 48,
  "project_creation_level": "developer",
  "auto_devops_enabled": null,
  "subgroup_creation_level": "maintainer",
  "emails_disabled": false,
  "emails_enabled": true,
  "mentions_disabled": null,
  "lfs_enabled": true,
  "archived": false,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false,
  "require_sha_for_merge": false,
  "lock_require_sha_for_merge": false,
  "default_branch": null,
  "default_branch_protection": 2,
  "default_branch_protection_defaults": {
    "allowed_to_push": [
      {
        "access_level": 40
      }
    ],
    "allow_force_push": false,
    "allowed_to_merge": [
      {
        "access_level": 40
      }
    ],
    "developer_can_initial_push": false
  },
  "avatar_url": null,
  "request_access_enabled": true,
  "full_name": "test-1",
  "full_path": "test-1",
  "created_at": "2025-03-25T12:05:24.813Z",
  "parent_id": null,
  "organization_id": 1,
  "shared_runners_setting": "enabled",
  "max_artifacts_size": null,
  "ldap_cn": null,
  "ldap_access": null,
  "wiki_access_level": "enabled",
  "shared_with_groups": [],
  "prevent_sharing_groups_outside_hierarchy": false,
  "shared_runners_minutes_limit": null,
  "extra_shared_runners_minutes_limit": null,
  "prevent_forking_outside_group": null,
  "membership_lock": false
}

그룹 이전#

히스토리
  • 비동기 이전이 GitLab 19.0에서 groups_and_projects_async_transfer라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • 비동기 이전이 GitLab 19.4에서 정식 출시되었습니다. 기능 플래그 groups_and_projects_async_transfer가 제거되었습니다.

그룹을 새 상위 그룹으로 이전하거나 하위 그룹을 최상위 그룹으로 전환합니다.

사전 요구 사항:

POST /groups/:id/transfer

파라미터:

Attribute Type Required Description
id integer yes 이전할 그룹의 ID.
group_id integer no 새 상위 그룹의 ID. 지정하지 않으면 그룹이 최상위 그룹으로 전환됩니다.

성공하면 201 Created와 이전 전 상태의 그룹을 반환합니다.

요청 예시:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4/transfer?group_id=7"

이전이 성공했는지 확인하려면 parent_id가 새 상위 그룹의 ID와 일치할 때까지 그룹을 조회합니다. 최상위 그룹의 값은 null입니다.

이전이 실패하면 이전을 요청한 사용자에게 transfer_failed 액션이 있는 할 일 항목이 생성됩니다. 할 일 항목을 가져오려면 모든 할 일 항목 나열을 참고합니다.

그룹 이전 가능한 위치 목록 조회#

지정된 그룹을 이전할 수 있는 모든 상위 그룹을 나열합니다.

GET /groups/:id/transfer_locations
Attribute Type Required Description
id integer or string Yes 이전할 그룹의 ID 또는 URL 인코딩된 경로.
search string No 검색할 특정 그룹의 이름.

요청 예시:

curl --request GET \
    --url "https://gitlab.example.com/api/v4/groups/1/transfer_locations"

응답 예시:

[
  {
    "id": 27,
    "web_url": "https://gitlab.example.com/groups/gitlab",
    "name": "GitLab",
    "avatar_url": null,
    "full_name": "GitLab",
    "full_path": "GitLab"
  },
  {
    "id": 31,
    "web_url": "https://gitlab.example.com/groups/foobar",
    "name": "FooBar",
    "avatar_url": null,
    "full_name": "FooBar",
    "full_path": "FooBar"
  }
]

프로젝트를 그룹으로 이전#

프로젝트를 다른 그룹 네임스페이스로 이전합니다. 또는 프로젝트를 새 네임스페이스로 이전 엔드포인트를 사용할 수도 있습니다.

Note

프로젝트 리포지터리에 태그가 지정된 패키지가 있으면 이전 과정이 실패할 수 있습니다.

사전 요구 사항:

  • 인스턴스의 관리자여야 합니다.
POST /groups/:id/projects/:project_id

파라미터:

Attribute Type Required Description
id integer or string yes 타깃 그룹의 ID 또는 URL 인코딩된 경로.
project_id integer or string yes 프로젝트의 ID 또는 URL 인코딩된 경로. 
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4/projects/56"

그룹 초대#

이 엔드포인트는 그룹 초대에 사용합니다. 자세한 내용은 그룹에 그룹 초대를 참고합니다.

그룹 초대 생성#

지정된 그룹에 타깃 그룹을 추가하는 그룹 초대를 생성합니다.

POST /groups/:id/share

파라미터:

Attribute Type Required Description
id integer or string yes 타깃 그룹의 ID 또는 URL 인코딩된 경로.
group_id integer yes 초대할 그룹의 ID.
group_access integer yes 초대된 그룹에 할당할 기본 access_level. 가능한 값: 5(Minimal access), 10(Guest), 15(Planner), 20(Reporter), 25(Security Manager), 30(Developer), 40(Maintainer), 50(Owner).
expires_at date (ISO 8601) no 그룹 초대가 만료되는 날짜.
member_role_id integer no 초대된 그룹에 할당할 사용자 지정 역할의 ID. 정의한 경우 group_access는 사용자 지정 역할을 만들 때 사용한 기본 역할과 일치해야 합니다.

성공하면 200과 그룹 세부 정보를 반환합니다.

그룹 초대 삭제#

그룹 초대를 삭제하고 지정된 그룹에서 타깃 그룹에 대한 액세스를 제거합니다.

DELETE /groups/:id/share/:group_id
Attribute Type Required Description
id integer or string yes 타깃 그룹의 ID 또는 URL 인코딩된 경로.
group_id integer yes 초대를 취소할 그룹의 ID.

성공하면 204와 빈 콘텐츠를 반환합니다.

그룹 속성 업데이트#

히스토리
  • GitLab 18.0에서 일반 공급되었습니다. 기능 플래그 limit_unique_project_downloads_per_namespace_user가 제거되었습니다.
  • GitLab 18.2에서 use_web_based_commit_signing_enabled라는 기능 플래그와 함께 web_based_commit_signing_enabled가 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 18.10에서 web_based_commit_signing_enabled가 일반 공급되었습니다. 기능 플래그 use_web_based_commit_signing_enabled가 제거되었습니다.
  • GitLab 18.5에서 allow_personal_snippets_setting이라는 기능 플래그와 함께 allow_personal_snippets가 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 18.9에서 allow_personal_snippets가 일반 공급되었습니다. 기능 플래그 allow_personal_snippets_setting 이 제거되었습니다.
  • GitLab 19.0에서 use_built_in_project_templates_enabled라는 기능 플래그와 함께 built_in_project_templates_enabled 및 lock_built_in_project_templates_enabled가 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 19.2에서 built_in_project_templates_enabled 및 lock_built_in_project_templates_enabled가 일반 공급되었습니다. 기능 플래그 use_built_in_project_templates_enabled가 제거되었습니다.
  • GitLab 19.2에서 ai_audit_events_storage_enabled 및 lock_ai_audit_events_storage_enabled가 도입되었습니다.

지정된 그룹의 속성을 업데이트합니다.

사전 요구 사항:

  • 관리자이거나 그룹에서 Owner 권한이 있어야 합니다.
PUT /groups/:id
Attribute Type Required Description
id integer yes 그룹의 ID.
name string no 그룹의 이름.
path string no 그룹의 경로.
auto_devops_enabled boolean no 이 그룹 내 모든 프로젝트에 Auto DevOps 파이프라인을 기본값으로 적용합니다.
avatar mixed no 그룹 아바타용 이미지 파일.
built_in_project_templates_enabled boolean no 사용자가 그룹에서 프로젝트를 생성할 때 기본 제공 프로젝트 템플릿을 활성화합니다. Premium 및 Ultimate 전용. GitLab 19.0에서 use_built_in_project_templates_enabled라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다. GitLab 19.2에서 일반 공급되었습니다. 기능 플래그 use_built_in_project_templates_enabled가 제거되었습니다.
lock_built_in_project_templates_enabled boolean no 모든 하위 그룹에 built_in_project_templates_enabled 설정을 강제합니다. Premium 및 Ultimate 전용. GitLab 19.0에서 use_built_in_project_templates_enabled라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다. GitLab 19.2에서 일반 공급되었습니다. 기능 플래그 use_built_in_project_templates_enabled가 제거되었습니다.
default_branch string no 그룹 프로젝트의 기본 브랜치 이름.
default_branch_protection integer no GitLab 17.0에서 지원 중단되었습니다. 대신 default_branch_protection_defaults를 사용합니다.
default_branch_protection_defaults hash no GitLab 17.0에서 도입되었습니다. 사용 가능한 옵션은 default_branch_protection_defaults 옵션을 참고합니다.
description string no 그룹의 설명.
enabled_git_access_protocol string no Git 액세스에 사용하도록 활성화된 프로토콜. 허용되는 값은 ssh, http, 두 프로토콜을 모두 허용하는 all 입니다.
emails_disabled boolean no (GitLab 16.5에서 지원 중단되었습니다.) 이메일 알림을 비활성화합니다. 대신 emails_enabled를 사용합니다.
emails_enabled boolean no 이메일 알림을 활성화합니다.
lfs_enabled boolean no 이 그룹의 프로젝트에 대해 Large File Storage(LFS)를 활성화하거나 비활성화합니다.
mentions_disabled boolean no 그룹이 멘션되는 기능을 비활성화합니다.
prevent_sharing_groups_outside_hierarchy boolean no 그룹 계층 외부로의 그룹 공유 방지를 참고합니다. 이 속성은 최상위 그룹에서만 사용할 수 있습니다.
project_creation_level string no 개발자가 그룹에서 프로젝트를 생성할 수 있는지 결정합니다. noone(아무도 없음), maintainer(Maintainer 권한이 있는 사용자), developer(Developer 또는 Maintainer 권한이 있는 사용자) 중 하나입니다.
request_access_enabled boolean no 사용자가 멤버 액세스를 요청할 수 있도록 허용합니다.
require_two_factor_authentication boolean no 이 그룹의 모든 사용자에게 2단계 인증 설정을 요구합니다.
shared_runners_setting string no shared_runners_setting 옵션을 참고합니다. 그룹의 하위 그룹과 프로젝트에 대해 인스턴스 러너를 활성화하거나 비활성화합니다.
share_with_group_lock boolean no 이 그룹 내에서 프로젝트를 다른 그룹과 공유하지 못하도록 합니다.
step_up_auth_required_oauth_provider string no 단계 상승 인증에 필요한 OAuth 공급자. 비활성화하려면 빈 문자열을 전달합니다. GitLab 18.4에서 도입되었습니다. omniauth_step_up_auth_for_namespace 기능 플래그가 활성화된 경우 사용할 수 있습니다.
subgroup_creation_level string no 하위 그룹 생성이 허용되는 대상. owner(Owner 권한이 있는 사용자) 또는 maintainer(Maintainer 권한이 있는 사용자) 중 하나입니다.
two_factor_grace_period integer no 2단계 인증이 강제되기까지의 시간(시간 단위).
visibility string no 그룹의 공개 수준. private, internal, public 중 하나입니다.
extra_shared_runners_minutes_limit integer no 관리자만 설정할 수 있습니다. 이 그룹의 추가 컴퓨팅 분. GitLab Self-Managed, Premium 및 Ultimate 전용.
file_template_project_id integer no 사용자 지정 파일 템플릿을 불러올 프로젝트의 ID. Premium 및 Ultimate 전용.
membership_lock boolean no 이 그룹의 프로젝트에 사용자를 추가할 수 없습니다. Premium 및 Ultimate 전용.
prevent_forking_outside_group boolean no 활성화하면 사용자가 이 그룹의 프로젝트를 외부 네임스페이스로 포크할 수 없습니다. Premium 및 Ultimate 전용.
shared_runners_minutes_limit integer no 관리자만 설정할 수 있습니다. 이 그룹의 월간 최대 컴퓨팅 분. nil(기본값, 시스템 기본값 상속), 0(무제한) 또는 > 0 일 수 있습니다. GitLab Self-Managed, Premium 및 Ultimate 전용.
unique_project_download_limit integer no 사용자가 차단되기 전까지 지정된 기간 동안 다운로드할 수 있는 고유 프로젝트의 최대 수. 최상위 그룹에서만 사용할 수 있습니다. 기본값: 0, 최댓값: 10,000. Ultimate 전용.
unique_project_download_limit_interval_in_seconds integer no 사용자가 차단되기 전까지 최대 개수의 프로젝트를 다운로드할 수 있는 기간. 최상위 그룹에서만 사용할 수 있습니다. 기본값: 0, 최댓값: 864,000초(10일). Ultimate 전용.
unique_project_download_limit_allowlist array of strings no 고유 프로젝트 다운로드 제한에서 제외되는 사용자 이름 목록. 최상위 그룹에서만 사용할 수 있습니다. 기본값: [], 최댓값: 사용자 이름 100개. Ultimate 전용.
unique_project_download_limit_alertlist array of integers no 고유 프로젝트 다운로드 제한을 초과했을 때 이메일을 받는 사용자 ID 목록. 최상위 그룹에서만 사용할 수 있습니다. 기본값: [], 최댓값: 사용자 ID 100개. Ultimate 전용.
auto_ban_user_on_excessive_projects_download boolean no 활성화하면 사용자가 unique_project_download_limit 및 unique_project_download_limit_interval_in_seconds로 지정한 최대 고유 프로젝트 수보다 많이 다운로드할 때 그룹에서 자동으로 차단됩니다. Ultimate 전용.
ip_restriction_ranges string no 그룹 액세스를 제한할 IP 주소 또는 서브넷 마스크의 쉼표로 구분된 목록. Premium 및 Ultimate 전용.
allowed_email_domains_list string no 그룹 액세스를 허용할 이메일 주소 도메인의 쉼표로 구분된 목록. 17.4에서 도입되었습니다. GitLab Premium 및 Ultimate 전용.
wiki_access_level string no 위키 액세스 수준. disabled, private, enabled 중 하나입니다. Premium 및 Ultimate 전용.
duo_availability string no GitLab Duo 가용성 설정. 유효한 값은 default_on, default_off, never_on 입니다. 참고: UI에서 never_on은 "Always Off" 로 표시됩니다.
experiment_features_enabled boolean no 이 그룹에 대해 실험 기능을 활성화합니다.
ai_settings_attributes hash no 이 그룹의 AI 관련 설정. 사용 가능한 옵션은 ai_settings_attributes 옵션을 참고합니다. GitLab Duo 기능이 활성화되어 있어야 합니다.
math_rendering_limits_enabled boolean no 이 그룹에 수식 렌더링 제한이 사용되는지 여부를 나타냅니다.
lock_math_rendering_limits_enabled boolean no 모든 하위 그룹에 대해 수식 렌더링 제한이 잠겨 있는지 여부를 나타냅니다.
require_sha_for_merge boolean no 이 그룹의 머지 리퀘스트가 머지 리퀘스트 병합 엔드포인트 호출에 유효한 커밋 SHA를 요구하는지 여부를 나타냅니다. GitLab 19.5에서 도입되었습니다.
lock_require_sha_for_merge boolean no 모든 하위 그룹에 require_sha_for_merge 설정을 강제합니다. GitLab 19.5에서 도입되었습니다.
duo_features_enabled boolean no 이 그룹에 대해 GitLab Duo 기능이 활성화되어 있는지 여부를 나타냅니다. GitLab Self-Managed, Premium 및 Ultimate 전용.
lock_duo_features_enabled boolean no GitLab Duo 기능 활성화 설정이 모든 하위 그룹에 강제되는지 여부를 나타냅니다. GitLab Self-Managed, Premium 및 Ultimate 전용.
ai_audit_events_storage_enabled boolean no 그룹에 대해 AI 감사 이벤트가 저장되는지 여부를 나타냅니다. GitLab 19.2에서 도입되었습니다. Premium 및 Ultimate 전용.
lock_ai_audit_events_storage_enabled boolean no AI 감사 이벤트 저장 설정이 모든 하위 그룹과 프로젝트에 강제되는지 여부를 나타냅니다. GitLab 19.2에서 도입되었습니다. Premium 및 Ultimate 전용.
max_artifacts_size integer No 개별 job 아티팩트의 최대 파일 크기(메가바이트).
web_based_commit_signing_enabled boolean No GitLab UI에서 생성한 커밋에 대해 웹 기반 커밋 서명을 활성화합니다. GitLab.com의 최상위 그룹에서만 사용할 수 있습니다. 그룹에 대해 활성화하면 그룹의 모든 프로젝트에 적용됩니다.
only_allow_merge_if_pipeline_succeeds boolean no 파이프라인이 성공한 경우에만 머지 리퀘스트 머지를 허용합니다. 그룹에 대해 활성화하면 그룹의 모든 프로젝트에 적용됩니다. Premium 및 Ultimate 전용.
allow_merge_on_skipped_pipeline boolean no 파이프라인을 건너뛴 경우에도 머지 리퀘스트 머지를 허용합니다. only_allow_merge_if_pipeline_succeeds가 true 인 경우에만 적용됩니다. Premium 및 Ultimate 전용.

| only_allow_merge_if_all_discussions_are_resolved | boolean | no | 모든 토론이 해결된 경우에만 머지 리퀘스트 머지를 허용합니다. 그룹에 대해 활성화하면 그룹의 모든 프로젝트에 적용됩니다. Premium 및 Ultimate 전용. | | allow_personal_snippets | boolean | no | 이 그룹의 엔터프라이즈 사용자가 개인 스니펫을 생성할 수 있도록 허용합니다. 비활성화하면 엔터프라이즈 사용자는 개인 네임스페이스에서 스니펫을 생성할 수 없습니다. |

Note

응답의 projects 및 shared_projects 속성은 지원이 중단되었으며 API v5에서 제거될 예정입니다. 그룹 내 모든 프로젝트의 세부 정보를 가져오려면 그룹의 프로젝트 목록 조회 또는 그룹의 공유 프로젝트 목록 조회 엔드포인트를 사용합니다.

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5?name=Experimental"

이 엔드포인트는 최대 100개의 프로젝트와 공유 프로젝트를 반환합니다. 그룹 내 모든 프로젝트의 세부 정보를 가져오려면 그룹의 프로젝트 목록 조회 엔드포인트를 대신 사용합니다.

응답 예시:

{
  "id": 5,
  "name": "Experimental",
  "path": "h5bp",
  "description": "foo",
  "visibility": "internal",
  "avatar_url": null,
  "web_url": "http://gitlab.example.com/groups/h5bp",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Foobar Group",
  "full_path": "h5bp",
  "file_template_project_id": 1,
  "parent_id": null,
  "enabled_git_access_protocol": "all",
  "created_at": "2020-01-15T12:36:29.590Z",
  "prevent_sharing_groups_outside_hierarchy": false,
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": false,
  "only_allow_merge_if_all_discussions_are_resolved": false,
  "allow_personal_snippets": true,
  "projects": [ // Deprecated and will be removed in API v5
    {
      "id": 9,
      "description": "foo",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "public": false,
      "archived": false,
      "visibility": "internal",
      "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
      "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
      "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "Experimental / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": true,
      "created_at": "2016-04-05T21:40:50.169Z",
      "last_activity_at": "2016-04-06T16:52:08.432Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "Experimental",
        "path": "h5bp",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 1,
      "forks_count": 0,
      "open_issues_count": 3,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    }
  ],
  "ip_restriction_ranges": null,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false,
  "require_sha_for_merge": false,
  "lock_require_sha_for_merge": false
}

prevent_sharing_groups_outside_hierarchy 속성은 최상위 그룹에 대해서만 응답에 포함됩니다.

GitLab Premium 또는 Ultimate 사용자에게는 wiki_access_level, duo_features_enabled, lock_duo_features_enabled, duo_availability, experiment_features_enabled 속성도 함께 표시됩니다.

shared_runners_setting 옵션#

shared_runners_setting 속성은 그룹의 하위 그룹과 프로젝트에 대해 인스턴스 러너가 활성화되는지 여부를 결정합니다.

Value Description
enabled 이 그룹의 모든 프로젝트와 하위 그룹에 대해 인스턴스 러너를 활성화합니다.
disabled_and_overridable 이 그룹의 모든 프로젝트와 하위 그룹에 대해 인스턴스 러너를 비활성화하지만, 하위 그룹이 이 설정을 재정의할 수 있도록 허용합니다.
disabled_and_unoverridable 이 그룹의 모든 프로젝트와 하위 그룹에 대해 인스턴스 러너를 비활성화하며, 하위 그룹이 이 설정을 재정의하지 못하도록 합니다.
disabled_with_override (지원 중단. disabled_and_overridable을 사용합니다.) 이 그룹의 모든 프로젝트와 하위 그룹에 대해 인스턴스 러너를 비활성화하지만, 하위 그룹이 이 설정을 재정의할 수 있도록 허용합니다.

ai_settings_attributes 옵션#

히스토리
  • GitLab 18.1에서 duo_workflow_mcp_enabled가 도입되었습니다.
  • GitLab 18.6에서 foundational_agents_default_enabled가 도입되었습니다.
  • GitLab 18.7에서 duo_agent_platform_enabled가 도입되었습니다.
  • GitLab 18.7에서 minimum_access_level_execute, minimum_access_level_execute_async, minimum_access_level_manage, minimum_access_level_enable_on_projects가 도입되었습니다.
  • GitLab 18.8에서 prompt_injection_protection_level 이 도입되었습니다.
  • GitLab 18.9에서 ai_usage_data_collection_enabled가 도입되었습니다.
  • GitLab 19.0에서 include_recommended_allowed, allow_all_unix_sockets, allow_project_extension 이 도입되었습니다.
  • GitLab 19.0에서 ai_catalog_restricted_to_group_hierarchy가 도입되었습니다.
  • GitLab 19.4에서 web_search_enabled가 도입되었습니다.

ai_settings_attributes 해시는 그룹의 AI 관련 설정을 구성합니다. 모든 속성은 선택 사항입니다.

Attribute Type Description
ai_catalog_restricted_to_group_hierarchy boolean true 인 경우 AI 카탈로그를 이 최상위 그룹 계층의 항목으로 제한합니다. 최상위 그룹에서만 설정할 수 있습니다. Premium 및 Ultimate 전용.
ai_usage_data_collection_enabled boolean true 인 경우 이 그룹에 대해 AI 사용 데이터 수집을 활성화합니다. GitLab.com 전용.
allow_all_unix_sockets boolean true 인 경우 GitLab Duo Agent Platform에 대해 모든 Unix 소켓을 허용합니다.
allow_project_extension boolean true 인 경우 프로젝트가 GitLab Duo Agent Platform의 네트워크 액세스 도메인 허용 목록을 확장할 수 있습니다.
duo_agent_platform_enabled boolean true 인 경우 이 그룹에 대해 GitLab Duo Agent Platform 기능을 활성화합니다. Premium 및 Ultimate. GitLab Credits가 있는 GitLab.com의 Free 등급에서도 사용 가능.
duo_workflow_mcp_enabled boolean true 인 경우 GitLab Duo Agent Platform에 대한 MCP 지원을 활성화합니다. Premium 및 Ultimate. GitLab Credits가 있는 GitLab.com의 Free 등급에서도 사용 가능.
foundational_agents_default_enabled boolean true 인 경우 이 그룹에 대해 새로운 파운데이셔널 에이전트가 기본적으로 활성화됩니다. Premium 및 Ultimate. GitLab Credits가 있는 GitLab.com의 Free 등급에서도 사용 가능.
include_recommended_allowed boolean true 인 경우 GitLab Duo Agent Platform의 네트워크 액세스 허용 목록에 권장 도메인을 포함합니다.
minimum_access_level_enable_on_projects integer 프로젝트에서 GitLab Duo Agent Platform을 활성화하는 데 필요한 최소 액세스 수준. 유효한 값: 30(Developer), 40(Maintainer), 50(Owner). dap_group_customizable_permissions 기능 플래그가 활성화된 경우 사용할 수 있습니다.
minimum_access_level_execute integer 사용자가 GitLab Duo Agent Platform 기능을 사용하는 데 필요한 최소 액세스 수준. 유효한 값: 10(Guest), 15(Planner), 20(Reporter), 30(Developer), 40(Maintainer), 50(Owner). dap_group_customizable_permissions 기능 플래그가 활성화된 경우 사용할 수 있습니다.
minimum_access_level_execute_async integer CI/CD에서 GitLab Duo Agent Platform 기능을 실행하는 데 필요한 최소 액세스 수준. 유효한 값: 30(Developer), 40(Maintainer), 50(Owner). dap_group_customizable_permissions 기능 플래그가 활성화된 경우 사용할 수 있습니다.
minimum_access_level_manage integer GitLab Duo Agent Platform을 관리하는 데 필요한 최소 액세스 수준. 유효한 값: 30(Developer), 40(Maintainer), 50(Owner). dap_group_customizable_permissions 기능 플래그가 활성화된 경우 사용할 수 있습니다.
prompt_injection_protection_level string 프롬프트 인젝션 보호 수준. 유효한 값: no_checks, log_only, interrupt.
web_search_enabled boolean true 인 경우 이 그룹의 GitLab Duo Chat에서 웹 검색을 활성화합니다. 최상위 그룹에서만 설정할 수 있습니다.

그룹 아바타 업데이트#

그룹 아바타를 업데이트합니다.

그룹 아바타 다운로드#

그룹 아바타를 가져옵니다. 그룹이 공개적으로 접근 가능한 경우 이 엔드포인트는 인증 없이도 접근할 수 있습니다.

GET /groups/:id/avatar
Attribute Type Required Description
id integer or string yes 그룹의 ID.

예시:

curl --request GET \
  --header "PRIVATE-TOKEN: $GITLAB_LOCAL_TOKEN" \
  --remote-header-name \
  --remote-name \
  --url "https://gitlab.example.com/api/v4/groups/4/avatar"

그룹 아바타 업로드#

파일 시스템에서 아바타 파일을 업로드하려면 --form 인수를 사용합니다. 이렇게 하면 curl 이 Content-Type: multipart/form-data 헤더를 사용해 데이터를 전송합니다. file= 파라미터는 파일 시스템의 파일을 가리켜야 하며 앞에 @를 붙여야 합니다. 예시:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "avatar=@/tmp/example.png" \
  --url "https://gitlab.example.com/api/v4/groups/22"

그룹 아바타 제거#

그룹 아바타를 제거하려면 avatar 속성에 빈 값을 사용합니다.

요청 예시:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "avatar=" \
  --url "https://gitlab.example.com/api/v4/groups/22"

그룹과 LDAP 동기화#

지정된 그룹을 연결된 LDAP 그룹과 동기화합니다.

사전 요구 사항:

  • 관리자이거나 그룹에서 Owner 권한이 있어야 합니다.
POST /groups/:id/ldap_sync
Attribute Type Required Description
id integer or string Yes 그룹의 ID 또는 URL 인코딩된 경로.

자격증명 인벤토리 관리#

히스토리
  • GitLab 18.6에서 manage_pat_by_group_owners_ready라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 18.7에서 일반 공급되었습니다. 기능 플래그 manage_pat_by_group_owners_ready가 제거되었습니다.

GitLab.com의 엔터프라이즈 사용자 자격 증명을 조회, 취소, 교체합니다.

사전 요구 사항:

  • 그룹에서 Owner 권한이 있어야 합니다.

그룹의 전체 개인 액세스 토큰 목록 조회#

히스토리
  • GitLab 19.4에서 응답의 last_used_ips가 도입되었습니다.

최상위 그룹의 엔터프라이즈 사용자와 연결된 모든 개인 액세스 토큰을 나열합니다.

GET /groups/:id/manage/personal_access_tokens
Attribute Type Required Description
id integer or string Yes 그룹의 ID 또는 URL 인코딩된 경로.
created_after datetime (ISO 8601) No 정의한 경우 지정된 시간 이후에 생성된 토큰을 반환합니다.
created_before datetime (ISO 8601) No 정의한 경우 지정된 시간 이전에 생성된 토큰을 반환합니다.
last_used_after datetime (ISO 8601) No 정의한 경우 지정된 시간 이후에 마지막으로 사용된 토큰을 반환합니다.
last_used_before datetime (ISO 8601) No 정의한 경우 지정된 시간 이전에 마지막으로 사용된 토큰을 반환합니다.
revoked boolean No true 이면 취소된 토큰만 반환합니다.
search string No 정의한 경우 이름에 지정된 값이 포함된 토큰을 반환합니다.
state string No 정의한 경우 지정된 상태의 토큰을 반환합니다. 가능한 값: active, inactive.
sort string No 정의한 경우 지정된 값으로 결과를 정렬합니다. 가능한 값: created_asc, created_desc, expires_asc, expires_desc, last_used_asc, last_used_desc, name_asc, name_desc.

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <group_owner_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/personal_access_tokens"

응답 예시:

[
  {
    "id": 1,
    "name": "Test Token",
    "revoked": false,
    "created_at": "2020-07-23T14:31:47.729Z",
    "description": "Test Token description",
    "scopes": [
        "api"
    ],
    "user_id": 3,
    "last_used_at": "2021-10-06T17:58:37.550Z",
    "last_used_ips": ["192.0.2.10"],
    "active": true,
    "expires_at": "2025-11-08"
  }
]

그룹의 전체 그룹 및 프로젝트 액세스 토큰 목록 조회#

최상위 그룹과 연결된 모든 그룹 및 프로젝트 액세스 토큰을 나열합니다.

GET /groups/:id/manage/resource_access_tokens
Attribute Type Required Description
id integer or string Yes 그룹의 ID 또는 URL 인코딩된 경로.
created_after datetime (ISO 8601) No 정의한 경우 지정된 시간 이후에 생성된 토큰을 반환합니다.
created_before datetime (ISO 8601) No 정의한 경우 지정된 시간 이전에 생성된 토큰을 반환합니다.
last_used_after datetime (ISO 8601) No 정의한 경우 지정된 시간 이후에 마지막으로 사용된 토큰을 반환합니다.
last_used_before datetime (ISO 8601) No 정의한 경우 지정된 시간 이전에 마지막으로 사용된 토큰을 반환합니다.
revoked boolean No true 이면 취소된 토큰만 반환합니다.
search string No 정의한 경우 이름에 지정된 값이 포함된 토큰을 반환합니다.
state string No 정의한 경우 지정된 상태의 토큰을 반환합니다. 가능한 값: active, inactive.
sort string No 정의한 경우 지정된 값으로 결과를 정렬합니다. 가능한 값: created_asc, created_desc, expires_asc, expires_desc, last_used_asc, last_used_desc, name_asc, name_desc.

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <group_owner_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/resource_access_tokens"

응답 예시:

[
  {
    "id": 12767703,
    "name": "Test Group Token",
    "revoked": false,
    "created_at": "2025-01-07T00:25:02.128Z",
    "description": "",
    "scopes": [
        "read_registry"
    ],
    "user_id": 25365147,
    "last_used_at": null,
    "active": true,
    "expires_at": "2025-06-19",
    "access_level": 10,
    "resource_type": "group",
    "resource_id": 77449520
  }
]

그룹의 전체 SSH 키 목록 조회#

최상위 그룹의 엔터프라이즈 사용자와 연결된 모든 SSH 공개 키를 나열합니다.

GET /groups/:id/manage/ssh_keys
Attribute Type Required Description
id integer or string Yes 그룹의 ID 또는 URL 인코딩된 경로.
created_after datetime (ISO 8601) No 정의한 경우 지정된 시간 이후에 생성된 SSH 키를 반환합니다.
created_before datetime (ISO 8601) No 정의한 경우 지정된 시간 이전에 생성된 SSH 키를 반환합니다.
expires_before datetime (ISO 8601) No 정의한 경우 지정된 시간 이전에 만료되는 SSH 키를 반환합니다.
expires_after datetime (ISO 8601) No 정의한 경우 지정된 시간 이후에 만료되는 SSH 키를 반환합니다. 
curl --request GET \
  --header "PRIVATE-TOKEN: <group_owner_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/ssh_keys"

응답 예시:

[
  {
    "id":3,
    "title":"Sample key 3",
    "created_at":"2024-12-23T05:40:11.891Z",
    "expires_at":null,
    "last_used_at":"2024-12-23T05:40:11.891Z",
    "usage_type":"auth_and_signing",
    "user_id":3
  }
]

엔터프라이즈 사용자의 개인 액세스 토큰 취소#

엔터프라이즈 사용자의 지정된 개인 액세스 토큰을 취소합니다.

DELETE groups/:id/manage/personal_access_tokens/:id
Attribute Type Required Description
id integer or string Yes 개인 액세스 토큰의 ID 또는 키워드 self. 
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/personal_access_tokens/<personal_access_token_id>"

성공하면 204: No Content를 반환합니다.

그 밖에 가능한 응답:

  • 취소에 실패한 경우 400: Bad Request.
  • 액세스 토큰이 유효하지 않은 경우 401: Unauthorized.
  • 액세스 토큰에 필요한 권한이 없는 경우 403: Forbidden.

엔터프라이즈 사용자의 그룹 또는 프로젝트 액세스 토큰 취소#

최상위 그룹과 연결된 엔터프라이즈 사용자의 지정된 그룹 또는 프로젝트 액세스 토큰을 취소합니다.

DELETE groups/:id/manage/resource_access_tokens/:id
Attribute Type Required Description
id integer or string Yes 리소스 액세스 토큰의 ID 또는 키워드 self. 
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/resource_access_tokens/<personal_access_token_id>"

성공하면 204: No Content를 반환합니다.

그 밖에 가능한 응답:

  • 취소에 실패한 경우 400: Bad Request.
  • 액세스 토큰이 유효하지 않은 경우 401: Unauthorized.
  • 액세스 토큰에 필요한 권한이 없는 경우 403: Forbidden.

엔터프라이즈 사용자의 SSH 키 삭제#

최상위 그룹과 연결된 엔터프라이즈 사용자의 지정된 SSH 공개 키를 삭제합니다.

DELETE /groups/:id/manage/ssh_keys/:key_id

지원되는 속성:

Attribute Type Required Description
key_id integer Yes 기존 키의 ID.

성공하면 204: No Content를 반환합니다.

그 밖에 가능한 응답:

  • SSH 키가 삭제되지 않은 경우 400: Bad Request.
  • SSH 키가 유효하지 않은 경우 401: Unauthorized.
  • 사용자에게 필요한 권한이 없는 경우 403: Forbidden.

엔터프라이즈 사용자의 개인 액세스 토큰 교체#

히스토리
  • GitLab 19.4에서 응답의 last_used_ips가 도입되었습니다.
  • GitLab 19.5에서 응답의 granular_scopes가 도입되었습니다.

최상위 그룹과 연결된 엔터프라이즈 사용자의 지정된 개인 액세스 토큰을 교체합니다. 이전 토큰은 취소되고 1주일 후에 만료되는 새 토큰이 생성됩니다.

POST groups/:id/manage/personal_access_tokens/:id/rotate
Attribute Type Required Description
id integer or string Yes 개인 액세스 토큰의 ID 또는 키워드 self.
expires_at date No ISO 형식(YYYY-MM-DD)으로 지정하는 액세스 토큰의 만료 날짜. 교체 날짜로부터 1년 이내여야 합니다. 정의하지 않으면 토큰은 1주일 후에 만료됩니다. 
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/manage/personal_access_tokens/<personal_access_token_id>/rotate"

응답 예시:

{
    "id": 42,
    "name": "Rotated Token",
    "revoked": false,
    "created_at": "2023-08-01T15:00:00.000Z",
    "description": "Test Token description",
    "scopes": ["api"],
    "user_id": 1337,
    "last_used_at": null,
    "last_used_ips": [],
    "active": true,
    "expires_at": "2023-08-15",
    "token": "s3cr3t"
}
Note

세분화된 범위가 있는 토큰을 교체하면 새 토큰의 granular_scopes 속성에 해당 범위가 반환됩니다. 자세한 내용은 모든 개인 액세스 토큰 나열을 참고합니다.

성공하면 200: OK를 반환합니다.

그 밖에 가능한 응답:

  • 교체에 실패한 경우 400: Bad Request.
  • 다음 조건 중 하나라도 해당하면 401: Unauthorized.
    • 토큰이 존재하지 않습니다.
    • 토큰이 만료되었습니다.
    • 토큰이 취소되었습니다.
    • 지정된 토큰에 대한 액세스 권한이 없습니다.
  • 토큰이 자체 교체를 허용하지 않는 경우 403: Forbidden.
  • 사용자에게 Owner 권한이 있지만 토큰이 존재하지 않는 경우 404: Not Found.
  • 토큰이 개인 액세스 토큰이 아닌 경우 405: Method Not Allowed.

엔터프라이즈 사용자의 그룹 또는 프로젝트 액세스 토큰 교체#

최상위 그룹과 연결된 엔터프라이즈 사용자의 지정된 그룹 또는 프로젝트 액세스 토큰을 교체합니다. 이전 토큰은 취소되고 1주일 후에 만료되는 새 토큰이 생성됩니다.

POST groups/:id/manage/resource_access_tokens/:id/rotate
Attribute Type Required Description
id integer or string Yes 개인 액세스 토큰의 ID 또는 키워드 self.
expires_at date No ISO 형식(YYYY-MM-DD)으로 지정하는 액세스 토큰의 만료 날짜. 교체 날짜로부터 1년 이내여야 합니다. 정의하지 않으면 토큰은 1주일 후에 만료됩니다. 
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/manage/resource_access_tokens/<resource_access_token_id>/rotate"

응답 예시:

{
    "id": 42,
    "name": "Rotated Token",
    "revoked": false,
    "created_at": "2023-08-01T15:00:00.000Z",
    "description": "Test Token description",
    "scopes": ["api"],
    "user_id": 1337,
    "last_used_at": null,
    "active": true,
    "expires_at": "2023-08-15",
    "token": "s3cr3t"
}

성공하면 200: OK를 반환합니다.

그 밖에 가능한 응답:

  • 교체에 실패한 경우 400: Bad Request.
  • 다음 조건 중 하나라도 해당하면 401: Unauthorized.
    • 토큰이 존재하지 않습니다.
    • 토큰이 만료되었습니다.
    • 토큰이 취소되었습니다.
    • 지정된 토큰에 대한 액세스 권한이 없습니다.
  • 토큰이 자체 교체를 허용하지 않거나 봇 사용자 토큰이 아닌 경우 403: Forbidden.
  • 사용자에게 Owner 권한이 있지만 토큰이 존재하지 않는 경우 404: Not Found.

Footnotes

  1. search URL 파라미터로 계산한 유사도 점수를 기준으로 결과를 정렬합니다. order_by=similarity를 사용하면 sort 파라미터는 무시됩니다. search 파라미터를 제공하지 않으면 API는 name 기준으로 정렬한 프로젝트를 반환합니다. ↩