gitlab-task-collector

v1.0.26

Published

9 days ago

CLI tool to collect tasks from files and sync with GitLab Issues

Downloads

2,311

0High
0Medium
0Low

paulthesecond

gitlab cli todo task collector

GitLab Task Collector

GitLab Task Collector — это CLI-утилита для автоматической синхронизации задач из Markdown-файлов (или документации) в GitLab Issues.

Основано на шаблоне BMad (Business Markdown Architecture Definition).

Она идеально подходит для команд, которые ведут требования или документацию в коде (Docs as Code) и хотят автоматически создавать и обновлять задачи в GitLab.

✨ Возможности

🚀 Автоматическое создание задач: Превращает Markdown-файлы в GitLab Issues.
🔄 Синхронизация обновлений: Обновляет описание задачи, если файл изменился.
💬 Синхронизация комментариев: Переносит секции Dev Agent Record, QA Results и Code Review Results в комментарии к задаче.
✅ Авто-закрытие: Автоматически закрывает задачи, если в файле стоит статус Done (с флагом --close-stories).
🧠 Умное кеширование: Не создает дубликатов и обновляет задачи только при реальных изменениях.
📝 Code Review: Поддержка отдельной секции для результатов Code Review.

🚀 Быстрый старт

Вам не нужно ничего устанавливать. Просто запустите утилиту через npx:

npx gitlab-task-collector@latest \
  --token "glpat-YOUR_TOKEN" \
  --project-id "12345" \
  --url "https://gitlab.com" \
  --files "docs/**/*.md" \
  --directory "./"

Совет: Используйте @latest чтобы всегда получать последнюю версию пакета.

🛠 Установка (Опционально)

Если вы хотите установить утилиту глобально:

npm install -g gitlab-task-collector

Тогда запуск будет выглядеть так:

gitlab-task-collector --token "..." ...

⚙️ Конфигурация

Вы можете передавать параметры через аргументы командной строки, переменные окружения или файл конфигурации.

Команды

`gitlab-task-collector` (основная команда)

Синхронизирует задачи из Markdown-файлов в GitLab Issues.

`gitlab-update-milestones` (утилита обновления майлстоунов)

Массово обновляет майлстоуны задач по префиксу проекта.

Локальное использование (в процессе разработки):

# Через npm скрипт
npm run dev:update-milestones -- --project-name "ImpactOS.Core.Lib" --milestone 456 --dry-run

# Или через собранный код
npm run build
node dist/index.js update-milestones --project-name "ImpactOS.Core.Lib" --milestone 456 --dry-run

После публикации пакета:

# Используйте как подкоманду
npx gitlab-task-collector update-milestones \
  --token "glpat-YOUR_TOKEN" \
  --project-id "12345" \
  --project-name "ImpactOS.Core.Lib" \
  --milestone 456 \
  --dry-run

Эта команда:

Получит все задачи из проекта
Отфильтрует только те, которые начинаются с [ImpactOS.Core.Lib]
Обновит их майлстоун на 456 (в dry-run режиме покажет изменения без применения)

Примечание: Команда update-milestones использует те же источники конфигурации, что и основная команда: CLI аргументы, .env файл или gitlab-task-collector.config.json.

Аргументы командной строки

| Аргумент | Описание | Обязательно | Пример | | :--- | :--- | :--- | :--- | | --token, -t | Ваш GitLab Private Token (api scope) | Да* | glpat-xyz... | | --project-id, -p | ID проекта в GitLab | Да* | 12345 | | --url, -u | URL вашего GitLab инстанса | Нет | https://gitlab.company.com (по умолчанию gitlab.com) | | --files, -f | Glob-паттерн для поиска файлов | Нет | docs/**/*.md (по умолчанию **/*.md) | | --directory, -d | Базовая директория для поиска | Нет | ./src (по умолчанию текущая) | | --labels, -l | Метки для новых задач (через запятую). Внимание: При обновлении задачи старые метки полностью заменяются новыми. | Нет | backend,feature | | --close-stories | Закрывать задачи, если в файле Status: Done | Нет | (флаг) | | --project-name | Префикс для названия задачи (например, [MyLib]) | Нет | MyLib | | --milestone | ID майлстоуна в GitLab | Нет | 123 | | --assign-to-me | Автоматически назначать создаваемые задачи на владельца токена | Нет | (флаг) | | --force-assign-to-me | Принудительно переназначать существующие задачи на владельца токена при обновлении | Нет | (флаг) | | --dry-run | Тестовый запуск (без изменений в GitLab). Автоматически включает детальное логирование. | Нет | (флаг) | | --verbose | Включить детальное логирование (пути к конфигам, токен, project ID и т.д.) | Нет | (флаг) |

* Можно также задать через переменные окружения GITLAB_TOKEN и PROJECT_ID, или через файл конфигурации.

Приоритет настроек

Утилита использует следующий порядок приоритетов при загрузке настроек:

CLI аргументы > Переменные окружения (.env) > JSON конфиг > Значения по умолчанию

Это означает, что если вы передаете --url через командную строку, он переопределит значение из .env или gitlab-task-collector.config.json.

Пример файла конфигурации (.env)

Для удобства вы можете создать файл .env в корне проекта, чтобы не передавать секреты каждый раз:

# .env file
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxx
GITLAB_URL=https://gitlab.company.com
PROJECT_ID=12345
PROJECT_NAME=MyLib

И запускать утилиту просто:

npx gitlab-task-collector@latest --files "docs/**/*.md"

Файл конфигурации (JSON)

Вы также можете использовать файл gitlab-task-collector.config.json в корне проекта для хранения всех настроек:

{
  "gitlabUrl": "https://gitlab.company.com",
  "gitlabToken": "glpat-xxx", 
  "projectId": "12345",
  "filePatterns": ["docs/**/*.md"],
  "labels": ["auto-generated", "backend"],
  "projectName": "MyLib",
  "milestoneId": 123,
  "closeStories": true
}

Безопасность: Не храните токен в JSON конфиге, если этот файл попадает в Git! Используйте .env (добавьте в .gitignore) или переменные окружения.

Для команды update-milestones: Если у вас уже настроен gitlab-task-collector.config.json с параметрами projectName и milestoneId, то команда npx gitlab-update-milestones сможет использовать эти настройки автоматически без дополнительных аргументов!

🏷️ Работа с метками (Kanban)

Утилита синхронизирует метки задачи с тем, что передано в конфигурации (--labels или labels в конфиге). Важно: Это полная синхронизация. Если вы измените набор меток в конфиге, то в GitLab старые метки будут удалены, а новые добавлены.

Это позволяет имитировать движение задач по Kanban-доске:

Запускаете с --labels "Pending" -> Задача создается с меткой Pending.
Меняете в конфиге/аргументах на --labels "Doing" -> У задачи удаляется Pending и добавляется Doing.

📝 Формат Markdown-файла

Утилита ожидает, что ваши файлы задач будут иметь определенную структуру (BMad совместимую). Секции определяются заголовками любого уровня (#, ##, ###). HTML-комментарии () полностью игнорируются.

Пример файла docs/story-1.md:

# Story 1: Название вашей задачи

### Status
- Done
*(Если указан флаг --close-stories и здесь есть 'Done', задача закроется)*

### Story
Здесь идет основное описание задачи.
Оно попадет в **Description** задачи в GitLab.

Можно использовать списки, ссылки и любое форматирование.

### Dev Agent Record
Комментарии разработчика.
Эта секция будет добавлена как **комментарий** к задаче.
Полезно для трекинга технических решений.

### QA Results
Результаты тестирования.
Эта секция также будет добавлена как **отдельный комментарий**.

### Code Review Results
Результаты проверки кода.
Эта секция синхронизируется как **отдельный комментарий**.
Полезно для сохранения истории ревью и замечаний.

### Change Log
Эта секция игнорируется утилитой.

⚠️ Валидация файлов

Утилита автоматически проверяет файлы на соответствие шаблону задачи. Файлы считаются невалидными, если:

Отсутствует заголовок первого уровня (# Title). ⚠️ Важно: Заголовок задачи должен быть строго уровня 1 (#). Заголовки ## или ### не подходят для главного title.
Отсутствует описание задачи (секция ### Story или любой контент, попадающий в description)

Примечание: Внутренние секции (Story, Dev Agent Record, QA Results, Code Review Results, Status) могут использовать заголовки любого уровня (#, ##, ###), но главный заголовок задачи должен быть только уровня 1.

Как это работает:

1️⃣ Первая проверка невалидного файла:

Файл читается и парсится
Если отсутствует заголовок # Title, выводится предупреждение:
```
⚠️ Skipping file (invalid template): filename.md
```
Файл сохраняется в кеш .task-cache.json с флагом isInvalid: true

2️⃣ Последующие запуски:

Проверяется дата последней модификации файла (mtime)
Если файл не изменялся, он пропускается без чтения содержимого

В режиме --verbose выводится:

Skipping known invalid file (unchanged): filename.md

3️⃣ Если файл исправлен:

Дата модификации изменится (при сохранении файла)
Файл будет прочитан и обработан заново
Если теперь он валидный, создастся задача в GitLab

Преимущества: Это экономит время и ресурсы при работе с большими репозиториями, где могут быть README, документация и другие markdown-файлы, не являющиеся задачами.

🤖 Пример для GitLab CI

Вы можете запускать коллектор автоматически при каждом пуше в ветку документации.

.gitlab-ci.yml:

sync-tasks:
  image: node:20-alpine
  stage: deploy
  script:
    - npx gitlab-task-collector@latest --token $GITLAB_API_TOKEN --project-id $CI_PROJECT_ID --files "docs/**/*.md" --close-stories
  only:
    changes:
      - docs/**/*.md

🔒 Безопасность

Не храните токен в коде! Используйте переменные окружения или CI/CD Variables.

License: ISC