그룹 레이블 API

요약

이 API를 사용하여 그룹 레이블을 관리합니다. 프로젝트 레이블의 경우 프로젝트 레이블 API를 사용합니다. 지정된 그룹의 모든 레이블을 가져옵니다. 지정된 그룹의 단일 레이블을 가져옵니다. 지정된 그룹에 새 그룹 레이블을 생성합니다.

히스토리

archived 속성이 GitLab 18.3에서 labels_archive라는 플래그와 함께 도입되었습니다.
GitLab 18.10에서 일반 공개되었습니다. 기능 플래그 labels_archive가 제거되었습니다.

이 API를 사용하여 그룹 레이블을 관리합니다.

프로젝트 레이블의 경우 프로젝트 레이블 API를 사용합니다.

그룹 레이블 목록 조회#

지정된 그룹의 모든 레이블을 가져옵니다.

GET /groups/:id/labels

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로.
`with_counts`	불리언	아니요	이슈 및 머지 리퀘스트 수를 포함할지 여부. 기본값은 `false`.
`include_ancestor_groups`	불리언	아니요	상위 그룹 포함. 기본값은 `true`.
`include_descendant_groups`	불리언	아니요	하위 그룹 포함. 기본값은 `false`.
`only_group_labels`	불리언	아니요	그룹 레이블만 포함할지 프로젝트 레이블도 포함할지 토글. 기본값은 `true`.
`search`	문자열	아니요	레이블을 필터링할 키워드.
`archived`	불리언	아니요	`true`이면 보관된 레이블만 반환합니다. 설정하지 않으면 모든 레이블을 반환합니다.

curl \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/labels?with_counts=true"

응답 예시:

[
  {
    "id": 7,
    "name": "bug",
    "color": "#FF0000",
    "text_color" : "#FFFFFF",
    "description": null,
    "description_html": null,
    "open_issues_count": 0,
    "closed_issues_count": 0,
    "open_merge_requests_count": 0,
    "subscribed": false,
    "archived": false
  },
  {
    "id": 4,
    "name": "feature",
    "color": "#228B22",
    "text_color" : "#FFFFFF",
    "description": null,
    "description_html": null,
    "open_issues_count": 0,
    "closed_issues_count": 0,
    "open_merge_requests_count": 0,
    "subscribed": false,
    "archived": false
  }
]

단일 그룹 레이블 가져오기#

지정된 그룹의 단일 레이블을 가져옵니다.

GET /groups/:id/labels/:label_id

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로.
`label_id`	정수 또는 문자열	예	그룹 레이블의 ID 또는 제목.
`include_ancestor_groups`	불리언	아니요	상위 그룹 포함. 기본값은 `true`.
`include_descendant_groups`	불리언	아니요	하위 그룹 포함. 기본값은 `false`.
`only_group_labels`	불리언	아니요	그룹 레이블만 포함할지 프로젝트 레이블도 포함할지 토글. 기본값은 `true`.

curl \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/labels/bug"

응답 예시:

{
  "id": 7,
  "name": "bug",
  "color": "#FF0000",
  "text_color" : "#FFFFFF",
  "description": null,
  "description_html": null,
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false,
  "archived": false
}

새 그룹 레이블 생성#

지정된 그룹에 새 그룹 레이블을 생성합니다.

POST /groups/:id/labels

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로
`name`	문자열	예	레이블의 이름
`color`	문자열	예	6자리 16진수 표기법에 선행 '#' 기호가 붙은 레이블 색상(예: #FFAABB) 또는 CSS 색상 이름 중 하나
`description`	문자열	아니요	레이블 설명.
`archived`	불리언	아니요	`true`이면 레이블을 보관 상태로 표시합니다. 기본값: `false`.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Feature Proposal",
    "color": "#FFA500",
    "description": "Describes new ideas"
  }' \
  --url "https://gitlab.example.com/api/v4/groups/5/labels"

응답 예시:

{
  "id": 9,
  "name": "Feature Proposal",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false,
  "archived": false
}

그룹 레이블 업데이트#

기존 그룹 레이블을 업데이트합니다. 그룹 레이블을 업데이트하려면 최소 하나의 매개변수가 필요합니다.

PUT /groups/:id/labels/:label_id

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로
`label_id`	정수 또는 문자열	예	그룹 레이블의 ID 또는 제목.
`new_name`	문자열	아니요	레이블의 새 이름
`color`	문자열	아니요	6자리 16진수 표기법에 선행 '#' 기호가 붙은 레이블 색상(예: #FFAABB) 또는 CSS 색상 이름 중 하나
`description`	문자열	아니요	레이블 설명.
`archived`	불리언	아니요	`true`이면 레이블을 보관 상태로 표시합니다. 기본값: `false`.

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"new_name": "Feature Idea"}' \
  --url "https://gitlab.example.com/api/v4/groups/5/labels/Feature%20Proposal"

응답 예시:

{
  "id": 9,
  "name": "Feature Idea",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false,
  "archived": false
}

Note

매개변수에 name을 사용하는 이전 엔드포인트 PUT /groups/:id/labels는 여전히 사용 가능하지만 더 이상 사용되지 않습니다.

그룹 레이블 삭제#

지정된 이름의 그룹 레이블을 삭제합니다.

DELETE /groups/:id/labels/:label_id

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로
`label_id`	정수 또는 문자열	예	그룹 레이블의 ID 또는 제목.

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/labels/bug"

Note

매개변수에 name을 사용하는 이전 엔드포인트 DELETE /groups/:id/labels는 여전히 사용 가능하지만 더 이상 사용되지 않습니다.

그룹 레이블 구독#

인증된 사용자가 그룹 레이블을 구독하여 알림을 받습니다. 사용자가 이미 레이블을 구독한 경우 상태 코드 304가 반환됩니다.

POST /groups/:id/labels/:label_id/subscribe

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로
`label_id`	정수 또는 문자열	예	그룹 레이블의 ID 또는 제목.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/labels/9/subscribe"

응답 예시:

{
  "id": 9,
  "name": "Feature Idea",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": true,
  "archived": false
}

그룹 레이블 구독 취소#

인증된 사용자가 그룹 레이블 구독을 취소하여 알림을 받지 않습니다. 사용자가 레이블을 구독하지 않은 경우 상태 코드 304가 반환됩니다.

POST /groups/:id/labels/:label_id/unsubscribe

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로
`label_id`	정수 또는 문자열	예	그룹 레이블의 ID 또는 제목.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/labels/9/unsubscribe"

응답 예시:

{
  "id": 9,
  "name": "Feature Idea",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false,
  "archived": false
}

그룹 레이블 API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

원문 보기

번역일: 2026-05-22

요약

히스토리

archived 속성이 GitLab 18.3에서 labels_archive라는 플래그와 함께 도입되었습니다.
GitLab 18.10에서 일반 공개되었습니다. 기능 플래그 labels_archive가 제거되었습니다.

이 API를 사용하여 그룹 레이블을 관리합니다.

프로젝트 레이블의 경우 프로젝트 레이블 API를 사용합니다.

그룹 레이블 목록 조회#

지정된 그룹의 모든 레이블을 가져옵니다.

GET /groups/:id/labels

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로.
`with_counts`	불리언	아니요	이슈 및 머지 리퀘스트 수를 포함할지 여부. 기본값은 `false`.
`include_ancestor_groups`	불리언	아니요	상위 그룹 포함. 기본값은 `true`.
`include_descendant_groups`	불리언	아니요	하위 그룹 포함. 기본값은 `false`.
`only_group_labels`	불리언	아니요	그룹 레이블만 포함할지 프로젝트 레이블도 포함할지 토글. 기본값은 `true`.
`search`	문자열	아니요	레이블을 필터링할 키워드.
`archived`	불리언	아니요	`true`이면 보관된 레이블만 반환합니다. 설정하지 않으면 모든 레이블을 반환합니다.

curl \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/labels?with_counts=true"

응답 예시:

[
  {
    "id": 7,
    "name": "bug",
    "color": "#FF0000",
    "text_color" : "#FFFFFF",
    "description": null,
    "description_html": null,
    "open_issues_count": 0,
    "closed_issues_count": 0,
    "open_merge_requests_count": 0,
    "subscribed": false,
    "archived": false
  },
  {
    "id": 4,
    "name": "feature",
    "color": "#228B22",
    "text_color" : "#FFFFFF",
    "description": null,
    "description_html": null,
    "open_issues_count": 0,
    "closed_issues_count": 0,
    "open_merge_requests_count": 0,
    "subscribed": false,
    "archived": false
  }
]

단일 그룹 레이블 가져오기#

지정된 그룹의 단일 레이블을 가져옵니다.

GET /groups/:id/labels/:label_id

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로.
`label_id`	정수 또는 문자열	예	그룹 레이블의 ID 또는 제목.
`include_ancestor_groups`	불리언	아니요	상위 그룹 포함. 기본값은 `true`.
`include_descendant_groups`	불리언	아니요	하위 그룹 포함. 기본값은 `false`.
`only_group_labels`	불리언	아니요	그룹 레이블만 포함할지 프로젝트 레이블도 포함할지 토글. 기본값은 `true`.

curl \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/labels/bug"

응답 예시:

{
  "id": 7,
  "name": "bug",
  "color": "#FF0000",
  "text_color" : "#FFFFFF",
  "description": null,
  "description_html": null,
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false,
  "archived": false
}

새 그룹 레이블 생성#

지정된 그룹에 새 그룹 레이블을 생성합니다.

POST /groups/:id/labels

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로
`name`	문자열	예	레이블의 이름
`color`	문자열	예	6자리 16진수 표기법에 선행 '#' 기호가 붙은 레이블 색상(예: #FFAABB) 또는 CSS 색상 이름 중 하나
`description`	문자열	아니요	레이블 설명.
`archived`	불리언	아니요	`true`이면 레이블을 보관 상태로 표시합니다. 기본값: `false`.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Feature Proposal",
    "color": "#FFA500",
    "description": "Describes new ideas"
  }' \
  --url "https://gitlab.example.com/api/v4/groups/5/labels"

응답 예시:

{
  "id": 9,
  "name": "Feature Proposal",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false,
  "archived": false
}

그룹 레이블 업데이트#

기존 그룹 레이블을 업데이트합니다. 그룹 레이블을 업데이트하려면 최소 하나의 매개변수가 필요합니다.

PUT /groups/:id/labels/:label_id

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로
`label_id`	정수 또는 문자열	예	그룹 레이블의 ID 또는 제목.
`new_name`	문자열	아니요	레이블의 새 이름
`color`	문자열	아니요	6자리 16진수 표기법에 선행 '#' 기호가 붙은 레이블 색상(예: #FFAABB) 또는 CSS 색상 이름 중 하나
`description`	문자열	아니요	레이블 설명.
`archived`	불리언	아니요	`true`이면 레이블을 보관 상태로 표시합니다. 기본값: `false`.

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"new_name": "Feature Idea"}' \
  --url "https://gitlab.example.com/api/v4/groups/5/labels/Feature%20Proposal"

응답 예시:

{
  "id": 9,
  "name": "Feature Idea",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false,
  "archived": false
}

Note

매개변수에 name을 사용하는 이전 엔드포인트 PUT /groups/:id/labels는 여전히 사용 가능하지만 더 이상 사용되지 않습니다.

그룹 레이블 삭제#

지정된 이름의 그룹 레이블을 삭제합니다.

DELETE /groups/:id/labels/:label_id

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로
`label_id`	정수 또는 문자열	예	그룹 레이블의 ID 또는 제목.

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/labels/bug"

Note

매개변수에 name을 사용하는 이전 엔드포인트 DELETE /groups/:id/labels는 여전히 사용 가능하지만 더 이상 사용되지 않습니다.

그룹 레이블 구독#

인증된 사용자가 그룹 레이블을 구독하여 알림을 받습니다. 사용자가 이미 레이블을 구독한 경우 상태 코드 304가 반환됩니다.

POST /groups/:id/labels/:label_id/subscribe

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로
`label_id`	정수 또는 문자열	예	그룹 레이블의 ID 또는 제목.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/labels/9/subscribe"

응답 예시:

{
  "id": 9,
  "name": "Feature Idea",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": true,
  "archived": false
}

그룹 레이블 구독 취소#

인증된 사용자가 그룹 레이블 구독을 취소하여 알림을 받지 않습니다. 사용자가 레이블을 구독하지 않은 경우 상태 코드 304가 반환됩니다.

POST /groups/:id/labels/:label_id/unsubscribe

속성	유형	필수	설명
`id`	정수 또는 문자열	예	그룹의 ID 또는 URL 인코딩된 경로
`label_id`	정수 또는 문자열	예	그룹 레이블의 ID 또는 제목.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/labels/9/unsubscribe"

응답 예시:

{
  "id": 9,
  "name": "Feature Idea",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false,
  "archived": false
}