GitHub Issue 가져오기 및 내보내기

GitHub Issue 가져오기 및 내보내기 기능을 통해 팀은 기존 GitHub issue를 AACWorkflow로 가져오고 동기화 상태를 유지할 수 있습니다. 이는 이미 GitHub Issues에서 작업을 추적하면서 백로그를 잃지 않고 AACWorkflow AI 에이전트를 도입하려는 팀에 필수적입니다.

개요

이 기능 제공:

• 원타임 가져오기 — 개방 GitHub issue를 AACWorkflow 백로그로 가져오기
• 역링크 레코드 — 각 가져온 issue에는 GitHub URL로의 참조 있음
• 양방향 필드 동기화 — 제목, 설명, 상태가 양쪽에서 동기화 유지
• 충돌 해결 — 양쪽이 변경되면 구성 가능한 전략 적용 (최신 우선, AACWorkflow 우선, GitHub 우선)
• 일시 중지/재개 — 통합을 끊지 않고 특정 issue 동기화 중지

지원되는 필드

참고: 첫 번째 GitHub 담당자만 동기화됩니다. AACWorkflow의 에이전트 담당자는 GitHub로 내보내지지 않습니다.

가져오기 워크플로우

단계 1: 가져오기 트리거

설정 → GitHub 로 이동하여 Issue 가져오기 클릭. 폼이 표시됩니다:

다음에서 가져오기: owner/repo 필터:

• 상태: open, closed 또는 둘 다
• 레이블: 선택적 필터 (예: bug, feature)
• 시간: 선택적 날짜 필터

가져오기 클릭. AACWorkflow는:

1. GitHub App token으로 GitHub에서 일치하는 issue 가져오기
2. 기존 매핑이 없는 각 issue에 대해 AACWorkflow issue 생성
3. external_issue 테이블에 매핑 기록
4. { imported: 42, skipped: 0, mappings: [...] } 반환

단계 2: 매핑 검토

설정 → GitHub → Issue 매핑 으로 이동. 모든 동기화된 issue의 테이블이 표시됩니다:

행을 클릭하면:

• GitHub issue로의 역링크 보기
• 해당 issue의 동기화 일시 중지/재개
• 지금 동기화 수동 트리거

양방향 동기화

동기화 방향

GitHub → AACWorkflow (webhook): GitHub issue 편집 시 GitHub가 webhook 전송. AACWorkflow는 변경된 필드 (제목, 설명, 상태)를 매핑된 AACWorkflow issue에 적용합니다.

AACWorkflow → GitHub (worker): AACWorkflow issue 업데이트 시 백그라운드 워커가 변경을 디바운스하고 GitHub issue를 PATCH합니다.

정기적인 조정: 30분마다 AACWorkflow는 최근에 동기화되지 않은 issue(예: 놓친 webhook)를 확인하고 조정합니다.

충돌 해결

GitHub와 AACWorkflow가 마지막 동기화 후 모두 변경되면 워크스페이스의 동기화 전략 을 사용하여 충돌을 해결합니다:

중요: 충돌이 해결될 때 손실된 값은 손실되지 않음 — AACWorkflow issue의 감사 댓글에 기록됩니다:

GitHub에서 동기화: 제목 「OAuth 추가」에서 「OAuth 2.1 추가」로 변경
(AACWorkflow 버전: 「OAuth 추가」가 2025-06-22 15:30 UTC에 GitHub로 덮어씌워짐)

예: 동시 편집

시나리오: AACWorkflow에서 제목을 편집하면서 팀원이 GitHub에서 같은 issue를 편집합니다.

1. AACWorkflow 제목: 「로그인 타임아웃 수정」 → 「인증 타임아웃 수정」(당신이 변경)
2. GitHub 제목: 「로그인 타임아웃 수정」 → 「로그인 세션 버그 수정」(팀원이 변경)
3. 두 변경사항이 조정 윈도우 내에 도착

해결 (「최신_우선」가정):

• GitHub updated_at: 2025-06-22 15:30:00
• AACWorkflow updated_at: 2025-06-22 15:29:45
• 결과: GitHub 버전 우선 → AACWorkflow 제목이 「로그인 세션 버그 수정」으로 변경
• 감사 추적: 감사 댓글이 충돌과 덮어씌운 내용 기록

일시 중지 / 재개 동기화

특정 issue의 동기화 중지 (예: AACWorkflow에서 상세 작업 중이고 GitHub 변경이 방해하는 걸 원하지 않음):

1. 설정 → GitHub → Issue 매핑 으로 이동
2. issue 행 클릭
3. 동기화 활성화 토글 → 비활성화

해당 issue의 동기화만 일시 중지됩니다. 다른 issue는 정상 동기화 계속.

재개하려면:

1. 동기화 활성화 토글 → 활성화
2. 지금 동기화 클릭하여 즉시 조정

연결 해제 워크플로우

워크스페이스에서 GitHub App 연결을 해제하면:

1. 모든 external_issue 매핑이 계단식 삭제됨
2. AACWorkflow issue는 유지됨 (삭제되지 않음)
3. 역링크가 issue 페이지에서 제거됨
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로 필터링됨 — 워크스페이스 간 데이터 누수 없음
• 웹훅 서명 처리 전 검증됨
• 설치 토큰은 클라이언트에 노출되지 않음
• 담당자 동기화는 검증된 워크스페이스 멤버만 매핑 (초대 생성 안 함)

비목표 (향후 버전)

다음은 v1에서 의도적으로 지원되지 않음:

• GitHub Projects (보드), 마일스톤 또는 레이블을 일급 객체로 가져오기
• 실시간 댓글 동기화 (별도 사양: github-pr-comments-sync.md)
• AACWorkflow에서 새 GitHub issue 생성 (내보내기는 가져온 issue로 제한)

문제 해결

「가져오기 실패: 권한 거부」

워크스페이스에 관리자 권한이 없을 수 있습니다. 워크스페이스 관리자만 가져오기 트리거 가능합니다.

「일부 issue가 건너뛰어짐 (동기화됨 40, 건너뜀 2)」

건너뛴 issue는 이미 매핑이 있습니다. 같은 리포에 다시 가져오기는 멱등성 — 이전에 가져온 issue는 다시 생성되지 않습니다.

「제목이 변경되었지만 GitHub로 동기화되지 않음」

동기화 워커는 30초마다 실행됨 (디바운스됨). 5분 내에 변경이 동기화되지 않으면:

1. 설정 → GitHub → Issue 매핑 으로 이동
2. issue 행 클릭
3. 지금 동기화 클릭하여 강제 즉시 조정
4. 오류에 대해 감사 로그 확인

「같은 issue로 충돌이 계속 발생」

양쪽에서 자주 issue를 편집할 수 있습니다. 다음 고려:

1. 동기화 전략을 aac_wins로 설정하여 AACWorkflow 우선
2. 대량 편집 시 동기화 일시 중지, 그 후 재개
3. 통합이 안정화될 때까지 한쪽에서만 편집 사용