GitHub PR 댓글 동기화

GitHub PR과 AACWorkflow 간 양방향 댓글 동기화 — 논의를 한 곳에 유지합니다.

GitHub PR 댓글 동기화 기능은 GitHub pull request와 AACWorkflow 간 댓글을 동기화하여 팀 논의를 양쪽에서 통일되고 최신 상태로 유지합니다.

작동 원리

동기화 방향

GitHub → AACWorkflow: 누군가 GitHub PR에 댓글을 게시하면 AACWorkflow는 이를 연결된 issue(있는 경우)로 미러링합니다. 댓글은 GitHub 사용자에게 귀속되며 GitHub 배지로 표시됩니다.

AACWorkflow → GitHub: 누군가 연결된 GitHub PR이 있는 AACWorkflow issue에 댓글을 남기면 AACWorkflow는 PR 스레드에 댓글을 게시합니다(구성된 경우).

댓글 동기화는 issue별 선택적입니다. 플랫폼 간 확산하지 않아야 하는 민감한 논의의 경우 비활성화할 수 있습니다.

예시 흐름

PR 생성: #123 Add OAuth support
PR 제목이 AACWorkflow issue와 일치: AAC-42
Issue 페이지 표시: Pull requests → #123 Add OAuth support
검토자가 PR에 댓글 게시: 「Good approach, but let's add type safety to the token handler」
AACWorkflow가 자동으로 댓글을 issue 스레드로 미러링
팀원이 두 곳 모두에서 동일한 피드백 보기

댓글 메타데이터

동기화된 댓글은 출처를 알 수 있도록 메타데이터를 포함합니다:

배지	출처	동기화 방향
🐙 GitHub	GitHub PR에 게시된 댓글	GitHub → AACWorkflow
✅ AACWorkflow	AACWorkflow에 게시된 댓글	AACWorkflow → GitHub

댓글을 볼 때 다음이 표시됩니다:

원래 작성자 — GitHub 사용자명 또는 AACWorkflow 사용자
원래 타임스탬프 — 댓글 처음 게시 시간
원본 링크 — 클릭하여 출처로 이동 (GitHub PR 또는 AACWorkflow 스레드)

동기화 동작 제어

Issue별 동기화 설정

연결된 PR이 있는 issue로 이동합니다. Pull requests 섹션에서 PR 행을 클릭하여 PR 패널을 엽니다. 토글:

댓글 동기화 → 켜짐/꺼짐

켜짐일 때, PR의 새 댓글이 AACWorkflow로 미러링됩니다. 기존 댓글은 소급 동기화되지 않습니다.

꺼짐일 때, 링크는 유지됨 (참고용) 하지만 새 댓글은 미러링되지 않습니다.

워크스페이스 전체 동기화 정책

설정 → GitHub → 댓글 동기화 정책으로 가서 기본값 설정:

정책	동작
항상 동기화 (기본값)	모든 PR 댓글 자동 미러링
PR별 옵트인	사용자가 명시적으로 활성화한 PR에만 동기화
동기화 안 함	모든 동기화 비활성화; 링크는 참고용만

개별 issue는 워크스페이스 정책을 무시할 수 있습니다.

댓글 중복 제거

동시에 GitHub와 AACWorkflow 모두에 댓글을 게시하는 경우 (드문), AACWorkflow는 멱등성 키를 사용하여 중복을 피합니다. 시스템 확인:

작성자 + 타임스탬프 + 첫 100자 내용 = 고유 신원
10초 내 중복 게시 → 중복 제거

수정 및 개인정보

댓글의 민감한 정보는 자동 수정되지 않습니다. 댓글에 비밀 (API 키, 토큰, 자격증명)이 포함되어 있다면:

출처에서 즉시 삭제 (GitHub 또는 AACWorkflow)
삭제는 동기화되지 않음 — 두 사본을 수동으로 삭제해야 합니다
pre-commit 훅 사용을 고려하여 비밀이 어떤 플랫폼에도 도달하기 전에 포착

댓글에 비밀, API 키 또는 자격증명을 게시하지 마세요. 둘 다 플랫폼으로 미러링될 수 있습니다.

스레드 및 컨텍스트

PR 댓글은 AACWorkflow issue에 스레드 답글로 동기화됩니다:

GitHub PR: 특정 줄/파일의 검토 댓글
AACWorkflow: 인라인 댓글이 issue 타임라인의 PR 댓글 섹션으로 수집됨

GitHub PR 스레드 내의 답글이 AACWorkflow의 중첩된 답글로 동기화됩니다.

제한사항

동기화 안 됨: PR 검토 이벤트 (승인/변경 요청), 커밋 댓글, 파일 특정 검토 댓글은 PR 수준 스레드로만 매핑
특정 이벤트 단방향: GitHub PR 「준비 완료」상태는 AACWorkflow 상태 변경으로 매핑되지 않음
댓글 편집: GitHub의 편집은 동기화됨 (업데이트된 타임스탐프 표시); AACWorkflow의 편집은 GitHub로 동기화되지 않음 (GitHub API 제한)
댓글 삭제: 양쪽의 삭제는 동기화되지 않음; 두 사본을 수동으로 삭제해야 함

API

PR에 대해 댓글 동기화

POST /api/issues/{issue_id}/github/pr/{pr_number}/sync-comments

이 PR에 대해 수동으로 댓글 동기화 트리거. 반환:

{
  "synced_count": 5,
  "new_comments": 3,
  "updated_comments": 2,
  "skipped": 0
}

Issue에 대해 동기화된 댓글 나열

GET /api/issues/{issue_id}/github/pr-comments

반환:

{
  "comments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "pr_number": 123,
      "github_comment_id": "1234567890",
      "author": "jane-smith",
      "author_type": "github",
      "body": "Good approach, but let's add type safety...",
      "created_at": "2025-06-22T15:30:00Z",
      "synced_at": "2025-06-22T15:30:05Z",
      "url": "https://github.com/org/repo/pull/123#discussion_r1234567890"
    }
  ]
}

Issue에 대해 동기화 비활성화

PATCH /api/issues/{issue_id}/github/sync

Body:

{
  "sync_pr_comments": false
}

문제 해결

「GitHub의 댓글이 표시되지 않음」

PR 패널에서 댓글 동기화가 활성화되어 있는지 확인
워크스페이스 동기화 정책 확인 (설정 → GitHub)
30초 대기 — 동기화는 백그라운드 워커에서 실행
여전히 누락되면 지금 동기화 클릭하여 강제 새로고침

「댓글이 GitHub에 표시되지만 AACWorkflow에는 없음」

GitHub PR이 AACWorkflow issue와 연결되어 있는지 확인
Issue 페이지 → Pull requests 섹션 확인
PR이 나열되지 않으면 GitHub issue/PR 가져오기 재실행 (설정 → GitHub)

「AACWorkflow에 댓글을 게시했지만 GitHub에 없음」

이 PR에 대해 댓글 동기화가 활성화되어 있는지 확인
GitHub 리포에 쓰기 권한이 있는지 확인
Issue 감사 로그 확인 (설정 → 감사) 동기화 오류 확인

「같은 댓글이 여러 번 표시됨」

동기화가 수동으로 트리거되는 동시에 (/sync-comments) 백그라운드 워커도 실행 중이면 발생 가능. 중복에서 삭제 클릭하면 양쪽에서 제거됨 (원클릭 정리).

모범 사례

코드 검토에 GitHub 사용 — 자세한 라인별 피드백
작업 컨텍스트에 AACWorkflow 사용 — PR 생성 이유, 의존 사항
PR 조기 링크 — 브랜치명 또는 PR 제목에 issue ID 언급하여 자동 감지
수동 크로스 포스트 금지 — 양쪽에 동일 댓글 붙여넣기 금지; 동기화가 처리하도록
큰 PR 전 설정 검토 — 큰 팀 PR 전 동기화 정책 설정하여 중복 방지