Задачи GitLab в проекте Keepr, учтённое время — через /spend
Что делает интеграция
Одна интеграция связывает проект GitLab с одним проектом Keepr. Входящее направление: GitLab сообщает Keepr о своих задачах — новая задача становится задачей в проекте Keepr, закрытие архивирует её, повторное открытие восстанавливает. Merge request, который закрывает ровно одну задачу GitLab — через «Closes #12» или связь, которую GitLab считает закрывающей, — учитывается в её задаче Keepr, и расширение для браузера запускает таймер тоже на ней; любой другой merge request получает собственную задачу, которая уходит в архив при слиянии или закрытии. Какие задачи закрывает merge request, Keepr спрашивает у GitLab, поэтому для этого нужен токен из шага 4.
Исходящее направление: Keepr возвращает отслеженное время. Когда запись времени на задаче, связанной с задачей, merge request или рабочим элементом GitLab, сохраняется, меняется или удаляется, Keepr добавляет к этому объекту комментарий с /spend, и время видно в учёте времени самого GitLab. Отправляется только время из проекта Keepr этой интеграции — с точностью до секунды, без округления.
Перед началом
В Keepr нужно быть владельцем или администратором организации либо менеджером рабочего пространства, в котором лежит проект. Интеграции есть на всех тарифах: на Free одновременно работает одна, на Team — три, на Ultimate, включая пробный период, — сколько нужно.
В GitLab нужна роль Maintainer или Owner в проекте — чтобы добавить вебхук и создать токен доступа проекта. Self-managed GitLab работает так же, если он может обратиться к по HTTPS, а Keepr — к нему через публичный интернет.
1. Создайте интеграцию в Keepr
Откройте «Настройки организации» → «Интеграции» и нажмите «Новая интеграция». Выберите GitLab, проект Keepr, в который пойдут задачи, и имя, от которого интеграция действует: в Keepr её действия выглядят, например, как «Архивировано: GitLab · Сайт».
После этого Keepr один раз покажет секрет подписи вебхука. Скопируйте его, прежде чем закрыть окно: потом видны только первые символы. Если секрет потерян, смените его на странице интеграции и вставьте новый в GitLab.
2. Добавьте вебхук в GitLab
В проекте GitLab откройте Settings → Webhooks по адресу и нажмите «Add new webhook». Вставьте адрес из раздела «Входящие вебхуки» интеграции в поле URL, а секрет подписи — в «Secret token».
В разделе Trigger отметьте «Issues events» и «Merge request events», оставьте проверку SSL включённой и сохраните. «Test → Issues events» отправит пример — он появится в последних доставках интеграции в Keepr вместе с тем, что с ним сделано.
Конфиденциальные задачи намеренно игнорируются: их названия увидели бы все, кому виден проект Keepr.
3. Решите, от чьего имени уходит время
GitLab приписывает каждый комментарий и каждый /spend владельцу токена, которым пользуется Keepr, поэтому в отчётах GitLab всё время команды числится за этой учётной записью. В самом комментарии назван участник Keepr, который отследил время. Отправка от имени собственной учётной записи GitLab каждого участника запланирована; до тех пор используйте токен, не принадлежащий конкретному человеку.
Лучше всего — токен доступа проекта: для него GitLab создаёт собственного бота. Создайте его по адресу с ролью Reporter или выше и областью api. Токен доступа группы, по адресу , так же покрывает все проекты группы. На GitLab.com оба требуют тарифа Premium или Ultimate; в self-managed GitLab они есть на любом тарифе.
Если в вашем тарифе есть сервисные учётные записи, подойдёт и такая запись с её токеном; на GitLab.com они находятся в Settings → Service accounts группы верхнего уровня, по адресу . Если ничего из этого нет, заведите для Keepr отдельную учётную запись GitLab, дайте ей роль Reporter в проекте и, войдя под ней, создайте персональный токен доступа в User settings → Personal access tokens с областью api.
Нужен классический токен, а не fine-grained: fine-grained токены пока не умеют выполнять /spend. Задайте срок действия, который вы не пропустите: когда токен истечёт, отправка остановится с ошибкой «Ключ доступа отклонён», пока не будет задан новый.
4. Укажите в Keepr адрес и токен
На странице интеграции откройте «Ключи доступа» и нажмите «Задать…» рядом с ключом доступа GitLab. Адрес GitLab — или корневой адрес вашего self-managed экземпляра, а не страница проекта; вставленная страница gitlab.com сохранится как . Вставьте токен и сохраните.
Keepr хранит токен в зашифрованном виде и потом показывает только его первые символы. Он нужен для отправки времени и чтобы узнать, какие задачи закрывает merge или pull request, — больше ни для чего. Без него задачи по-прежнему приходят, но merge и pull request остаются без действия, а в последних доставках видно «Не удалось узнать его задачи».
Что отправляет Keepr
Запись отправляется, когда она завершена — идущий таймер ничего не отправляет, пока не остановится, — и только если её задача лежит в проекте интеграции и ссылается на задачу, merge request или рабочий элемент по адресу GitLab. Так связаны задачи, созданные интеграцией, и задачи, запущенные из расширения для браузера на странице GitLab.
Каждая отправка — комментарий к объекту: фраза с участником, длительностью и днём, а затем строка /spend. Изменение отправляет только разницу — отрицательным /spend, если запись стала короче; удаление записи так же забирает её время обратно, а перенос на другую задачу переносит время. Длительность указывается в часах, минутах и секундах, но не в днях: GitLab считает день за восемь рабочих часов.
Импортированное время — это история, и оно не отправляется. Список «Недавно отправлено» на странице интеграции показывает последние записи: объект, участника, сколько времени держит GitLab и удалась ли последняя отправка; у неудачной строки написано, почему и что делать.
Пауза, смена секрета и отзыв
Переключатель на странице интеграции выключает её без потери данных. Пока она выключена, доставки записываются, но не выполняются (кнопка GitLab «Resend request» повторит доставку позже), а время не отправляется: запись, сохранённая во время паузы, уйдёт при следующем её изменении. Повторное включение снова занимает место в лимите тарифа.
«Заменить…» в разделе «Ключи доступа» сразу заменяет секрет вебхука, без переходного периода: доставки не проходят, пока новый секрет не окажется в GitLab. «Удалить» рядом с ключом доступа GitLab выключает отправку времени и не трогает входящее направление.
Отзыв окончателен. Keepr уничтожает оба секрета и больше ничего не выполняет; интеграция остаётся в списке как история, а её действия — подписанными её именем в журнале аудита и на архивных задачах. Отзовите токен и в GitLab.
Если вебхук добавить нельзя
Если вебхук добавить не получается — нет роли Maintainer или GitLab не может достучаться до Keepr, — задачи может создавать запланированный конвейер через REST API. Ему нужен персональный API-токен, а он входит в тариф Ultimate: создайте его в разделе API-токены с областью timers:write и сохраните в маскированной переменной CI/CD по адресу . Расписание конвейера задаётся по адресу .
Задание получает задачи проекта через API GitLab и для каждой вызывает с заголовком «Authorization: Bearer» и токеном и телом JSON: externalKey (номер задачи), name (её название), url (её веб-адрес) и projectId. Keepr возвращает существующую задачу или создаёт её, сопоставляя так же, как при вебхуке, поэтому повторный запуск ничего не испортит.
Чтобы архивировать задачу закрытой задачи GitLab, возьмите id задачи из этого ответа и вызовите — для этого нужна область projects:write. Все поля описаны в справочнике API на api.keepr.ru/docs. Отправке времени вебхук не нужен: она работает в обоих случаях, когда заданы адрес и токен.
Если что-то пошло не так
Каждая доставка видна в последних доставках интеграции вместе с тем, что с ней сделано. Если GitLab показывает доставку как неудачную с кодом 401, в ней был неверный секретный токен: вставьте текущий или смените его. «Задача уже есть» значит, что задача для этой задачи GitLab уже существовала — например, запущенная из расширения для браузера, — и дубля не появилось.
В списке «Недавно отправлено» «Не заданы адрес или ключ доступа» значит, что у интеграции ещё нет адреса GitLab или токена. «Ключ доступа отклонён» значит, что токен отозван, истёк или у него нет области api. «Сервис отказал» чаще всего значит, что GitLab сохранил комментарий, но не применил /spend, потому что роль токена ниже Reporter. «Задача не найдена» — объект удалён или токен его не видит, «Адрес не разрешён» — адрес GitLab не публичный HTTPS. «Сервис недоступен, повторим» проходит само, когда GitLab снова отвечает.
Отправка, завершившаяся окончательной ошибкой, повторяется при следующем изменении записи.