Подключение Notion как таск-трекера

import Head from '@docusaurus/Head';

TL;DR. Создайте Internal Integration в Notion, скопируйте токен secret_..., расшарьте целевую базу с интеграцией и добавьте в эту базу свойство Unique ID с префиксом NT. Вставьте Token + Database ID в Настройки → Интеграции → Notion в PanDev Metrics. Ветки вида feature/NT-42 - описание после этого будут связываться с соответствующей страницей Notion. Занимает около 5 минут.

Как работает интеграция с Notion

В отличие от Jira или ClickUp, Notion не отправляет события в PanDev Metrics. Интеграция опрашивает Notion каждые 10 минут через NotionSyncCronJob, забирает страницы, изменившиеся с последнего watermark, и пишет их в таблицу issue. Pull-модель означает, что на стороне Notion ничего настраивать не нужно — никаких вебхуков, callback URL и публичных endpoint'ов, кроме одной операции «расшарить базу».

Перед началом работы

Подготовьте доступы в обеих системах перед открытием PanDev Metrics — сама интеграция занимает около 5 минут, когда предусловия выполнены.

• Рабочее пространство Notion, в котором у вас есть права администратора (нужны для создания интеграций).
• База данных Notion (не обычная страница), в которой хранятся задачи.
• PanDev Metrics версии 5.7 или новее и роль tenant admin.
• Опционально: согласуйте с командой соглашение о коротких ID для названий веток (см. Соглашение об именах веток).

Шаг 1 — Создайте Internal Integration в Notion

PanDev Metrics авторизуется в Notion по Internal Integration Token. Сгенерируйте его в настройках своего рабочего пространства Notion.

1. Откройте Notion в браузере и перейдите в Settings → Connections → Develop or manage integrations.
2. Выберите New integration.
3. Заполните:
   • Name: PanDev Metrics
   • Associated workspace: ваше рабочее пространство
   • Type: Internal
4. В разделе Capabilities включите Read content, Update content и Insert content. Read-only недостаточно — PanDev пишет в Notion комментарии worklog и обновляет свойство Time Spent.
5. Нажмите Save.
6. Скопируйте Internal Integration Token — он начинается с secret_. Храните его в секрете.

Internal или Public — что выбрать

Всегда выбирайте Internal. Public-интеграции требуют OAuth callback URL и нужны для публичных приложений в Notion Marketplace; для self-hosted таск-трекинга это лишняя сложность.

Шаг 2 — Расшарьте целевую базу с интеграцией

Сам по себе токен не даёт доступа ни к чему. Доступ к каждой базе нужно выдать интеграции отдельно.

1. Откройте в Notion базу данных, в которой ведутся задачи.
2. Нажмите … (меню в правом верхнем углу) → Connections → Add connections.
3. Найдите в списке PanDev Metrics и выберите.
4. Подтвердите.

Повторите для каждой базы, которую нужно синхронизировать с PanDev Metrics.

Как найти Database ID

Скопируйте URL базы. Он выглядит как https://www.notion.so/acme/My-Tasks-1f3a9c2e8b7d4f5a8e2b1c4d6e9a0f3b?v=.... Database ID — это 32-символьный сегмент непосредственно перед ?v=, например 1f3a9c2e8b7d4f5a8e2b1c4d6e9a0f3b. Уберите дефисы, если они есть.

Шаг 3 — Подключение в PanDev Metrics

Когда токен на руках и база расшарена, остаётся завершить настройку в PanDev Metrics.

1. Перейдите в Настройки → Интеграции → Notion.
2. Включите тумблер Включить интеграцию с Notion.
3. Введите:
   • Database ID: 32-символьный UUID из предыдущего шага
   • Integration Token: значение secret_... из Шага 1
4. Нажмите Проверить подключение.
5. После успешной проверки нажмите Сохранить.

Первая синхронизация запустится на ближайшем cron-тике (в течение 10 минут). Чтобы стянуть данные сразу, дёрните POST /api/v1/notion/sync/{departmentId} из API explorer.

Шаг 4 — Рекомендуемая схема базы в Notion

PanDev Metrics читает свойства по имени без учёта регистра. Жёстко обязательных свойств нет, но набор метрик, которые PanDev сможет посчитать, зависит от того, что присутствует.

Свойство Notion	Тип в Notion	Что читает PanDev	Обязательно?
Name (или первый столбец Title)	Title	issue.title	Да (всегда есть)
ID (любое имя)	Unique ID с префиксом NT	issue.project_key — человекочитаемый ключ вида NT-42, который используется в именах веток	Настоятельно рекомендуется
Status	Status	issue.status + маппинг в IssueDefaultStatus	Рекомендуется
Assignee (или Owner, Responsible)	People	issue.assignee (email, если доступен)	Опционально
Priority	Select	issue.priority	Опционально
Estimate (или Time Estimate)	Number (часы)	issue.original_time_estimate (конвертируется в секунды)	Опционально
Time Spent	Number (часы)	Увеличивается PanDev'ом при добавлении worklog	Создаётся автоматически при первом worklog

Как добавить свойство Unique ID

1. Откройте базу данных в Notion → нажмите + в заголовке колонок → ID (в группе «Advanced», иногда подписано «Unique ID»).
2. В настройках свойства задайте Prefix = NT (или любую другую короткую строку — см. настройку NOTION_ISSUE_PREFIX на on-prem).
3. Notion автоматически проставит следующий номер каждой существующей странице и каждой новой (NT-1, NT-2, NT-3, …). Эти номера нельзя редактировать — это by design, и именно это нужно для постоянных идентификаторов в именах git-веток.

Колонку ID можно скрывать в любых view базы без влияния на привязку веток — PanDev читает её через API независимо от видимости.

Маппинг статусов

PanDev маппит произвольные статусы Notion в один из трёх дефолтных по ключевым словам:

Если статус Notion содержит...	Маппится в
done, complete, closed, released, shipped, resolved	DONE
progress, doing, review, active, development, wip	IN_PROGRESS
to do, todo, backlog, new, open, planned, not started	TO_DO
что-либо ещё	UNDEFINED

То есть In Review → IN_PROGRESS, Released to prod → DONE, Icebox → UNDEFINED. Переименуйте статусы в Notion, если дефолтный маппинг не подходит под ваш флоу.

Критично: соглашение об именах веток

Это самое важное правило для того, чтобы интеграция приносила пользу. Когда в базе Notion есть Unique ID со префиксом NT, у каждой страницы появляется чистый человекочитаемый ключ вроде NT-1, NT-42, NT-1337. Этот ключ и нужно ставить в имя ветки.

Называйте feature-ветки так:

Именование веток

feature/NT-<номер-id> - описание
bugfix/NT-<номер-id> - описание

Примеры:

feature/NT-42 - notion-integration
bugfix/NT-1337 - fix-status-mapping
hotfix/NT-7 - critical-prod-issue

PanDev сопоставляет регуляркой NT-<число> (без учёта регистра) внутри названия ветки, ищет страницу в таблице issue по project_key = 'NT-42' и связывает ветку с этой страницей. Префикс настраивается на уровне департамента через NOTION_ISSUE_PREFIX (по умолчанию NT) — он должен совпадать с тем, что вы задали в свойстве Unique ID в Notion.

Где увидеть ID в Notion?

Откройте любую страницу в базе — свойство ID отображается в шапке страницы прямо рядом с заголовком (NT-42). Также колонку ID можно показать в любом table view для быстрой ориентации при именовании веток.

Без префикса NT- ветки не будут привязаны к страницам Notion

Коммиты и pull-реквесты на ветках без NT-<id> появятся в PanDev Metrics как несвязанные. Они всё равно попадут в метрики coding time, но PanDev не сможет атрибутировать их к конкретной задаче Notion — поэтому таск-метрики (Cycle Time, время в статусах, Lead Time) для этих задач будут пустыми.

Шаг 5 — Проверка

После сохранения настроек и первого cron-тика:

1. Откройте Дашборд → Задачи. Страницы из вашей базы Notion должны появиться с tracker = notion и project_key = NT-<n>.
2. Возьмите любую страницу из вашей базы Notion, посмотрите её ID (например, NT-42) и создайте ветку feature/NT-42 - test. Запушьте хотя бы один коммит.
3. В течение нескольких минут ветка должна появиться привязанной к странице Notion в таблице Branches, и название страницы должно отобразиться в столбце Task.
4. Ссылка на страницу из PanDev должна резолвиться в нужную страницу Notion и открывать её.

Как записывается worklog

У Notion нет нативного endpoint'а для worklog, поэтому PanDev эмулирует его. Когда приходит событие worklog (от IDE-телеметрии, ручного лога или вызова API addWorklog):

1. PanDev публикует комментарий на странице Notion в формате +1.50h — fixed flaky test.
2. PanDev увеличивает number-свойство Time Spent на странице на длительность worklog в часах.

Обе операции используют один и тот же Integration Token. Комментарии не содержат префикса с именем продукта — это сохраняет нейтральный вид страницы Notion для заказчиков, разворачивающих PanDev Metrics в white-label-режиме.

Только в одну сторону

PanDev пишет worklog в Notion, но не читает worklog из Notion. У Notion API нет потока worklog, поэтому время, залогированное прямо в Notion, не вернётся в PanDev Metrics. Всегда логируйте время через PanDev (IDE-плагин или API).

Notion и Jira: сравнение моделей синхронизации

Аспект	Jira (push)	Notion (pull)
Как обновления попадают в PanDev	Jira POST'ит на вебхук PanDev на каждое событие	PanDev опрашивает Notion каждые 10 мин на предмет изменений
Настройка на стороне трекера	PanDev автоматически регистрирует вебхуки через Jira API	Нет — только расшарить базу с интеграцией
Задержка по статусам	Почти real-time (секунды)	До 10 минут
Работает за NAT / firewall?	Требует доступности PanDev из Jira	Да — PanDev делает только исходящие вызовы
Ingestion worklog	Двусторонний (worklog Jira → PanDev)	Односторонний (PanDev → Notion)
Настраиваемый интервал	Фиксированный (вебхук-driven)	Переменная NOTION_SYNC_CRON (on-prem)

Pull-модель меняет несколько минут задержки на нулевую конфигурацию со стороны Notion. Для большинства аналитических сценариев — дневные/недельные дашборды, отчёты по cycle time — это незаметно. Если нужна реакция на смену статуса за секунды, используйте Jira.

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

Самые частые ошибки при подключении с готовым решением для каждой.

Test Connection возвращает 401 «notion.auth»

Токен неверен или интеграция удалена. Пересоздайте Internal Integration в Notion, вставьте новый токен secret_... и проверьте подключение снова. Токены не переиспользуются между рабочими пространствами.

Test Connection проходит, но через 10 минут страницы не появляются

База не расшарена с интеграцией. Откройте базу в Notion → … → Connections → Add connections → выберите PanDev Metrics. Проверка подключения валидирует только токен и доступ к API в целом, но не проверяет доступ к конкретной базе.

Страницы появились, но Status всегда UNDEFINED

Имя свойства status не Status (без учёта регистра) или значения статусов не содержат ожидаемых ключевых слов. Переименуйте свойство в Status и переименуйте значения так, чтобы они содержали In Progress, Done, To Do. См. таблицу в разделе Маппинг статусов.

Ветки не привязываются к страницам Notion

В названии ветки нет NT-<id> или <id> короче 6 символов. Переименуйте ветку в feature/NT-<short-id-страницы> - описание (минимум 6 символов после NT-) и запушьте хотя бы один новый коммит.

Комментарий worklog опубликован, но свойство Time Spent не обновляется

Свойство Time Spent на странице не существует или имеет тип, отличный от Number. Добавьте number-свойство Time Spent в базу данных. Существующие страницы получат свойство автоматически при следующем обновлении.

FAQ

Часто задаваемые вопросы команд, подключающих Notion-интеграцию впервые.

Как найти ID страницы Notion для имени ветки?

Откройте страницу в Notion — свойство ID показывает присвоенный ключ (например, NT-42) в шапке прямо рядом с заголовком. Также колонку ID можно показать в любом table view базы для удобства. Скопируйте этот ключ в имя ветки как есть: feature/NT-42 - описание. Префикс совпадает с тем, что вы задали в свойстве Unique ID в Notion; дефолт PanDev — NT, настраивается через NOTION_ISSUE_PREFIX.

Что если в моей базе Notion ещё нет свойства Unique ID?

Добавьте — это 5 секунд, и интеграция продолжит работать на время перехода. Откройте базу в Notion → + в шапке колонок → ID (под группой Advanced) → задайте Prefix NT. Notion сразу проставит NT-1, NT-2, … всем существующим страницам; новые страницы будут получать следующий номер автоматически. Старые ветки с NT-<длинный-id> продолжат матчиться по UUID-фрагменту, но новые ветки должны использовать чистый формат NT-<число>.

Где изменить интервал опроса?

По умолчанию — каждые 10 минут. На on-prem-инсталляциях задайте переменную окружения NOTION_SYNC_CRON стандартным Spring cron-выражением: например, 0 */5 * * * * для каждых 5 минут или 0 0 */1 * * * для каждого часа. После изменения перезапустите контейнер PanDev Metrics. На SaaS интервал зафиксирован.

Что будет, если переименовать значение Status в Notion?

Ничего не ломается. PanDev перечитывает имя статуса при каждой синхронизации и заново применяет keyword matching. Если новое имя больше не матчится ни на одно ключевое слово, default_status страницы становится UNDEFINED до следующего переименования. Историческая таблица IssueStatusPeriod не переписывается — там остаётся имя статуса каким оно было в момент записи.

Можно ли использовать Notion без свойства Status?

Можно, но потеряете все метрики, основанные на статусах. Страницы будут синхронизированы с названиями, исполнителями и другими читаемыми свойствами, но все DORA- и cycle-time-графики, зависящие от переходов статусов, окажутся пустыми. Настоятельно рекомендуется добавить свойство Status, даже если оно содержит всего два значения (Open и Done).

Может ли один департамент в PanDev синхронизировать несколько баз Notion?

Сейчас нет. Каждый департамент хранит ровно один NOTION_DATABASE_ID. Чтобы отслеживать несколько баз, создайте в PanDev отдельные департаменты или сначала объедините базы в Notion. Поддержка нескольких баз в одном департаменте — в roadmap.

Видит ли PanDev приватные страницы Notion, которые я не расшарил с интеграцией?

Нет. Notion API строго соблюдает scope расшаривания. PanDev видит только страницы внутри баз, к которым вы явно добавили интеграцию через Connections → Add connections. Удаление коннекшна в Notion мгновенно отзывает доступ PanDev.

Как заротировать Integration Token?

Создайте новую internal-интеграцию в Notion (или перегенерируйте токен на существующей), расшарьте с ней свою базу и обновите поле Integration Token в Настройки → Интеграции → Notion в PanDev Metrics. Нажмите Проверить подключение для верификации и затем Сохранить. После этого старый токен можно сразу удалить из Notion.

Дальше

После подключения Notion добавьте источники данных, нужные PanDev для полной атрибуции метрик к задачам.

• Подключите IDE-плагин — чтобы считать coding time по задачам Notion
• Подключите Git-интеграцию — чтобы PanDev увидел ветки с префиксом NT-
• Метрики и индикаторы — посмотрите метрики по задачам Notion

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

Другие гайды по таск-трекерам и материалы для сравнения.

• How-to: Подключение Jira — сравнение с push-моделью
• How-to: Подключение Yandex Tracker — альтернативный таск-трекер