Интеграция с Ягой

Яга может служить внешней системой управления задачами проекта. Deckhouse Code превращает коды задач в ссылки на Ягу, добавляет комментарии к задачам и может проверять коммиты и запросы на слияние по этим задачам.

Предварительные требования

Администратор включил флаг функций fe_jaga_integration так, как описано на странице Ранний доступ.

Для настройки интеграции в проекте нужна роль «Мейнтейнер» или «Владелец» в этом проекте. Для настройки в группе нужна роль «Владелец»; настройки инстанса изменяет администратор.

Используйте учётную запись Яги с доступом к проектам, задачи которых будет обрабатывать интеграция. Действия в Яге выполняются от имени этой учётной записи. Интеграция не ограничивает коды задач конкретными проектами Яги, поэтому предоставьте учётной записи доступ только к проектам, задачи которых требуется изменять.

В проекте может быть активна только одна внешняя система управления задачами: Deckhouse Code не сохраняет интеграцию с Ягой в проекте, где активна другая система. Активная система, унаследованная от группы или инстанса, тоже мешает сохранению. Перед настройкой Яги откройте эту систему в проекте, выберите «Использовать пользовательские настройки» и отключите её.

Если Яга находится в локальной сети, попросите администратора разрешить обращения к её адресу в разделе «Admin» → «Настройки» → «Сеть» → «Исходящие запросы».

Настройка интеграции

1. Откройте проект и перейдите в раздел «Настройки» → «Интеграции» → «Jaga».
2. В разделе «Включить интеграцию» установите флажок «Активные».
3. В поле «Web URL» укажите базовый адрес Яги, например https://jaga.example.com. В полях «Электронная почта» и «Пароль» введите данные учётной записи Яги. Для обращений к API Deckhouse Code использует адрес <Web URL>/backend.
4. В разделе «Упоминания» выберите источники комментариев в Яге: «Коммиты», «Запросы на слияние» и «Задачи GitLab». В поле «Подробность комментария» выберите заголовок или полный текст.
5. В разделе «Задачи Jaga» заполните поля «Регулярное выражение задачи Jaga» или «Префикс задачи Jaga», если требуется другой шаблон кодов. По умолчанию код задачи распознаётся, если он начинается с заглавной латинской буквы, за которой следуют одна или несколько заглавных латинских букв, цифр или подчёркиваний, затем дефис и число, например JAGA-1.
6. При необходимости настройте разделы «Умные коммиты» и «Закрытие задач» для изменения задач через коммиты.
7. Нажмите «Сохранить изменения». На странице группы или инстанса подтвердите сохранение кнопкой «Сохранить» в окне «Сохранить настройки?». На странице проекта или группы нажмите «Проверить настройки», чтобы проверить адрес и учётные данные.

Интеграцию также можно настроить для группы или инстанса. Проекты наследуют эти настройки и могут задать собственные. При смене «Web URL» сохранённый пароль удаляется: введите его заново перед сохранением. При использовании http:// учётные данные и токены передаются без шифрования.

По умолчанию в разделе «Упоминания» выбраны все три источника, а в поле «Подробность комментария» — «Заголовок коммита или запроса на слияние». Умные коммиты и переходы Jaga выключены. При включении умных коммитов команда #comment и команда статуса включены, #time выключена, а в поле «Вид работы» указано develop.

Ссылки и упоминания задач

Код задачи вида JAGA-1 в задаче, запросе на слияние, комментарии или сообщении коммита становится ссылкой на <Web URL>/browse/JAGA-1. В боковом меню проекта появляется ссылка «Jaga» на адрес из поля «Web URL».

Для источников, выбранных в разделе «Упоминания», Deckhouse Code добавляет к задаче Яги комментарий со ссылкой на объект в Deckhouse Code. Несуществующая задача пропускается. Повторное упоминание того же объекта не создаёт новый комментарий. Комментарии добавляются от имени учётной записи Яги из настроек интеграции.

Комментарии об упоминании, умные коммиты и закрытие задачи коммитом, отправленным в ветку по умолчанию, находят код, только если в тексте есть код вида JAGA-1 или другая ссылка на объект, например #1 или URL. Код вида JAGA-1 — это заглавная латинская буква, за которой могут следовать заглавные латинские буквы, цифры или подчёркивания, затем дефис и число. Код другого вида, заданный собственным регулярным выражением, в тексте без такой ссылки молча игнорируется. Ссылки, созданные из кодов задач, правила отправки изменений, проверка при слиянии и закрытие через запрос на слияние используют заданный шаблон напрямую.

Умные коммиты

В разделе «Умные коммиты» установите флажок «Выполнять команды из коммитов, у автора которых есть учётная запись Jaga», затем включите нужные команды. Электронная почта автора, записанная в коммите, должна соответствовать учётной записи Яги. Действия выполняет учётная запись из настроек интеграции.

Поместите код задачи и команды в одну строку сообщения коммита:

JAGA-1 #comment Исправлена форма входа #на-проверке #time 1h 30m

• #comment добавляет следующий за командой текст в комментарий к задаче.
• #на-проверке переводит задачу в доступный статус «На проверке». Подставьте название статуса из своего процесса в Яге, заменив пробелы дефисами; регистр не учитывается. Командой статуса считается только первое #слово в коммите, кроме #comment и #time; следующие игнорируются.
• #time списывает рабочее время, если команда включена и указан «Вид работы». Единицы времени: w, d, h и m; день равен восьми часам, неделя — пяти дням. Запись больше 40 часов, например 6d или 1w 1h, игнорируется, время по ней не списывается. Яга записывает время на учётную запись интеграции.

Команды выполняются при отправке коммита, в том числе в ветки, отличные от ветки по умолчанию. Обрабатываются только последние 100 коммитов одной отправки; это относится и к комментариям об упоминании, и к закрытию задач коммитом. Если у автора коммита нет учётной записи Яги, команды пропускаются. После выполнения команд комментарий добавляется и при снятом флажке «Коммиты» в разделе «Упоминания».

Если задачу нельзя перевести в названный статус — Яга отклоняет смену, из текущего статуса задачи нет перехода в него или Яга не отвечает, — записи #time и комментарий этого коммита тоже пропускаются. Они выполняются, когда Deckhouse Code обработает коммит в следующий раз, например при отправке коммита в новую ветку или при попадании в ветку по умолчанию. Повторная отправка того же коммита в ту же ветку его не обрабатывает. Если команда статуса не совпадает ни с одним статусом проекта Яги, например #wip, она остаётся обычным текстом, а #comment и #time выполняются.

Закрытие задач Яги

В разделе «Закрытие задач» установите флажок «Включить переходы Jaga», чтобы менять статус задачи, когда закрывающий коммит или запрос на слияние попадает в ветку по умолчанию. Добавьте запись вида Closes JAGA-1 или Fixes JAGA-1 в сообщение коммита или, для запроса на слияние, в его заголовок, описание или сообщения его коммитов. Если задан префикс задачи, включите его в запись.

Выберите «Перевести в «Готово»» для перехода в первый доступный статус категории «Готово». Выберите «Перевести по целевым статусам» и перечислите названия статусов в порядке процесса через запятую или точку с запятой (подсказка под полем называет только запятую) для прохождения нескольких доступных переходов. Если Яга отклоняет переход, задача остаётся в последнем достигнутом статусе. После перехода в категорию «Готово» Deckhouse Code добавляет комментарий со ссылкой на закрывающий коммит.

Правила отправки изменений

Настройте проверки Яги в разделе «Настройки» → «Репозиторий» → «Push-правила» на уровне проекта, группы или инстанса, как описано на странице Правила отправки изменений. Интеграция с Ягой должна быть активна на этом уровне либо унаследована. По умолчанию правила выключены:

• «Отклонять коммиты с несуществующей задачей Jaga» требует, чтобы каждый новый коммит называл хотя бы одну существующую задачу.
• «Отклонять коммиты, если email автора не принадлежит исполнителю задачи Jaga» требует, чтобы каждая существующая задача, названная в коммите, была назначена на электронную почту автора коммита напрямую или через группу Яги. Коммит отклоняется, если у названной задачи нет исполнителей или ни у одного пользователя Яги нет такой почты.
• «Статусы задач Jaga, в которых разрешён push» требует, чтобы каждая существующая задача, названная в коммите, находилась в одном из перечисленных статусов. Поле принимает названия статусов через запятую или точку с запятой (подсказка под полем называет только запятую); регистр не учитывается. Как и у каждого правила отправки изменений, у него есть список со значениями «Включен» и «Отключен». Правило действует, только если выбрано «Включен» и в поле указан хотя бы один статус; пустое поле оставляет правило выключенным.

При любом включённом правиле Яги каждый новый коммит в отправляемых ветках и тегах должен называть хотя бы одну задачу, которая существует в Яге. Код, для которого в Яге нет задачи, не приводит к отклонению, если коммит называет и существующую задачу. Коммиты из веб-редактора и коммиты слияния тоже проверяются. Первый коммит, созданный через веб-интерфейс для заполнения пустого репозитория, например начальный README, не проверяется.

Отправка изменений также отклоняется, если:

• в ней названо более 100 различных кодов задач;
• Яга недоступна или отвечает ошибкой — пока Яга не начнёт отвечать без ошибок;
• Яга отклоняет учётные данные интеграции — до исправления учётных данных или правил;
• правило, унаследованное от группы или инстанса, осталось включённым после отключения интеграции в проекте.

Проверка исполнителя использует электронную почту автора, записанную в коммите. Создатель коммита может указать её самостоятельно; чтобы установить, кто подписал коммит, включите также правило «Коммит должен быть подписан GPG».

Правила отправки изменений, включая правила Яги, не действуют в проекте с pull-зеркалированием: не проверяются ни обновления зеркала, ни прямые отправки изменений в такой проект.

Проверка при слиянии

В проекте откройте «Настройки» → «Запросы на слияние» → «Проверки слияния» и установите флажок «В заголовке или описании должна быть указана задача Jaga». Интеграция должна быть активна в проекте или унаследована. Проверка ищет код задачи в заголовке или описании запроса на слияние без обращения к Яге.

Флажок недоступен, пока интеграция с Ягой не настроена. Если интеграцию позже отключить, флажок остаётся установленным, но проверка больше не блокирует слияние.

Если правило отправки изменений требует код задачи в каждом коммите, укажите его в заголовке запроса на слияние. Сообщение коммита слияния по умолчанию содержит заголовок и проходит проверку при отправке изменений. Если в проекте задан шаблон сообщения коммита слияния, включите в него %{title}, а при редактировании сообщения перед слиянием сохраните код задачи. Если включено «Объединять коммиты при слиянии», проверяется и объединённый коммит: его сообщение по умолчанию берётся из шаблона сообщения squash-коммита, а без шаблона — из заголовка запроса на слияние. Включите %{title} и в этот шаблон.