Перейти к основному содержимому
Версия: v2 (текущая)

Интеграция ClickUp с PanDev Metrics

import IdealImage from "@theme/IdealImage"; import Head from "@docusaurus/Head";

Кратко. Гайд подключает ClickUp к PanDev Metrics примерно за 10 минут. Вы сгенерируете Personal API Token в ClickUp, вставите его в Настройки → Интеграции → ClickUp, выберете workspace'ы и spaces для мониторинга и убедитесь, что задачи, статусы и worklog попадают в дашборды. Аудитория: администратор.

Что понадобится​

  • Запущенный PanDev Metrics (Cloud-воркспейс или on-prem)
  • Доступ администратора к воркспейсу PanDev Metrics
  • Пользователь ClickUp с ролью Admin или Workspace Owner в нужных workspace'ах — права администратора обязательны, потому что PanDev Metrics регистрирует webhooks при подключении
  • Для on-prem PanDev Metrics: исходящий 443 до api.clickup.com
  • Чтобы ClickUp мог достучаться до on-prem PanDev Metrics: хост PanDev Metrics должен быть доступен из ClickUp по публичному webhook URL

:::tip Сервисный аккаунт Заведите отдельного пользователя ClickUp (например pandev-metrics-bot) и добавьте его в нужные workspace'ы с правами админа. Это отделяет автоматическую вебхук-активность от истории людей и переживает увольнения. :::

Шаг 1 — Сгенерируйте Personal API Token в ClickUp​

PanDev Metrics аутентифицируется как сервисный пользователь через Personal API Token — это самый простой способ авторизации в ClickUp (OAuth-callback не нужен).

  1. Войдите в ClickUp как сервисный аккаунт.
  2. Нажмите на аватар в правом верхнем углу → Settings.
  3. Откройте My Settings → Apps (раздел может называться Apps или API в зависимости от плана).
  4. В секции API Token нажмите Generate (или Regenerate, если токен уже есть).
  5. Сразу скопируйте токен — он начинается с pk_…, ClickUp его больше не покажет.

:::warning Храните токен в секрете Personal API Token даёт ровно те же права, что и у сервисного пользователя. Положите его в менеджер секретов. :::

Шаг 2 — Откройте экран интеграции ClickUp в PanDev Metrics​

Войдите в PanDev Metrics как администратор воркспейса и откройте Настройки → Интеграции → ClickUp.

Включите Enable integration with ClickUp.

Шаг 3 — Введите API-токен​

Заполните форму:

ПолеЗначение
API TokenЗначение pk_… из Шага 1

Нажмите Check connection. PanDev Metrics вызовет GET /api/v2/team в ClickUp и покажет аутентифицированного пользователя плюс список доступных workspace'ов.

После успешной проверки нажмите Save.

Шаг 4 — Выберите workspace'ы и spaces для мониторинга​

После сохранения PanDev Metrics показывает список workspace'ов, spaces и folders, видимых сервисному аккаунту. Выберите spaces для анализа и сохраните.

PanDev Metrics запускает одноразовый backfill за последние 90 дней по задачам, статусам и worklog'у.

Шаг 5 — Проверьте регистрацию webhook'ов​

PanDev Metrics регистрирует webhook'и ClickUp автоматически. Чтобы убедиться, откройте ClickUp → Settings → Integrations → Webhooks для выбранного workspace'а. Вы увидите один или несколько hook'ов, указывающих на ingest-URL PanDev Metrics.

Последние доставки должны возвращать HTTP 200 в течение секунд. PanDev Metrics также раз в 15 минут запускает реконсиляцию, чтобы не потерять пропущенные события.

Проверка​

Откройте Настройки → Интеграции → ClickUp в PanDev Metrics. Вы увидите:

  • Зелёный бейдж Подключено
  • Количество выбранных workspace'ов и spaces
  • Время последней синхронизации (не старше 30 минут после завершения backfill)

Затем откройте дашборд с виджетом таск-трекера и убедитесь, что:

  • Свежие задачи ClickUp появляются рядом с коммитами
  • Статусы соответствуют ClickUp (Open / In Progress / Closed плюс ваши кастомные статусы)
  • Время IDE атрибуцируется задачам, чей ID появляется в названиях веток или сообщениях коммитов (например CU-abc123)

Для принудительного обновления нажмите Sync now на плитке интеграции.

Что синхронизируется​

PanDev Metrics получает узкий срез данных ClickUp — без вложений и без тел комментариев по умолчанию.

ИсточникНаправлениеЧто сохраняется
Поля задачPull + webhookID, название, статус, status group, приоритет, assignee, creator, list, folder, space, теги, due date, story points / estimate
Переходы статусовWebhookОт, к, время, actor — для cycle time и time-in-status
Worklog (Time Tracked)Webhook + pullАвтор, старт, длительность, task ID — для обогащения IDE-учёта времени
Спринты (если включён Sprints ClickApp)PullID, имя, даты старта/конца
ПользователиPullClickUp user id, имя, email — сопоставляются с сотрудниками PanDev Metrics

Вложения, значения произвольных custom fields (сверх базового маппинга) и тела комментариев не сохраняются.

Решение проблем​

Check connection возвращает «401 Unauthorized»

API-токен неверный, истёк или был перегенерирован. Откройте ClickUp → My Settings → Apps, сгенерируйте новый токен и вставьте его в PanDev Metrics. Токены не переносятся между пользователями — новый просто заменяет старый для сервисного аккаунта.

Подключение работает, но задачи не появляются через 30 минут

Сервисный пользователь не входит в выбранные spaces, или backfill ещё идёт для крупного workspace'а. Проверьте членство в ClickUp → Workspace settings → People и нажмите Sync now на плитке интеграции.

Webhook'и доставляются с таймаутом

ClickUp не может достучаться до webhook URL PanDev Metrics. Для on-prem убедитесь, что хост доступен из ClickUp по публичному URL. С любого хоста с общим доступом в интернет выполните curl -I <pandev-public-url> — должен вернуться HTTP-ответ, а не connection error.

Worklog-записи не появляются

В workspace'е отключён Time Tracking ClickApp, или у сервисного пользователя нет доступа к time entries. Включите Time Tracking в ClickUp → Workspace settings → ClickApps, затем нажмите Sync now в PanDev Metrics.

Кастомные статусы всегда маппятся в «UNDEFINED»

PanDev Metrics маппит статусы по типу (Open / Custom / Closed), а не по имени. Откройте space в ClickUp, отредактируйте каждый кастомный статус и поставьте ему Type = In Progress или Closed по смыслу. На следующей синхронизации маппинг подтянется заново.

FAQ​

Учитываются ли custom fields ClickUp?​

PanDev Metrics читает стандартные поля (статус, приоритет, assignee, теги, due date, story points). Произвольные custom fields по умолчанию не синхронизируются. Если на дашборде нужно конкретное поле — напишите в поддержку, большинство можно добавить по запросу.

Какие минимальные права в ClickUp?​

Сервисному пользователю нужна роль Admin в workspace'е — иначе PanDev Metrics не сможет зарегистрировать webhooks при подключении. Member-уровень читает задачи, но не создаёт webhook'и, что вынуждает откатиться к polling-only режиму.

Работает ли PanDev Metrics с бесплатным планом ClickUp?​

Да. Интеграция использует стандартный ClickUp API v2 и Personal API Token — оба доступны на free-плане. Webhook'и тоже бесплатны. Часть функциональности зависит от платных ClickApps (Sprints, Time Tracking) — если у вас их нет, отключите соответствующие фичи в PanDev Metrics.

Можно ли связать коммиты и PR с задачами ClickUp?​

Да. ClickUp присваивает каждой задаче короткий ID вроде abc1d2. Добавьте префикс CU- (настраивается) и ID в название ветки, сообщение коммита или заголовок PR — feature/CU-abc1d2 - описание. PanDev Metrics извлекает ID и связывает с данными ClickUp на дашбордах.

Пишет ли интеграция в ClickUp?​

PanDev Metrics пишет IDE-worklog в поле Time Tracked в режиме automatic worklog. В режиме read-only запись не выполняется. Статус, assignee и комментарии задач никогда не изменяются.

Можно ли ротировать Personal API Token?​

Да. Сгенерируйте новый токен в ClickUp, затем откройте Настройки → Интеграции → ClickUp → Обновить токен в PanDev Metrics. Webhook'и остаются зарегистрированными.

Можно ли подключить несколько workspace'ов ClickUp?​

Да. Один Personal API Token даёт доступ ко всем workspace'ам, в которые входит сервисный пользователь. Включайте/выключайте workspace'ы в PanDev Metrics в любой момент.

Сколько идёт первичный backfill?​

PanDev Metrics при активации подтягивает последние 90 дней задач и worklog. Для 10k задач это занимает 5-15 минут; очень крупные workspace'ы (100k+ задач) — час и больше.

Дальнейшие шаги​

Связанные материалы​