Linear в Keepr: задачи команды открываются сами, время возвращается комментарием
Что делает интеграция
Одна интеграция связывает команду Linear — или все публичные команды пространства — с одним проектом Keepr. Входящее направление: Linear сообщает Keepr о задачах. Новая задача становится задачей в проекте Keepr, перевод в состояние Completed архивирует её, а возврат из него восстанавливает. Отменённая задача ничего не меняет, а удаление задачи архивирует её.
Исходящее направление: Keepr возвращает учтённое время. В Linear нет поля для учёта времени, поэтому каждая запись времени по связанной задаче становится одним комментарием, который правится при изменении записи и удаляется вместе с ней. Отправляется только время из проекта Keepr этой интеграции, с точностью до секунды и без округления.
Что понадобится
В Keepr нужно быть владельцем или администратором организации либо менеджером пространства, в котором лежит проект. Интеграции есть на всех тарифах: на Free работает одна одновременно, на Team — три, на Ultimate, включая пробный период, — сколько нужно.
В Linear нужен API-ключ администратора пространства: создавать вебхуки Linear разрешает только администраторам, а Keepr создаёт вебхук сам. В отличие от GitHub, GitLab и Jira, вручную в Linear ничего вставлять не нужно.
1. Создайте интеграцию в Keepr
Откройте «Настройки организации» → «Интеграции» и нажмите «Новая интеграция». Выберите Linear, проект Keepr, куда будут попадать задачи, и имя, от которого интеграция действует: Keepr показывает её действия, например, как «Архивировано: Linear · Website».
Укажите ключ команды, например ENG — буквы перед номером в идентификаторе каждой задачи, — чтобы подключить одну команду. Оставьте поле пустым, чтобы охватить все публичные команды пространства; закрытая команда подключается только своим ключом.
2. Выберите, чей ключ использует Keepr
Linear показывает автором каждого комментария владельца API-ключа, который использует Keepr. В комментарии указан участник Keepr, учитывавший время, но автором для всех записей будет эта учётная запись, и она должна быть администратором пространства: тем же ключом регистрируется вебхук.
Лучше всего завести для Keepr отдельную у чётную запись администратора Linear. Войдите под ней и создайте ключ в Settings → Security & access → Personal API keys. Дайте ему полный доступ или хотя бы права Read, Write и Admin, а если ограничиваете ключ командами — включите команду интеграции.
3. Передайте ключ Keepr
На странице интеграции откройте «Ключи доступа» и нажмите «Задать…» у ключа Linear. В ставьте ключ и сохраните. Адрес вводить не нужно: Keepr узнаёт пространство по ключу.
Затем Keepr регистрирует вебхук в Linear с секретом, который знают только он и Linear, и показывает его состояние во «Входящих вебхуках»: «Регистрируется…», затем «Зарегистрирован Keepr». Если не получилось, там же сказано почему — чаще всего ключ не администратора, — а «Зарегистрировать заново» повторит попытку, когда причина устранена. Ключ хранится в зашифрованном виде, дальше видны только его первые символы.
Вебхук, который регистрирует Keepr
Его видно в Linear в Settings → API → Webhooks: он подписан «Keepr» и именем интеграции и отправляет события Issue на . Не меняйте его вручную: смена команды на странице интеграции заменяет его, замена секрета обновляет, а удаление ключа или отзыв интеграции удаляет.
Если вебхук удалили в Linear, кнопка «Зарегистрировать заново» на странице интеграции создаст его снова.
Что отправляет Keepr
Запись отправляется, когда она завершена — идущий таймер ничего не отправляет, пока не остановится, — и только если её задача лежит в проекте интеграции и связана с задачей этого пространства Linear. Так связаны задачи, созданные интеграцией, и задачи, начатые из браузерного расширения на странице задачи Linear.
На каждую запись — один комментарий с участником, длительностью и днём; учётная запись ключа на задачу не подписывается. Правка записи переписывает этот комментарий, а не добавляет новый, удаление записи удаляет его, перенос записи на другую задачу переносит комментарий. Комментарий, удалённый вручную, появится снова при следующем изменении записи.
Импортированное время — это история, оно не отправляется. В списке «Недавно отправлено» видны последние записи: задача, участник, время, которое числится за ней в Linear, и удалась ли последняя отправка; у неудачной указаны причина и что делать.
Пауза, замена секрета и отзыв
Переключатель на странице интеграции выключает её, ничего не теряя. Пока она выключена, доставки записываются, но не обрабатываются, и время не отправляется: запись, сохранённая во время паузы, уйдёт при следующем изменении. Повторное включение снова занимает место в лимите тарифа.
«Заменить…» в «Ключах доступа» меняет секрет вебхука, и Keepr сам передаёт новый секрет в Linear; доставка, отправленная в промежутке, не пройдёт, и Linear её повторит. «Удалить» у ключа Linear выключает учёт времени и удаляет вебхук.
Отзыв окончателен. Keepr удаляет вебхук в Linear, уничтожает оба секрета и больше ничего не делает; интеграция остаётся в списке как история, а её действия остаются за ней в журнале аудита и на архивных задачах. Отзовите API-ключ и в Linear.
Если что-то не так
Каждая доставка видна в последних доставках интеграции вместе с результатом. Если не приходит ничего, скорее всего, вебхук не зарегистрирован: проверьте его состояние во «Входящих вебхуках». «Задача уже есть» значит, что задача для неё уже существовала — например, начатая из браузерного расширения, — и дубликат не создан.
В «Недавно отправлено» «Ключ доступа отклонён» значит, что ключ отозван или у него нет права Write. «Задача не найдена» — задачу удалили или учётная запись ключа не видит её команду. «Сервис отказал» — любой другой отказ Linear; «Сервис недоступен, повторим» пройдёт сам, когда Linear ответит. Отправка, не прошедшая окончательно, повторится при следующем изменении записи.