GitHub Issue Импорт и экспорт

Функция GitHub Issue Import & Export позволяет командам привнести существующие GitHub issues в AACWorkflow и держать их синхронизированными. Это необходимо для команд, которые уже отслеживают работу в GitHub Issues но хотят использовать AI агентов AACWorkflow без потери их backlog'а.

Обзор

Эта функция предоставляет:

• Одноразовый импорт — загрузить открытые GitHub issues в AACWorkflow как backlog
• Обратные ссылки — каждый импортированный issue имеет ссылку обратно на его GitHub URL
• Двусторонняя синхронизация полей — название, описание и статус остаются синхронизированными с обеих сторон
• Разрешение конфликтов — когда обе стороны меняют данные, применить настраиваемую стратегию (последний писал, AACWorkflow выигрывает, GitHub выигрывает)
• Пауза/возобновление — остановить синхронизацию конкретного issue без отключения интеграции

Поддерживаемые поля

Примечание: Только первый GitHub исполнитель синхронизируется. Исполнители-агенты в AACWorkflow никогда не экспортируются в GitHub.

Рабочий процесс импорта

Шаг 1: Активируйте импорт

Перейдите в Настройки → GitHub и нажмите Импортировать Issues. Вы увидите форму:

Импортировать из: owner/repo Фильтры:

• Статус: open, closed или оба
• Labels: опциональный фильтр (например, bug, feature)
• Начиная с: опциональный фильтр по дате

Нажмите Импорт. AACWorkflow:

1. Загружает соответствующие issues из GitHub через GitHub App token
2. Для каждого issue без существующего сопоставления создаёт AACWorkflow issue
3. Записывает сопоставление в таблицу external_issue
4. Возвращает { imported: 42, skipped: 0, mappings: [...] }

Шаг 2: Проверьте сопоставления

Перейдите в Настройки → GitHub → Issue Mappings. Вы увидите таблицу всех синхронизированных issues:

Нажмите любую строку чтобы:

• Посмотреть обратную ссылку на GitHub issue
• Пауза/возобновление синхронизации для этого issue
• Вручную активировать синхронизацию сейчас

Двусторонняя синхронизация

Направления синхронизации

GitHub → AACWorkflow (вебхук): Когда GitHub issue отредактирован, GitHub посылает вебхук. AACWorkflow применяет изменённые поля (название, описание, статус) к сопоставленному AACWorkflow issue.

AACWorkflow → GitHub (работник): Когда AACWorkflow issue обновлён, фоновый работник дебаунсит изменение и PATCH'ит GitHub issue.

Периодическая сверка: Каждые 30 минут AACWorkflow проверяет issues которые недавно не синхронизировались (например, пропущенные вебхуки) и сверяет их.

Разрешение конфликтов

Если и GitHub и AACWorkflow изменили данные с последней синхронизации, конфликт разрешается используя стратегию синхронизации workspace'а:

Важно: Когда конфликт разрешается, проигравшее значение не потеряно — оно записывается в комментарий-аудит на AACWorkflow issue:

Synced from GitHub: Title changed from "Add OAuth" to "Add OAuth 2.1"
(AACWorkflow version: "Add OAuth" was overwritten by GitHub at 2025-06-22 15:30 UTC)

Пример: Одновременные редактирования

Сценарий: Вы редактируете название в AACWorkflow пока товарищ по команде редактирует тот же issue на GitHub.

1. AACWorkflow название: "Fix login timeout" → "Fix auth timeout" (вы изменили)
2. GitHub название: "Fix login timeout" → "Fix login session bug" (товарищ изменил)
3. Обе изменения прибывают в окно сверки

Разрешение (предполагая newest_wins):

• GitHub updated_at: 2025-06-22 15:30:00
• AACWorkflow updated_at: 2025-06-22 15:29:45
• Результат: GitHub версия выигрывает → AACWorkflow название становится "Fix login session bug"
• Аудит: Комментарий-аудит записывает конфликт и что было перезаписано

Пауза / Возобновление синхронизации

Чтобы остановить синхронизацию конкретного issue (например, вы делаете детальную работу в AACWorkflow и не хотите чтобы GitHub изменения вмешивались):

1. Перейдите в Настройки → GitHub → Issue Mappings
2. Нажмите строку issue
3. Переключите Sync enabled → OFF

Синхронизация паузирована только для этого issue. Другие issues продолжают синхронизироваться нормально.

Чтобы возобновить:

1. Переключите Sync enabled → ON
2. Нажмите Sync now чтобы сверить немедленно

Рабочий процесс отключения

Если вы отключите GitHub App от вашего workspace'а:

1. Все external_issue сопоставления каскадно удалены
2. AACWorkflow issues остаются (они не удаляются)
3. Обратные ссылки удаляются со страниц issues
4. Исторический аудит сохраняется для соответствия

Если вы переподключитесь позже, вам понадобится повторно импортировать чтобы пересоздать сопоставления.

API

Пример: Импорт через API

curl -X POST https://aacworkflow.example.com/api/workspaces/my-ws/github/issues/import \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_owner": "my-org",
    "repo_name": "my-repo",
    "filters": {
      "state": "open",
      "labels": ["bug"],
      "since": "2025-01-01T00:00:00Z"
    }
  }'

Возвращает:

{
  "imported": 12,
  "skipped": 0,
  "mappings": [
    {
      "external_issue_id": "...",
      "issue_id": "...",
      "gh_issue_number": 123,
      "html_url": "https://github.com/my-org/my-repo/issues/123",
      "sync_enabled": true
    }
  ]
}

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

• Все запросы отфильтрованы по workspace_id — нет утечки данных между workspace'ами
• Подписи вебхуков проверяются перед обработкой
• Токены установки никогда не открыты клиенту
• Синхронизация исполнителя только сопоставляет проверенных членов workspace'а (никогда не создаёт приглашения)

Non-goals (будущие версии)

Следующие намеренно НЕ поддерживаются в v1:

• Импорт GitHub Projects (boards), milestones или labels как первоклассных объектов
• Синхронизация комментариев в реальном времени (отдельная спец: github-pr-comments-sync.md)
• Создание новых GitHub issues из AACWorkflow (экспорт ограничен issues которые были импортированы)

Устранение проблем

"Импорт не пройдён: permission denied"

Вероятно, у вас нет админских прав в workspace'е. Только админы workspace'а могут активировать импорт.

"Некоторые issues были пропущены (synced 40, skipped 2)"

Пропущенные issues уже имеют сопоставление. Повторный импорт на том же репо идемпотентен — ранее импортированные issues не пересоздаются.

"Название изменилось но не синхронизировалось в GitHub"

Работник синхронизации запускается каждые 30 секунд (дебаунсирован). Если изменение не синхронизировалось в течение 5 минут:

1. Перейдите в Настройки → GitHub → Issue Mappings
2. Нажмите строку issue
3. Нажмите Sync now чтобы принудительно сверить
4. Проверьте лог аудита на ошибки

"Конфликт постоянно происходит с тем же issue"

Вы можете редактировать issue на обеих сторонах часто. Рассмотрите:

1. Установку стратегии синхронизации на aac_wins чтобы приоритизировать AACWorkflow
2. Паузу синхронизации пока делаете массовые редактирования, затем возобновление
3. Использование только одной стороны для редактирования пока интеграция не стабилизируется