GitHub 연동
GitHub App을 한 번만 연결하면, 브랜치·제목·본문에 이슈 식별자가 들어간 PR이 해당 이슈에 자동으로 연결됩니다. 그리고 PR을 머지하면 이슈가 완료로 이동합니다.
설정 → GitHub에서 GitHub 계정 또는 조직을 한 번만 연결하세요. 그 후에는 브랜치 이름, 제목, 본문에 이슈 식별자(예: AAC-123)가 들어 있는 모든 pull request가 해당 이슈에 자동으로 연결되고, 이슈 사이드바의 Pull requests 아래에 표시되며, PR이 머지되면 이슈가 완료로 이동합니다.
이슈별 설정은 없습니다. 전체 흐름은 식별자로 동작합니다.
연동이 하는 일
| 위치 | 동작 |
|---|---|
| 설정 → GitHub | 워크스페이스 admin에게는 마스터 토글, Connect GitHub 버튼, 기능 스위치(PR 사이드바, Co-authored-by, 자동 연결)가 있는 GitHub 탭이 보입니다. 설치 후에는 GitHub 탭으로 다시 돌아옵니다. |
| 이슈 사이드바 → Pull requests | 이 이슈에 자동 연결된 모든 PR이 제목, 저장소, 상태(Open / Draft / Merged / Closed), 작성자와 함께 표시됩니다. 행을 클릭하면 GitHub의 해당 PR로 이동합니다. |
| Webhook(백그라운드) | 모든 pull_request 이벤트에서 AACWorkflow는 PR 행을 upsert하고, PR에서 이슈 식별자를 스캔한 뒤, 연결 행을 (다시) 구성합니다. 멱등성이 있어 동일 delivery를 재전송해도 변화가 없습니다. |
| 머지 시 상태 자동 변경 | PR이 merged로 전환되면, 아직 Done이나 Cancelled가 아닌 모든 연결된 이슈가 Done으로 이동합니다. 상태 변경은 source github_pr_merged로 타임라인에 기록됩니다. |
미러링되는 것은 PR 자체뿐입니다. 커밋, 열린 PR이 없는 브랜치 ref, CI 체크 상태는 모델링되지 않습니다. 이 연동은 의도적으로 좁게 설계되었습니다.
식별자 매칭 방식
Webhook은 다음 순서로 세 필드에서 식별자를 추출합니다: PR head 브랜치, PR 제목, PR 본문. 매처는 다음과 같습니다.
- 대소문자를 구분하지 않습니다 —
aac-123,AAC-123,Mul-123이 모두 매칭됩니다. - 경계가 있습니다 — 왼쪽의
\b와 오른쪽의 숫자 앵커 덕분에v1.2-3같은 버전 번호나 이메일 형식 문자열을 잘못 잡지 않습니다. - 워크스페이스 범위로 제한됩니다 — 해당 워크스페이스 고유의 이슈 prefix에만 매칭됩니다. prefix가
AAC인 워크스페이스에서는 정수가 다른 이슈와 일치하더라도FOO-1이 무시됩니다. - 중복이 제거됩니다 — 본문에
AAC-1, AAC-1을 나열해도 이슈는 한 번만 연결됩니다.
하나의 PR에서 여러 이슈를 참조할 수 있습니다. Closes AAC-1, AAC-2는 PR을 두 이슈에 모두 연결하고, 머지하면 두 이슈 모두 Done으로 진행됩니다.
머지 시 완료 자동 변경 규칙
PR의 merged 필드가 true로 바뀌면, 연결된 모든 이슈가 평가됩니다.
| 이슈 현재 상태 | 결과 |
|---|---|
done | 변화 없음(이미 종료 상태). |
cancelled | 변화 없음 — 취소됨은 사용자가 작업을 명시적으로 포기했다는 의미이므로, 연동이 이 신호를 덮어쓰지 않습니다. |
그 외 모두(todo, in_progress, in_review, blocked, backlog) | done으로 이동. |
PR을 머지하지 않고 닫으면 PR 카드의 상태만 Closed로 업데이트됩니다. 연결된 이슈는 그대로 유지됩니다 — 머지 없이 닫는 것이 무엇을 의미하는지는 사용자가 결정합니다.
이 동작은 타임라인에서 system 액터에게 귀속됩니다. 이슈 구독자는 사람이 상태를 옮겼을 때와 동일하게 상태 변경에 대한 인박스 알림을 받습니다.
자동 연결되지 않는 것
- 커밋 메시지의 식별자 — 브랜치 / 제목 / 본문만 스캔됩니다.
AAC-123: fix login이라는 제목의 커밋은 동일한 문자열이 PR 제목이나 본문에도 나타나지 않는 한 자동 연결되지 않습니다. - PR 댓글의 식별자 — PR 자체의 메타데이터만 스캔되며, 이후의 GitHub 댓글은 무시됩니다.
- App이 설치되지 않은 저장소의 PR — App이 없으면 AACWorkflow는 webhook을 전혀 받지 못합니다.
- PR을 이슈에 수동으로 연결하기 — 아직 이를 위한 UI는 없습니다. 팀의 규칙상 식별자를 AACWorkflow가 읽지 않는 위치에 둔다면, PR 제목이나 본문에 추가하세요.
연결 해제
설정 → GitHub에는 설치 목록이 없습니다 — 기존 설치는 GitHub에서 직접 관리합니다.
- GitHub에서 —
https://github.com/settings/installations(개인) 또는https://github.com/organizations/<org>/settings/installations(조직)에서 AACWorkflow GitHub App을 제거합니다. AACWorkflow는installation.deletedwebhook을 받아 실시간으로 행을 삭제하며, 열려 있는 Settings 탭은 새로고침 없이 업데이트됩니다. - AACWorkflow 내부에서의 연결 해제는 admin 전용입니다 — GitHub 탭의 연결 해제 컨트롤은 admin이 아닌 사용자에게는 숨겨집니다. 마스터 GitHub 스위치가 꺼져 있어도 계속 사용할 수 있어, admin이 원클릭으로 기능을 비활성화한 후에도 오래된 설치를 해제할 수 있습니다.
연결 해제 후에도 미러링된 PR 행은 데이터베이스에 남아 과거 이슈 사이드바에서 무엇이 연결되어 있었는지 계속 보여주지만, 해당 설치에서 새로 들어오는 webhook 이벤트는 더 이상 수락되지 않습니다.
권한 및 가시성
- 연결 / 연결 해제에는 워크스페이스 owner 또는 admin이 필요합니다. member에게는 카드 설명은 보이지만 Connect 버튼은 보이지 않습니다.
- 이슈의 Pull requests 사이드바는 해당 이슈를 읽을 수 있는 모든 사람에게 보입니다 — 이슈 상세의 나머지 부분과 동일한 권한입니다.
- GitHub App은 pull request와 메타데이터에 대한 읽기 전용 액세스를 요청합니다. AACWorkflow는 커밋, 댓글, 상태 체크를 GitHub로 다시 푸시하지 않습니다.
AACWorkflow Cloud 연동
GitHub 연동은 AACWorkflow Cloud에서 이미 구성되어 있습니다. 설정 → GitHub를 열고 Connect GitHub를 클릭해 계정이나 조직을 연결하세요. 액세스를 허용할 저장소를 선택하고 설치를 완료합니다.
설치 후, 브랜치 / 제목 / 본문에 이슈 식별자가 들어 있는 pull request는 몇 초 내에 해당 이슈에 자동으로 연결됩니다.
제한 사항
현재 알아 둬야 할 몇 가지 거친 부분이 있습니다.
- 아직 수동 연결 UI가 없습니다 — PR을 연결하는 유일한 방법은 브랜치, 제목, 본문에 식별자를 두는 것입니다.
- CI / 체크 상태가 없습니다 — PR 자체만 미러링됩니다. 빌드 상태, 리뷰 댓글, 리뷰어는 AACWorkflow에 표시되지 않습니다.
- 머지 → 완료 규칙에 대한 워크스페이스 수준 설정이 없습니다 — 고정된 기본값입니다(
cancelled가 아닌 한merged → done). 워크스페이스에서 커스터마이즈할 수 있는 매핑은 향후 추가될 예정입니다. - 하나의 이슈에 여러 PR이 연결된 경우 머지가 보수적입니다 — 두 PR이 모두
AAC-123을 참조하고 첫 번째가 머지되면, 이슈는 즉시Done으로 이동합니다. 진행하기 전에 연결된 모든 PR이 해결되기를 기다리는 후속 변경이 진행 중입니다.