Эпик — рабочий элемент группы или проекта. Он объединяет задачи и другие эпики общей целью, берёт у них даты начала и завершения и показывает, какие элементы блокируют другие.

Требования

Эпики группы видят её участники, эпики проекта — участники проекта. Чтобы создавать и изменять эпики, нужна роль «Планировщик», «Наблюдатель» или выше в группе или проекте.

Создание эпика

  1. Откройте группу и перейдите в «Планирование» → «Рабочие элементы».
  2. Нажмите «Новый элемент». Форма откроется с группой в поле «Группа или проект»; выберите «Эпик» в поле «Тип».
  3. Введите заголовок. При необходимости заполните описание, ответственных, метки, этап, даты и цвет.
  4. Нажмите «Создать эпик».

Создание эпика в группе

Отдельной страницы эпиков нет: список эпиков группы — это «Рабочие элементы» с фильтром по типу «Эпик». В нём видны и эпики подгрупп и проектов группы.

Чтобы изменить несколько элементов списка сразу, нажмите «Массовое редактирование», отметьте элементы и задайте поля, которые нужно изменить: состояние, ответственного, метки, подписку, конфиденциальность, этап, родителя или состояние работоспособности. Затем нажмите «Обновить выбранные». Эпики и задачи меняются вместе, например их можно поставить под один родительский эпик.

Эпики в проекте

Чтобы создать эпик в проекте, откройте проект, перейдите в «Планирование» → «Рабочие элементы», нажмите «Новый элемент» и выберите «Эпик» в поле «Тип». Эпики проекта находятся в «Планирование» → «Рабочие элементы» с фильтром по типу «Эпик». Родителем эпика проекта может быть эпик группы, а эпик группы может содержать эпики проектов.

На досках задач проекта («Планирование» → «Доски задач») эпики проекта отображаются карточками рядом с задачами. Карточка отображается в списке, соответствующем её метке. Если метки списка нет, карточка находится в списке «Открыто». Карточки закрытых эпиков находятся в списке «Закрыто».

Карточку можно перенести в другой список и открыть на боковой панели. Цвет эпика отображается полосой по левому краю карточки. Фильтр «Тип» на доске отбирает эпики или задачи. Доска задач группы показывает так же эпики группы, её подгрупп и проектов.

Чтобы превратить задачу в эпик того же проекта, откройте задачу, выберите «Больше действий» → «Изменить тип», выберите «Эпик» и подтвердите. Эпик так же превращается обратно в задачу. Задача с подзадачами не становится эпиком, а эпик с дочерними элементами не становится задачей: сначала уберите дочерние элементы. Эпик, ставший задачей, сохраняет показанные даты как фиксированные.

Чтобы превратить задачу в эпик, нужна роль, с которой вы можете создавать эпики в этом проекте и редактировать задачу.

Эпики можно загрузить из 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_filteron_track, needs_attention, at_risk, none или any
not[health_status_filter][]on_track, needs_attention, at_risk; исключает элементы с этими состояниями
order_byweight, health_status, blocking_issues и другие; элементы без веса или состояния идут последними

API задач тоже сортирует по блокирующим связям: GET /api/v4/projects/<PROJECT_ID>/issues?order_by=blocking_issues.