GitHub PR Поток создания

Агенты могут создавать и обновлять pull requests на GitHub как часть их выполнения задачи. GitHub PR Creation Flow обрабатывает:

• Создание нового PR с названием, описанием и веткой
• Линкование PR с AACWorkflow issue (автообнаружение через ID issue)
• Обновление описания PR и статуса
• Обработка merge конфликтов и CI проверок

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

Создание PR

Когда агент завершает работу над функцией, он может:

1. Пушить ветку в GitHub с кодом функции
2. Открыть PR с описательным названием и телом
3. Название или тело должно содержать ID AACWorkflow issue (например, AAC-42)
4. AACWorkflow обнаруживает ID и автолинкует PR

Пример названия PR:

AAC-42: Add OAuth 2.1 authorization to MCP endpoint

Пример тела PR:

## Description
Implements OAuth 2.1 authorization server for MCP clients per spec.

## Changes
- Add /oauth/authorize, /oauth/token endpoints
- Implement PKCE + refresh-token rotation
- Add RFC 8414 metadata discovery

## Issue
Closes AAC-42

## Testing
- [x] Unit tests for OAuth flows
- [x] Integration test for PKCE verification

Автолинкование

Когда PR создан:

1. AACWorkflow сканирует название и тело на идентификаторы issues (без учёта регистра: AAC-42, aac-42, и т.д.)
2. Если найдено и issue существует в workspace'е, PR автолинкован
3. Страница issue показывает PR в разделе Pull requests

Обновление описания PR

После создания PR, агенты могут обновить описание чтобы:

• Добавить результаты тестов или скриншоты
• Линковать зависимые PR
• Обновить статус («Ready for review», «WIP», и т.д.)

Обновления синхронизируются обратно в AACWorkflow через вебхук.

Жизненный цикл PR

Автоперемещение при слиянии

Когда PR слит, каждый связанный issue (если не уже Done или Cancelled) автоматически переходит в Done статус вашего workspace'а.

Пример:

• PR #123 (Closes AAC-42, AAC-43) слит
• Issue AAC-42 → переходит в Done
• Issue AAC-43 → переходит в Done
• Issue AAC-99 → остаётся в текущем статусе (не был линкован)

Это происходит автоматически через GitHub вебхук.

Стратегия веток

Рекомендуемое именование веток

Используйте ID issue в названии ветки для ясности:

feature/aac-42-oauth-mcp
fix/aac-99-login-timeout
refactor/aac-55-query-optimization

AACWorkflow не требует этого, но это:

• Делает историю проще для навигации на GitHub
• Помогает разработчикам помнить над какой задачей они работают
• Делает очевидным какая ветка закрывает какой issue

Защита веток

Правила защиты веток вашего GitHub репо применяются (например, «require PR reviews before merge»). AACWorkflow их уважает.

Если код агента не соответствует требованиям:

• PR не будет слит
• Issue остаётся в текущем статусе
• Агент может повторить попытку или запросить помощь человека

Индикаторы статуса PR

На странице issue, раздел Pull requests показывает:

Кликните строку PR чтобы перейти на GitHub.

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

Merge конфликты

Если ветка агента конфликтует с main:

1. Агент обнаруживает конфликт при push
2. Агент может:
   • Rebase ветку и повторить
   • Запросить помощь человека (постить комментарий на issue)
   • Закрыть PR и начать заново

Выбор зависит от инструкций агента и уровня автономии.

Ошибки CI проверок

Если GitHub CI проверки не пройдены (тесты, линтирование, сканирование безопасности):

1. PR показывает ❌ статус проверки
2. Агент может:
   • Исправить проблемы и пушить новый коммит
   • Запросить отзыв человека на падающих проверках
   • Закрыть PR если проблемы блокирующие

Страница issue показывает статус CI проверки. Админы могут настроить политики чтобы заблокировать слияние пока проверки не пройдены.

API

Получить линкованный PR для issue

GET /api/issues/{issue_id}

Ответ включает:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Add OAuth to MCP",
  "status": "in_progress",
  "pull_requests": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "pr_number": 123,
      "repo": "org/repo",
      "title": "AAC-42: Add OAuth 2.1 authorization",
      "url": "https://github.com/org/repo/pull/123",
      "state": "merged",
      "merged_at": "2025-06-22T16:00:00Z"
    }
  ]
}

Список PR для workspace'а

GET /api/workspaces/{ws}/github/pull-requests

Возвращает все PR созданные агентами в этом workspace'е, с пагинацией.

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

• Права веток: агенты пушат в feature ветки; админы контролируют кто может слить в main
• Атрибуция коммитов: коммиты агентов приписываются bot пользователю GitHub App (настроен в Настройки → GitHub)
• Редакция описания PR: секреты в телах PR редактируются перед сохранением в AACWorkflow
• Лог аудита: каждое действие PR (создание, обновление, слияние) логируется

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

"PR создан но не линкован к issue"

1. Проверьте заголовок/тело PR на ID issue (например, AAC-42)
2. Проверьте что issue существует в вашем workspace'е
3. Проверьте что префикс workspace'а совпадает (например, PR говорит AAC-42 но префикс workspace'а FOO)
4. Вручную линкуйте через страницу issue → Pull requests → + Link PR

"Агент не может пушить в GitHub"

1. Проверьте GitHub App имеет доступ на запись к репо
2. Проверьте что кредитиалы GitHub агента ещё валидны
3. Перейдите в Настройки → GitHub → проверьте статус установки
4. Переподключите app если нужно

"PR слит но issue не переместился в Done"

1. Проверьте PR был линкован к issue (должен показываться в строке PR)
2. Проверьте что статус issue позволяет переходы в Done
3. Вручную переместите issue в Done через UI
4. Проверьте лог аудита на ошибки

"Агент постоянно получает merge конфликты"

1. Агент может работать на устаревшей ветке; поощряйте частые pulls
2. Проверьте если несколько агентов изменяют одни и те же файлы
3. Рассмотрите распределение работы одному агенту per файл/функция
4. Используйте политики одобрения чтобы обеспечить code review перед слиянием

Связанные функции

• GitHub интеграция — см. GitHub integration
• PR комментарии синхронизация — см. GitHub PR Comments Sync
• Политики одобрения — см. Approval Policies