GitHub PR 생성 흐름

에이전트는 작업 실행의 일부로 GitHub에서 pull request를 생성하고 업데이트할 수 있습니다. GitHub PR 생성 흐름은 다음을 처리합니다:

• 제목, 설명 및 브랜치로 새 PR 생성
• PR을 AACWorkflow issue로 링크 (issue ID 통해 자동 감지)
• PR 설명 및 상태 업데이트
• Merge 충돌 및 CI 검사 처리

작동 원리

PR 생성

에이전트가 기능 작업을 완료하면:

1. 기능 코드가 있는 브랜치를 GitHub로 푸시
2. 설명적인 제목과 본문으로 PR 열기
3. 제목 또는 본문에 AACWorkflow issue ID 포함 (예: 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가 제목과 본문을 스캔하여 issue 식별자 찾기 (대소문자 무시: AAC-42, aac-42 등)
2. 발견되고 issue가 워크스페이스에 존재하면 PR 자동 링크
3. Issue 페이지가 Pull requests 섹션에 PR 표시

PR 설명 업데이트

PR 생성 후 에이전트는 설명을 업데이트할 수 있습니다:

• 테스트 결과 또는 스크린샷 추가
• 의존 PR 링크
• 상태 업데이트 (「준비 완료」, 「WIP」 등)

업데이트는 webhook을 통해 AACWorkflow로 동기화됩니다.

PR 생명 주기

병합 시 자동 이동

PR이 병합되면, 모든 관련 issue (이미 완료 또는 취소 아님)가 자동으로 워크스페이스의 완료 상태로 이동합니다.

예시:

• PR #123 (Closes AAC-42, AAC-43) 병합됨
• Issue AAC-42 → 완료로 이동
• Issue AAC-43 → 완료로 이동
• Issue AAC-99 → 현재 상태 유지 (링크되지 않음)

GitHub webhook을 통해 자동으로 발생합니다.

브랜치 전략

권장되는 브랜치 명명

분명함을 위해 브랜치명에 issue ID 사용:

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

AACWorkflow는 이를 요구하지 않지만:

• GitHub 히스토리 탐색이 더 쉬움
• 개발자가 작업 중인 issue 기억에 도움
• 어떤 브랜치가 어떤 issue를 종료하는지 명백

브랜치 보호

GitHub 리포의 브랜치 보호 규칙이 적용됩니다 (예: 「병합 전 PR 검토 필요」). AACWorkflow가 이를 존중합니다.

에이전트 코드가 요구사항을 충족하지 않으면:

• PR이 병합되지 않음
• Issue는 현재 상태 유지
• 에이전트가 재시도하거나 수동 도움 요청 가능

PR 상태 지표

Issue 페이지에서 Pull requests 섹션 표시:

PR 행을 클릭하여 GitHub로 이동합니다.

충돌 해결

Merge 충돌

에이전트 브랜치가 main과 충돌하면:

1. 에이전트가 push 시 충돌 감지
2. 에이전트는:
   • 브랜치를 Rebase하고 재시도
   • 수동 도움 요청 (issue에 댓글 게시)
   • PR 종료하고 다시 시작

선택은 에이전트 지침과 자율성 수준에 따름.

CI 검사 실패

GitHub CI 검사가 실패하면 (테스트, lint, 보안 스캔):

1. PR이 ❌ 검사 상태 표시
2. 에이전트는:
   • 문제 수정하고 새 커밋 푸시
   • 수동 검토 요청 실패한 검사
   • 문제가 차단하면 PR 종료

Issue 페이지가 CI 검사 상태 표시. 관리자는 검사 통과 전 병합을 차단하는 정책 구성 가능.

API

Issue에 대해 링크된 PR 가져오기

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 나열

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

이 워크스페이스에서 에이전트가 생성한 모든 PR 반환, 페이지 나눔.

보안

• 브랜치 권한: 에이전트는 기능 브랜치로 푸시; 관리자가 main으로 병합 가능자 제어
• 커밋 귀속: 에이전트 커밋이 GitHub App bot 사용자에게 귀속 (설정 → GitHub에서 구성)
• PR 설명 편집: PR 본문의 비밀이 AACWorkflow에 저장 전 편집됨
• 감사 추적: 모든 PR 동작 (생성, 업데이트, 병합) 기록됨

문제 해결

「PR이 생성되었지만 issue로 링크되지 않음」

1. PR 제목/본문에서 issue ID 확인 (예: AAC-42)
2. 워크스페이스에 issue가 존재하는지 확인
3. 워크스페이스 접두사 일치 확인 (예: PR이 AAC-42이지만 워크스페이스 접두사가 FOO)
4. Issue 페이지 → Pull requests → + PR 링크로 수동 링크

「에이전트가 GitHub로 푸시 불가」

1. GitHub App이 리포에 쓰기 권한 있는지 확인
2. 에이전트 GitHub 자격증명이 여전히 유효한지 확인
3. 설정 → GitHub로 이동 → 설치 상태 확인
4. 필요시 app 재연결

「PR이 병합되었지만 issue가 완료로 이동하지 않음」

1. PR이 issue로 링크되었는지 확인 (PR 행에 표시되어야 함)
2. Issue 상태가 완료로의 전환을 허용하는지 확인
3. UI를 통해 수동으로 issue를 완료로 이동
4. 오류를 위해 감사 로그 확인

「에이전트가 계속 merge 충돌 얻음」

1. 에이전트가 오래된 브랜치에서 작업할 수 있음; 자주 pull 장려
2. 여러 에이전트가 동일 파일 수정하는지 확인
3. 파일/기능별 단일 에이전트 작업 배정 고려
4. 병합 전 코드 검토 보장하는 승인 정책 사용

관련 기능

• GitHub 통합 — GitHub 통합 참조
• PR 댓글 동기화 — GitHub PR 댓글 동기화 참조
• 승인 정책 — 승인 정책 참조