Help us learn about your current experience with the documentation. Take the survey.

Epic API (已弃用)

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

Epic REST API 在 GitLab 17.0 中已被弃用， 并计划在 API v5 中移除。 从 GitLab 17.4 到 18.0，如果启用了epic 的新外观，以及在 GitLab 18.1 及更高版本中， 请改用 Work Items API。更多信息，请参阅将 epic API 迁移到工作项。 此更改是一个破坏性更改。

每个对 epic 的 API 调用都必须经过身份验证。

如果用户不是私有组的成员，对该组的 GET 请求将返回 404 状态码。

如果 epic 功能不可用，将返回 403 状态码。

Epic 问题 API

epic 问题 API 允许您与与 epic 关联的问题进行交互。

里程碑日期集成

因为开始日期和截止日期可以动态地从相关问题里程碑获取， 当用户具有编辑权限时，会显示额外的字段。这包括两个布尔字段 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。
  • start_date_from_milestones 已被弃用，请使用 start_date_from_inherited_source
  • due_date_from_milestones 已被弃用，请使用 due_date_from_inherited_source

Epic 分页

默认情况下，GET 请求一次返回 20 个结果，因为 API 结果 是分页的。

阅读更多关于分页的信息。

在 GitLab 12.6 及更高版本中， 响应中的 reference 属性已被弃用，请使用 references。

references.relative 是相对于请求 epic 的组的。当 epic 从其原始组获取时，relative 格式与 short 格式相同。 当跨组请求 epic 时，relative 格式应与 full 格式相同。

列出组的 epic

获取所请求组及其子组的所有 epic。

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 integer/string 是 组的 ID 或URL 编码路径
author_id integer 否 返回由给定用户 id 创建的 epic
author_username string 否 返回由给定 username 的用户创建的 epic。
labels string 否 返回匹配逗号分隔的标签名称列表的 epic。可以使用 epic 组或父组的标签名称
with_labels_details boolean 否 如果为 true，响应会在 labels 字段中返回每个标签的更多详细信息：:name、:color、:description、:description_html、:text_color。默认为 false。
order_by string 否 按 created_at、updated_at 或 title 字段排序返回 epic。默认为 created_at
sort string 否 按 asc 或 desc 顺序返回 epic。默认为 desc
search string 否 根据 title 和 description 搜索 epic
state string 否 根据 state 搜索 epic，可能的过滤器：opened、closed 和 all，默认：all
created_after datetime 否 返回在给定时间或之后创建的 epic。期望为 ISO 8601 格式 (2019-03-15T08:00:00Z)
created_before datetime 否 返回在给定时间或之前创建的 epic。期望为 ISO 8601 格式 (2019-03-15T08:00:00Z)
updated_after datetime 否 返回在给定时间或之后更新的 epic。期望为 ISO 8601 格式 (2019-03-15T08:00:00Z)
updated_before datetime 否 返回在给定时间或之前更新的 epic。期望为 ISO 8601 格式 (2019-03-15T08:00:00Z)
include_ancestor_groups boolean 否 包含所请求组的祖先组的 epic。默认为 false
include_descendant_groups boolean 否 包含所请求组的后代组的 epic。默认为 true
my_reaction_emoji string 否 返回经过身份验证的用户用给定表情符号做出反应的 epic。None 返回未做出反应的 epic。Any 返回至少有一个反应的 epic。
not Hash 否 返回不匹配提供参数的 epic。接受：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,
  "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,
  "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"
  }
  }
]

单个 epic

获取单个 epic

GET /groups/:id/epics/:epic_iid
属性 类型 必需 描述
id integer/string 是 组的 ID 或URL 编码路径
epic_iid integer/string 是 epic 的内部 ID。 
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/epics/5"

示例响应：

{
  "id": 30,
  "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
  }
}

新建 epic

创建一个新的 epic。

从 GitLab 11.3 开始，不应再直接分配 start_date 和 end_date，因为它们现在表示复合值。您可以通过 *_is_fixed 和 *_fixed 字段来配置它。

POST /groups/:id/epics
属性 类型 必需 描述
id integer/string 是 组的 ID 或URL 编码路径
title string 是 epic 的标题
labels string 否 逗号分隔的标签列表
description string 否 epic 的描述。限制为 1,048,576 个字符。
color string 否 epic 的颜色。位于名为 epic_highlight_color 的功能标志后面（默认禁用）
confidential boolean 否 epic 是否应该是机密的
created_at string 否 epic 的创建时间。日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z。需要管理员或项目/组所有者权限
start_date_is_fixed boolean 否 开始日期是否应从 start_date_fixed 或从里程碑获取
start_date_fixed string 否 epic 的固定开始日期
due_date_is_fixed boolean 否 截止日期是否应从 due_date_fixed 或从里程碑获取
due_date_fixed string 否 epic 的固定截止日期
parent_id integer/string 否 父 epic 的 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,
  "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"
  }
}

更新 epic

更新一个 epic。

PUT /groups/:id/epics/:epic_iid
属性 类型 必需 描述
id integer/string 是 组的 ID 或URL 编码路径
epic_iid integer/string 是 epic 的内部 ID
add_labels string 否 要添加到问题的逗号分隔标签名称。
confidential boolean 否 epic 是否应该是机密的
description string 否 epic 的描述。限制为 1,048,576 个字符。
due_date_fixed string 否 epic 的固定截止日期
due_date_is_fixed boolean 否 截止日期是否应从 due_date_fixed 或从里程碑获取
labels string 否 问题的逗号分隔标签名称。设置为空字符串以取消分配所有标签。
parent_id integer/string 否 父 epic 的 ID。
remove_labels string 否 要从问题中删除的逗号分隔标签名称。
start_date_fixed string 否 epic 的固定开始日期
start_date_is_fixed boolean 否 开始日期是否应从 start_date_fixed 或从里程碑获取
state_event string 否 epic 的状态事件。设置 close 以关闭 epic，设置 reopen 以重新打开它
title string 否 epic 的标题
updated_at string 否 epic 的更新时间。日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z。需要管理员或项目/组所有者权限
color string 否 epic 的颜色。位于名为 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,
  "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"
}

删除 epic

删除一个 epic

DELETE /groups/:id/epics/:epic_iid
属性 类型 必需 描述
id integer/string 是 组的 ID 或URL 编码路径
epic_iid integer/string 是 epic 的内部 ID。 
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/epics/5"

创建待办事项

为当前用户在 epic 上手动创建一个待办事项。如果 该用户在该 epic 上已经存在待办事项，则返回状态码 304。

POST /groups/:id/epics/:epic_iid/todo
属性 类型 必需 描述
id integer/string 是 组的 ID 或URL 编码路径
epic_iid integer 是 组的 epic 的内部 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"
}