Эпик — рабочий элемент группы или проекта. Он объединяет задачи и другие эпики общей целью, берёт у них даты начала и завершения и показывает, какие элементы блокируют другие.
Требования
Эпики группы видят её участники, эпики проекта — участники проекта. Чтобы создавать и изменять эпики, нужна роль «Планировщик», «Наблюдатель» или выше в группе или проекте.
Создание эпика
- Откройте группу и перейдите в «Планирование» → «Рабочие элементы».
- Нажмите «Новый элемент». Форма откроется с группой в поле «Группа или проект»; выберите «Эпик» в поле «Тип».
- Введите заголовок. При необходимости заполните описание, ответственных, метки, этап, даты и цвет.
- Нажмите «Создать эпик».

Отдельной страницы эпиков нет: список эпиков группы — это «Рабочие элементы» с фильтром по типу «Эпик». В нём видны и эпики подгрупп и проектов группы.
Чтобы изменить несколько элементов списка сразу, нажмите «Массовое редактирование», отметьте элементы и задайте поля, которые нужно изменить: состояние, ответственного, метки, подписку, конфиденциальность, этап, родителя или состояние работоспособности. Затем нажмите «Обновить выбранные». Эпики и задачи меняются вместе, например их можно поставить под один родительский эпик.
Эпики в проекте
Чтобы создать эпик в проекте, откройте проект, перейдите в «Планирование» → «Рабочие элементы», нажмите «Новый элемент» и выберите «Эпик» в поле «Тип». Эпики проекта находятся в «Планирование» → «Рабочие элементы» с фильтром по типу «Эпик». Родителем эпика проекта может быть эпик группы, а эпик группы может содержать эпики проектов.
На досках задач проекта («Планирование» → «Доски задач») эпики проекта отображаются карточками рядом с задачами. Карточка отображается в списке, соответствующем её метке. Если метки списка нет, карточка находится в списке «Открыто». Карточки закрытых эпиков находятся в списке «Закрыто».
Карточку можно перенести в другой список и открыть на боковой панели. Цвет эпика отображается полосой по левому краю карточки. Фильтр «Тип» на доске отбирает эпики или задачи. Доска задач группы показывает так же эпики группы, её подгрупп и проектов.
Чтобы превратить задачу в эпик того же проекта, откройте задачу, выберите «Больше действий» → «Изменить тип», выберите «Эпик» и подтвердите. Эпик так же превращается обратно в задачу. Задача с подзадачами не становится эпиком, а эпик с дочерними элементами не становится задачей: сначала уберите дочерние элементы. Эпик, ставший задачей, сохраняет показанные даты как фиксированные.
Чтобы превратить задачу в эпик, нужна роль, с которой вы можете создавать эпики в этом проекте и редактировать задачу.
Эпики можно загрузить из CSV-файла на странице «Рабочие элементы» проекта: в столбце type укажите epic.
При экспорте и импорте проекта эпики проекта сохраняют тип «Эпик».
Дочерние элементы
Эпик может содержать:
- другие эпики, до семи уровней вложенности;
- задачи;
- заявки.

Чтобы добавить дочерний элемент, откройте эпик и нажмите кнопку добавления в блоке «Дочерние элементы». Новый дочерний эпик создаётся в группе или проекте, выбранном в поле «Группа»: в списке есть группа родительского эпика, её подгруппы и проекты. Если родительский эпик находится в проекте, список включает группу этого проекта, её подгруппы и проекты.
Родителя можно указать и со стороны дочернего элемента: откройте задачу и выберите эпик в поле «Родитель» или выполните быструю команду /set_parent <эпик>. В задаче то же делает команда /epic <эпик>.
Даты
Даты начала и завершения эпика бывают фиксированными или унаследованными. Выберите вариант в блоке «Даты» на боковой панели эпика:
- «Фиксированные»: даты вводятся вручную через «Редактировать»;
- «Унаследованные»: дата начала — самая ранняя, а дата завершения — самая поздняя среди дат прямых дочерних элементов и их этапов. Закрытые дочерние элементы тоже учитываются.
Унаследованные даты передаются вверх по иерархии: изменение в задаче сдвигает даты её эпика и каждого родительского эпика с унаследованными датами. Пересчёт выполняется в фоне и занимает несколько секунд.
Учёт времени вверх не передаётся: оценка и затраченное время эпика свои, а не сумма значений дочерних элементов.
Блокирующие связи
Блокирующие связи доступны для всех типов рабочих элементов, в том числе эпиков, задач, подзадач и заявок.
Чтобы добавить блокирующую связь, откройте элемент, добавьте элемент в блоке «Связанные элементы» и выберите «блокирует» или «заблокировано». Те же связи добавляют быстрые команды /blocks <элемент> и /blocked_by <элемент>. В обоих элементах появляется системная заметка, и каждый показывает связь в группе «Блокирует» или «Заблокировано».
Блокирующие связи видны в интерфейсе так:
- в списке рабочих элементов, среди дочерних элементов эпика и на карточках досок задач отображается значок блокировки с числом открытых связанных элементов, к которым у вас есть доступ;
- при закрытии заблокированного элемента запрашивается подтверждение;
- в списке рабочих элементов вариант «Отображать» → «Сортировка» → «Блокировка» упорядочивает элементы по числу открытых элементов, которые блокирует каждый из них.
Цвет
У каждого эпика есть цвет, по умолчанию синий #1068bf. Цвет отображается полосой по левому краю строки эпика в списке рабочих элементов и среди дочерних элементов родительского эпика.

Чтобы изменить цвет, нажмите «Редактировать» в блоке «Цвет» на боковой панели эпика и выберите предложенный цвет или введите шестнадцатеричный код, например #c91c00. После изменения цвета в эпике появляется системная заметка.
Вес
У задач, подзадач, заявок и эпиков есть вес, целое число от 0 до 2147483647 включительно. Чтобы задать его, нажмите «Редактировать» в блоке «Вес» на боковой панели элемента и введите число; «Удалить вес» удаляет его. Вес можно задать и в форме создания или быстрыми командами /weight <число> и /clear_weight. После изменения веса в элементе появляется системная заметка.
Чтобы задать вес, нужна роль «Планировщик» или выше.
Родитель суммирует веса прямых дочерних элементов. Если у дочернего элемента не задан вес, в расчёте используется сумма весов его дочерних элементов.
Рядом с блоком «Дочерние элементы» родитель показывает сумму и долю в процентах, которая приходится на закрытые дочерние элементы; при наведении на процент видны оба числа, например 3/8 вес выполнен. Открытый дочерний элемент со своим весом считается невыполненным, даже если часть его дочерних элементов закрыта. Сумма пересчитывается в фоне: чтобы увидеть её после изменения дочернего элемента, обновите страницу.

Вес также отображается:
- в списке рабочих элементов, в каждой строке; вариант «Отображать» → «Сортировка» → «Вес» упорядочивает элементы по весу, элементы без веса идут последними;
- на карточках досок задач; заголовок каждого списка показывает общий вес его элементов;
- на странице этапа («Планирование» → «Этапы»), где «Общий вес» суммирует веса элементов, к которым у вас есть доступ.
Состояние работоспособности
Для задач, заявок и эпиков можно указать состояние работоспособности: «По плану», «Требует внимания» или «Под угрозой». Чтобы задать состояние, нужна роль «Планировщик» или выше.
Нажмите «Редактировать» в блоке «Состояние работоспособности» на боковой панели элемента и выберите состояние. Чтобы удалить его, нажмите «Очистить».
Состояние можно задать в форме создания элемента или сразу для нескольких элементов через «Массовое редактирование» в списке рабочих элементов. Быстрая команда /health_status <on_track|needs_attention|at_risk> задаёт состояние, а /clear_health_status удаляет его.
После изменения состояния в элементе появляется системная заметка.
Состояние закрытого элемента изменить нельзя: «Редактировать» и быстрые команды недоступны, пока элемент не открыт снова.
Рядом с блоком «Дочерние элементы» эпик показывает, сколько его открытых прямых дочерних элементов находится в каждом состоянии. Закрытые дочерние элементы и элементы следующих уровней не учитываются.

Состояние работоспособности также отображается:
- в списке рабочих элементов, в каждой строке; вариант «Отображать» → «Сортировка» → «Состояние» упорядочивает элементы по состоянию, элементы без состояния идут последними;
- в фильтре списка: «Состояние работспособности» «является» состоянием, «Нет» или «Любой» либо «не является одним из» состояний;
- на карточках досок задач и среди дочерних элементов родителя.
Уведомления
На уровне уведомлений «Настраиваемый» в группе, проекте или глобальных настройках отметьте «Эпик создан», чтобы получать письма о новых эпиках. Письма о новых эпиках также приходят, если отмечено событие «Обсуждение создано». Если для группы выбран уровень «Отслеживать», вы получаете письма об эпиках этой группы.

Поиск
Если в инстансе включён расширенный поиск, эпики находятся в области «Рабочие элементы»; фильтр «Тип» оставляет в результатах только эпики. Поиск в группе находит эпики группы, её подгрупп и проектов. Поиск в проекте находит только эпики этого проекта.
API
GraphQL
GraphQL API по адресу https://<HOST>/api/graphql работает с эпиками, весом, состоянием работоспособности и блокирующими связями:
| Задача | GraphQL |
|---|---|
| Задать цвет, вес и состояние работоспособности | colorWidget { color }, weightWidget { weight } и healthStatusWidget { healthStatus } в мутациях workItemCreate и workItemUpdate; healthStatusWidget в workItemBulkUpdate |
| Прочитать их | виджеты WorkItemWidgetColor, WorkItemWidgetWeight (weight, rolledUpWeight, rolledUpCompletedWeight) и WorkItemWidgetHealthStatus (healthStatus, rolledUpHealthStatus) |
| Добавить и удалить блокирующие связи | мутация workItemAddLinkedItems с linkType: BLOCKS или BLOCKED_BY и workItemRemoveLinkedItems |
| Прочитать блокирующие связи | linkedItems(filter: BLOCKS) и linkedItems(filter: BLOCKED_BY); blockedByCount и blockingCount в виджете связанных элементов |
| Фильтровать и сортировать списки | healthStatusFilter (onTrack, needsAttention, atRisk, NONE или ANY) и not: { healthStatusFilter: [...] }; значения sort WEIGHT_ASC, WEIGHT_DESC, HEALTH_STATUS_ASC, HEALTH_STATUS_DESC, BLOCKING_ISSUES_ASC и BLOCKING_ISSUES_DESC |
Значения полей rolledUpWeight и rolledUpCompletedWeight ограничены сверху числом 2147483647. Чтобы получить полные суммы, используйте REST API.
Например, чтобы задать вес рабочего элемента:
mutation {
workItemUpdate(input: { id: "gid://gitlab/WorkItem/<ID>", weightWidget: { weight: 3 } }) {
workItem { widgets { ... on WorkItemWidgetWeight { weight } } }
errors
}
}REST
REST API рабочих элементов по умолчанию выключен. Чтобы им пользоваться, администратор включает флаг work_item_rest_api, как описано на странице Ранний доступ; без него методы ниже отвечают 404. Методы доступны в контекстах projects, groups и namespaces; в примерах — проект.
Чтобы получить вес, его суммы и состояние работспособности, перечислите их в features:
curl --header "PRIVATE-TOKEN: <TOKEN>" \
"https://<HOST>/api/v4/projects/<PROJECT_ID>/-/work_items/<WORK_ITEM_IID>?features=weight,health_status,color"В ответе features.weight содержит weight, rolled_up_weight и rolled_up_completed_weight, features.health_status — on_track, needs_attention, at_risk или null, а features.color — цвет.
Чтобы задать вес и состояние работоспособности, передайте features при создании или изменении рабочего элемента:
curl --request PATCH --header "PRIVATE-TOKEN: <TOKEN>" --header "Content-Type: application/json" \
--data '{"features": {"weight": {"weight": 3}, "health_status": {"health_status": "at_risk"}}}' \
"https://<HOST>/api/v4/projects/<PROJECT_ID>/-/work_items/<WORK_ITEM_IID>"Чтобы очистить вес и состояние работоспосбности, задайте null в полях features.weight.weight и features.health_status.health_status:
curl --request PATCH --header "PRIVATE-TOKEN: <TOKEN>" --header "Content-Type: application/json" \
--data '{"features": {"weight": {"weight": null}, "health_status": {"health_status": null}}}' \
"https://<HOST>/api/v4/projects/<PROJECT_ID>/-/work_items/<WORK_ITEM_IID>"Чтобы задать цвет эпика, передайте его шестнадцатеричный код в features.color.color; для возврата к цвету по умолчанию укажите #1068bf.
Чтобы добавить связи, передайте ID (не IID) до 10 рабочих элементов и тип связи: relates_to (по умолчанию), blocks или is_blocked_by. Ответ — 201 со списком связанных элементов. Если хотя бы одного ID нет, ответ — 404, и ни одна связь не добавляется:
curl --request POST --header "PRIVATE-TOKEN: <TOKEN>" --header "Content-Type: application/json" \
--data '{"work_items_ids": [<ID>], "link_type": "blocks"}' \
"https://<HOST>/api/v4/projects/<PROJECT_ID>/-/work_items/<WORK_ITEM_IID>/linked_items"Чтобы удалить связь, передайте ID связанного рабочего элемента. Ответ — 204:
curl --request DELETE --header "PRIVATE-TOKEN: <TOKEN>" \
"https://<HOST>/api/v4/projects/<PROJECT_ID>/-/work_items/<WORK_ITEM_IID>/linked_items/<LINKED_ITEM_ID>"GET …/linked_items возвращает список связей, а его параметр link_type оставляет связи одного типа.
Где:
<TOKEN>— токен для аутентификации в Deckhouse Code;<HOST>— адрес инстанса Deckhouse Code;<PROJECT_ID>— ID проекта или его путь в URL-кодировке;<WORK_ITEM_IID>— внутренний ID рабочего элемента в проекте;<ID>,<LINKED_ITEM_ID>— ID рабочего элемента из поляid.
Список рабочих элементов, GET …/-/work_items, принимает параметры:
| Параметр | Значения |
|---|---|
health_status_filter | on_track, needs_attention, at_risk, none или any |
not[health_status_filter][] | on_track, needs_attention, at_risk; исключает элементы с этими состояниями |
order_by | weight, health_status, blocking_issues и другие; элементы без веса или состояния идут последними |
API задач тоже сортирует по блокирующим связям: GET /api/v4/projects/<PROJECT_ID>/issues?order_by=blocking_issues.