Epics API (deprecated)
Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
요약
Epics REST API는 GitLab 17.0에서 deprecated되었으며 API v5에서 제거될 예정입니다. 에픽에 대한 모든 API 호출은 인증이 필요합니다. 사용자가 비공개 그룹의 멤버가 아닌 경우, 해당 그룹에 대한 GET 요청은 404 상태 코드를 반환합니다.
Warning
Epics REST API는 GitLab 17.0에서 deprecated되었으며 API v5에서 제거될 예정입니다. GitLab 17.4~18.0에서 에픽의 새로운 모습이 활성화된 경우, 그리고 GitLab 18.1 이상에서는 Work Items API를 대신 사용하세요. 자세한 내용은 에픽 API를 work items로 마이그레이션을 참조하세요. 이 변경사항은 파괴적 변경입니다.
에픽에 대한 모든 API 호출은 인증이 필요합니다.
사용자가 비공개 그룹의 멤버가 아닌 경우, 해당 그룹에 대한 GET 요청은 404 상태 코드를 반환합니다.
에픽 기능을 사용할 수 없는 경우 403 상태 코드가 반환됩니다.
레거시 Epic ID와 WorkItem ID#
레거시 Epic ID는 WorkItem ID와 동일하지 않습니다. iid만 일치합니다. 그러나 에픽에 해당하는 WorkItem ID를 조회하기 위해 응답에 work_item_id가 포함됩니다.
이 ID는 WorkItem GraphQL API에 사용할 수 있으며, 예를 들어 work_item_id는 WorkItem GraphQL API에서 gid://gitlab/WorkItem/123 형식의 전역 ID가 됩니다.
Epic issues API#
epic issues API를 사용하면 에픽과 연관된 이슈와 상호작용할 수 있습니다.
마일스톤 날짜 통합#
시작 날짜와 마감 날짜는 관련 이슈 마일스톤에서 동적으로 가져올 수 있으므로,
사용자에게 편집 권한이 있는 경우 추가 필드가 표시됩니다. 여기에는 두 개의 부울
필드 start_date_is_fixed 및 due_date_is_fixed, 그리고 네 개의 날짜 필드 start_date_fixed,
start_date_from_inherited_source, due_date_fixed, due_date_from_inherited_source가 포함됩니다.
end_date는due_date로 대체되어 deprecated되었습니다.start_date_from_milestones는start_date_from_inherited_source로 대체되어 deprecated되었습니다.due_date_from_milestones는due_date_from_inherited_source로 대체되어 deprecated되었습니다.
모든 그룹 에픽 나열#
지정된 그룹과 해당 하위 그룹의 모든 에픽을 나열합니다.
응답은 페이지네이션되며 기본적으로 20개 결과를 반환합니다.
Note
references.relative는 에픽이 요청되는 그룹에 상대적입니다. 에픽이 원본 그룹에서
가져올 때 relative 형식은 short 형식과 동일합니다.
에픽이 그룹 간에 요청될 때 relative 형식은 full 형식과 동일할 것으로 예상됩니다.
GET /groups/:id/epics
GET /groups/:id/epics?author_id=5
GET /groups/:id/epics?labels=bug,reproduced
GET /groups/:id/epics?state=opened
| 속성 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
id |
정수 또는 문자열 | 예 | 그룹의 ID 또는 URL-인코딩된 경로. |
author_id |
정수 | 아니요 | 지정된 사용자 id가 생성한 에픽을 반환합니다. |
author_username |
문자열 | 아니요 | 지정된 username의 사용자가 생성한 에픽을 반환합니다. |
labels |
문자열 | 아니요 | 쉼표로 구분된 라벨 이름 목록과 일치하는 에픽을 반환합니다. 에픽 그룹 또는 상위 그룹의 라벨 이름을 사용할 수 있습니다. |
with_labels_details |
부울 | 아니요 | true이면 응답에서 labels 필드의 각 라벨에 대해 더 많은 세부 정보를 반환합니다: :name, :color, :description, :description_html, :text_color. 기본값: false. |
order_by |
문자열 | 아니요 | created_at, updated_at, title 필드로 에픽을 정렬하여 반환합니다. 기본값: created_at. |
sort |
문자열 | 아니요 | asc 또는 desc 순서로 에픽을 정렬하여 반환합니다. 기본값: desc. |
search |
문자열 | 아니요 | title과 description에 대해 에픽을 검색합니다. |
state |
문자열 | 아니요 | state에 대해 에픽을 검색합니다. 가능한 필터: opened, closed, all. 기본값: all. |
created_after |
날짜/시간 | 아니요 | 지정된 시간 이후에 생성된 에픽을 반환합니다. ISO 8601 형식(2019-03-15T08:00:00Z)으로 예상됩니다. |
created_before |
날짜/시간 | 아니요 | 지정된 시간 이전에 생성된 에픽을 반환합니다. ISO 8601 형식(2019-03-15T08:00:00Z)으로 예상됩니다. |
updated_after |
날짜/시간 | 아니요 | 지정된 시간 이후에 업데이트된 에픽을 반환합니다. ISO 8601 형식(2019-03-15T08:00:00Z)으로 예상됩니다. |
updated_before |
날짜/시간 | 아니요 | 지정된 시간 이전에 업데이트된 에픽을 반환합니다. ISO 8601 형식(2019-03-15T08:00:00Z)으로 예상됩니다. |
include_ancestor_groups |
부울 | 아니요 | 요청된 그룹의 상위 그룹의 에픽을 포함합니다. 기본값: false. |
include_descendant_groups |
부울 | 아니요 | 요청된 그룹의 하위 그룹의 에픽을 포함합니다. 기본값: true. |
my_reaction_emoji |
문자열 | 아니요 | 인증된 사용자가 지정된 이모지로 반응한 에픽을 반환합니다. None은 반응이 없는 에픽을 반환합니다. Any는 하나 이상의 반응이 있는 에픽을 반환합니다. |
not |
해시 | 아니요 | 제공된 파라미터와 일치하지 않는 에픽을 반환합니다. 허용 값: author_id, author_username, labels. |
curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/1/epics"
응답 예시:
[
{
"id": 29,
"work_item_id": 1032,
"iid": 4,
"group_id": 7,
"parent_id": 23,
"parent_iid": 3,
"title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",
"description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
"state": "opened",
"confidential": "false",
"web_url": "http://gitlab.example.com/groups/test/-/epics/4",
"reference": "&4",
"references": {
"short": "&4",
"relative": "&4",
"full": "test&4"
},
"author": {
"id": 10,
"name": "Lu Mayer",
"username": "kam",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
"web_url": "http://gitlab.example.com/kam"
},
"start_date": null,
"start_date_is_fixed": false,
"start_date_fixed": null,
"start_date_from_milestones": null, //deprecated in favor of start_date_from_inherited_source
"start_date_from_inherited_source": null,
"end_date": "2018-07-31", //deprecated in favor of due_date
"due_date": "2018-07-31",
"due_date_is_fixed": false,
"due_date_fixed": null,
"due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
"due_date_from_inherited_source": "2018-07-31",
"created_at": "2018-07-17T13:36:22.770Z",
"updated_at": "2018-07-18T12:22:05.239Z",
"closed_at": "2018-08-18T12:22:05.239Z",
"labels": [],
"upvotes": 4,
"downvotes": 0,
"color": "#1068bf",
"_links":{
"self": "http://gitlab.example.com/api/v4/groups/7/epics/4",
"epic_issues": "http://gitlab.example.com/api/v4/groups/7/epics/4/issues",
"group":"http://gitlab.example.com/api/v4/groups/7",
"parent":"http://gitlab.example.com/api/v4/groups/7/epics/3"
}
},
{
"id": 50,
"work_item_id": 1035,
"iid": 35,
"group_id": 17,
"parent_id": 19,
"parent_iid": 1,
"title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",
"description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
"state": "opened",
"web_url": "http://gitlab.example.com/groups/test/sample/-/epics/35",
"reference": "&4",
"references": {
"short": "&4",
"relative": "sample&4",
"full": "test/sample&4"
},
"author": {
"id": 10,
"name": "Lu Mayer",
"username": "kam",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
"web_url": "http://gitlab.example.com/kam"
},
"start_date": null,
"start_date_is_fixed": false,
"start_date_fixed": null,
"start_date_from_milestones": null, //deprecated in favor of start_date_from_inherited_source
"start_date_from_inherited_source": null,
"end_date": "2018-07-31", //deprecated in favor of due_date
"due_date": "2018-07-31",
"due_date_is_fixed": false,
"due_date_fixed": null,
"due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
"due_date_from_inherited_source": "2018-07-31",
"created_at": "2018-07-17T13:36:22.770Z",
"updated_at": "2018-07-18T12:22:05.239Z",
"closed_at": "2018-08-18T12:22:05.239Z",
"imported": false,
"imported_from": "none",
"labels": [],
"upvotes": 4,
"downvotes": 0,
"color": "#1068bf",
"_links":{
"self": "http://gitlab.example.com/api/v4/groups/17/epics/35",
"epic_issues": "http://gitlab.example.com/api/v4/groups/17/epics/35/issues",
"group":"http://gitlab.example.com/api/v4/groups/17",
"parent":"http://gitlab.example.com/api/v4/groups/17/epics/1"
}
}
]
에픽 조회#
그룹의 지정된 에픽을 조회합니다.
GET /groups/:id/epics/:epic_iid
| 속성 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
id |
정수 또는 문자열 | 예 | 그룹의 ID 또는 URL-인코딩된 경로. |
epic_iid |
정수 또는 문자열 | 예 | 에픽의 내부 ID. |
curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/1/epics/5"
응답 예시:
{
"id": 30,
"work_item_id": 1099,
"iid": 5,
"group_id": 7,
"parent_id": null,
"parent_iid": null,
"title": "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.",
"description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
"state": "opened",
"imported": false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/groups/test/-/epics/5",
"reference": "&5",
"references": {
"short": "&5",
"relative": "&5",
"full": "test&5"
},
"author":{
"id": 7,
"name": "Pamella Huel",
"username": "arnita",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",
"web_url": "http://gitlab.example.com/arnita"
},
"start_date": null,
"start_date_is_fixed": false,
"start_date_fixed": null,
"start_date_from_milestones": null, //deprecated in favor of start_date_from_inherited_source
"start_date_from_inherited_source": null,
"end_date": "2018-07-31", //deprecated in favor of due_date
"due_date": "2018-07-31",
"due_date_is_fixed": false,
"due_date_fixed": null,
"due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
"due_date_from_inherited_source": "2018-07-31",
"created_at": "2018-07-17T13:36:22.770Z",
"updated_at": "2018-07-18T12:22:05.239Z",
"closed_at": "2018-08-18T12:22:05.239Z",
"labels": [],
"upvotes": 4,
"downvotes": 0,
"color": "#1068bf",
"subscribed": true,
"_links":{
"self": "http://gitlab.example.com/api/v4/groups/7/epics/5",
"epic_issues": "http://gitlab.example.com/api/v4/groups/7/epics/5/issues",
"group":"http://gitlab.example.com/api/v4/groups/7",
"parent": null
}
}
에픽 생성#
지정된 그룹에 에픽을 생성합니다.
Note
GitLab 11.3부터 start_date와 end_date는
이제 복합 값을 나타내므로 직접 할당하면 안 됩니다. 대신 *_is_fixed와
*_fixed 필드를 통해 구성할 수 있습니다.
POST /groups/:id/epics
| 속성 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
id |
정수 또는 문자열 | 예 | 그룹의 ID 또는 URL-인코딩된 경로. |
title |
문자열 | 예 | 에픽의 제목. |
labels |
문자열 | 아니요 | 쉼표로 구분된 라벨 목록. |
description |
문자열 | 아니요 | 에픽의 설명. 최대 1,048,576자. |
color |
문자열 | 아니요 | 에픽의 색상. epic_highlight_color라는 기능 플래그 뒤에 있습니다(기본값: 비활성화). |
confidential |
부울 | 아니요 | 에픽을 기밀로 설정할지 여부. |
created_at |
문자열 | 아니요 | 에픽이 생성된 날짜. ISO 8601 형식의 날짜 시간 문자열(2016-03-11T03:45:40Z). 관리자 또는 프로젝트/그룹 소유자 권한이 필요합니다. |
start_date_is_fixed |
부울 | 아니요 | 시작 날짜가 start_date_fixed 또는 마일스톤에서 가져와야 하는지 여부. |
start_date_fixed |
문자열 | 아니요 | 에픽의 고정 시작 날짜. |
due_date_is_fixed |
부울 | 아니요 | 마감 날짜가 due_date_fixed 또는 마일스톤에서 가져와야 하는지 여부. |
due_date_fixed |
문자열 | 아니요 | 에픽의 고정 마감 날짜. |
parent_id |
정수 또는 문자열 | 아니요 | 부모 에픽의 ID. |
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/1/epics?title=Epic&description=Epic%20description&parent_id=29"
응답 예시:
{
"id": 33,
"work_item_id": 1020,
"iid": 6,
"group_id": 7,
"parent_id": 29,
"parent_iid": 4,
"title": "Epic",
"description": "Epic description",
"state": "opened",
"imported": false,
"imported_from": "none",
"confidential": "false",
"web_url": "http://gitlab.example.com/groups/test/-/epics/6",
"reference": "&6",
"references": {
"short": "&6",
"relative": "&6",
"full": "test&6"
},
"author": {
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"state" : "active",
"web_url" : "https://gitlab.example.com/eileen.lowe",
"id" : 18,
"username" : "eileen.lowe"
},
"start_date": null,
"start_date_is_fixed": false,
"start_date_fixed": null,
"start_date_from_milestones": null, //deprecated in favor of start_date_from_inherited_source
"start_date_from_inherited_source": null,
"end_date": "2018-07-31", //deprecated in favor of due_date
"due_date": "2018-07-31",
"due_date_is_fixed": false,
"due_date_fixed": null,
"due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
"due_date_from_inherited_source": "2018-07-31",
"created_at": "2018-07-17T13:36:22.770Z",
"updated_at": "2018-07-18T12:22:05.239Z",
"closed_at": "2018-08-18T12:22:05.239Z",
"labels": [],
"upvotes": 4,
"downvotes": 0,
"color": "#1068bf",
"_links":{
"self": "http://gitlab.example.com/api/v4/groups/7/epics/6",
"epic_issues": "http://gitlab.example.com/api/v4/groups/7/epics/6/issues",
"group":"http://gitlab.example.com/api/v4/groups/7",
"parent": "http://gitlab.example.com/api/v4/groups/7/epics/4"
}
}
에픽 업데이트#
그룹의 지정된 에픽을 업데이트합니다.
PUT /groups/:id/epics/:epic_iid
| 속성 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
id |
정수 또는 문자열 | 예 | 그룹의 ID 또는 URL-인코딩된 경로. |
epic_iid |
정수 또는 문자열 | 예 | 에픽의 내부 ID. |
add_labels |
문자열 | 아니요 | 이슈에 추가할 쉼표로 구분된 라벨 이름. |
confidential |
부울 | 아니요 | 에픽을 기밀로 설정할지 여부. |
description |
문자열 | 아니요 | 에픽의 설명. 최대 1,048,576자. |
due_date_fixed |
문자열 | 아니요 | 에픽의 고정 마감 날짜. |
due_date_is_fixed |
부울 | 아니요 | 마감 날짜가 due_date_fixed 또는 마일스톤에서 가져와야 하는지 여부. |
labels |
문자열 | 아니요 | 이슈의 쉼표로 구분된 라벨 이름. 빈 문자열로 설정하면 모든 라벨이 제거됩니다. |
parent_id |
정수 또는 문자열 | 아니요 | 부모 에픽의 ID. |
remove_labels |
문자열 | 아니요 | 이슈에서 제거할 쉼표로 구분된 라벨 이름. |
start_date_fixed |
문자열 | 아니요 | 에픽의 고정 시작 날짜. |
start_date_is_fixed |
부울 | 아니요 | 시작 날짜가 start_date_fixed 또는 마일스톤에서 가져와야 하는지 여부. |
state_event |
문자열 | 아니요 | 에픽의 상태 이벤트. 에픽을 닫으려면 close, 다시 열려면 reopen. |
title |
문자열 | 아니요 | 에픽의 제목. |
updated_at |
문자열 | 아니요 | 에픽이 업데이트된 날짜. ISO 8601 형식의 날짜 시간 문자열(2016-03-11T03:45:40Z). 관리자 또는 프로젝트/그룹 소유자 권한이 필요합니다. |
color |
문자열 | 아니요 | 에픽의 색상. epic_highlight_color라는 기능 플래그 뒤에 있습니다(기본값: 비활성화). |
curl --request PUT \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/1/epics/5?title=New%20Title&parent_id=29"
응답 예시:
{
"id": 33,
"work_item_id": 1019,
"iid": 6,
"group_id": 7,
"parent_id": 29,
"parent_iid": 4,
"title": "New Title",
"description": "Epic description",
"state": "opened",
"imported": false,
"imported_from": "none",
"confidential": "false",
"web_url": "http://gitlab.example.com/groups/test/-/epics/6",
"reference": "&6",
"references": {
"short": "&6",
"relative": "&6",
"full": "test&6"
},
"author": {
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"state" : "active",
"web_url" : "https://gitlab.example.com/eileen.lowe",
"id" : 18,
"username" : "eileen.lowe"
},
"start_date": null,
"start_date_is_fixed": false,
"start_date_fixed": null,
"start_date_from_milestones": null, //deprecated in favor of start_date_from_inherited_source
"start_date_from_inherited_source": null,
"end_date": "2018-07-31", //deprecated in favor of due_date
"due_date": "2018-07-31",
"due_date_is_fixed": false,
"due_date_fixed": null,
"due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
"due_date_from_inherited_source": "2018-07-31",
"created_at": "2018-07-17T13:36:22.770Z",
"updated_at": "2018-07-18T12:22:05.239Z",
"closed_at": "2018-08-18T12:22:05.239Z",
"labels": [],
"upvotes": 4,
"downvotes": 0,
"color": "#1068bf"
}
에픽 삭제#
히스토리
- GitLab 16.11에서 변경되었습니다. GitLab 16.10 이하에서 에픽을 삭제하면 모든 자식 에픽과 그 하위 항목도 삭제됩니다. 필요한 경우 삭제 전에 부모 에픽에서 자식 에픽을 제거할 수 있습니다.
그룹에서 지정된 에픽을 삭제합니다.
DELETE /groups/:id/epics/:epic_iid
| 속성 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
id |
정수 또는 문자열 | 예 | 그룹의 ID 또는 URL-인코딩된 경로. |
epic_iid |
정수 또는 문자열 | 예 | 에픽의 내부 ID. |
curl --request DELETE \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/1/epics/5"
에픽에 대한 할 일 항목 생성#
지정된 에픽에 대해 현재 사용자의 할 일 항목을 생성합니다. 해당 에픽에 대한 할 일 항목이 이미 존재하는 경우 상태 코드 304가 반환됩니다.
POST /groups/:id/epics/:epic_iid/todo
| 속성 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
id |
정수 또는 문자열 | 예 | 그룹의 ID 또는 URL-인코딩된 경로. |
epic_iid |
정수 | 예 | 그룹 에픽의 내부 ID. |
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/1/epics/5/todo"
응답 예시:
{
"id": 112,
"group": {
"id": 1,
"name": "Gitlab",
"path": "gitlab",
"kind": "group",
"full_path": "base/gitlab",
"parent_id": null
},
"author": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "https://gitlab.example.com/root"
},
"action_name": "marked",
"target_type": "epic",
"target": {
"id": 30,
"iid": 5,
"group_id": 1,
"title": "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.",
"description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
"author":{
"id": 7,
"name": "Pamella Huel",
"username": "arnita",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",
"web_url": "http://gitlab.example.com/arnita"
},
"web_url": "http://gitlab.example.com/groups/test/-/epics/5",
"reference": "&5",
"references": {
"short": "&5",
"relative": "&5",
"full": "test&5"
},
"start_date": null,
"end_date": null,
"created_at": "2018-01-21T06:21:13.165Z",
"updated_at": "2018-01-22T12:41:41.166Z",
"closed_at": "2018-08-18T12:22:05.239Z"
},
"target_url": "https://gitlab.example.com/groups/epics/5",
"body": "Vel voluptas atque dicta mollitia adipisci qui at.",
"state": "pending",
"created_at": "2016-07-01T11:09:13.992Z"
}