GitHub 연동 — QA Note Docs

GitHub 연동이란?

QA Note의 GitHub 연동은 양방향 동기화를 지원합니다. QA Note에서 등록한 이슈가 GitHub에 자동 생성되고, GitHub에서의 상태 변경이 QA Note에 반영됩니다. 댓글과 라벨도 양쪽에서 실시간으로 동기화됩니다.

연동 설정

1. GitHub 계정 연결

프로젝트 설정 → 연동 탭에서 GitHub 연결 버튼을 클릭합니다. GitHub OAuth 인증 과정을 거쳐 계정이 연결됩니다.

연결 시 repo(이슈 생성) 및 project(GitHub Projects 접근) 권한이 요청됩니다.

2. 저장소 설정

연결 후 이슈를 동기화할 GitHub 저장소를 owner/repo 형식으로 입력합니다. 저장소를 설정하면 Webhook이 자동으로 등록되어 양방향 동기화가 활성화됩니다.

3. 자동 동기화 설정

자동 동기화가 활성화되어 있으면(기본값), QA Note에서 새 이슈를 등록할 때 GitHub 이슈가 자동으로 생성됩니다. 필요에 따라 비활성화할 수 있습니다.

동기화 범위

QA Note → GitHub

항목	동기화 내용
이슈 생성	QA Note 이슈 등록 시 GitHub 이슈 자동 생성. 스크린샷, 환경 정보, 콘솔 에러, 네트워크 에러, 사용자 액션 타임라인, 세션 리플레이 링크가 포함됩니다.
상태 변경	QA Note에서 상태를 변경하면 GitHub 이슈의 open/closed 상태와 `status:*` 라벨이 업데이트됩니다.
댓글	QA Note에서 작성한 댓글이 GitHub에 동기화됩니다. 수정, 삭제도 반영됩니다.
라벨	QA Note에서 라벨을 변경하면 GitHub 이슈의 라벨이 업데이트됩니다.

GitHub → QA Note

항목	동기화 내용
상태 변경	GitHub 이슈를 닫으면 활성 QA Note 기록이 `fix_submitted`로 전환될 수 있습니다. 활성 `status:*` 라벨은 동기화되며, GitHub reopen은 사람 검수 게이트를 우회하지 않습니다.
댓글	GitHub에서 작성한 댓글이 QA Note에 동기화됩니다. 수정, 삭제도 반영됩니다.
라벨	GitHub에서 라벨을 추가/제거하면 QA Note에 반영됩니다. 새 라벨은 자동 생성됩니다.

에코(무한 반복) 방지를 위해 5초 이내의 중복 동기화는 자동으로 무시됩니다.

상태 라벨

QA Note의 이슈 상태는 GitHub에서 status: 접두사가 붙은 라벨로 표현됩니다.

QA Note 상태	GitHub 라벨
open	`status:open`
in_progress	`status:in-progress`
blocked	`status:blocked`
fix_submitted	`status:fix-submitted`
verified	`status:verified`
closed	`status:closed`

상태는 위 6개로 고정됩니다. verified는 QA Note의 사람 세션만 선택할 수 있고, closed는 리포트 발행 시 만들어집니다.

GitHub Projects v2

GitHub Projects v2를 사용 중이라면 QA Note 이슈를 프로젝트 보드에 자동으로 추가할 수 있습니다.

설정 방법

프로젝트 설정 → 연동 탭에서 GitHub Projects 섹션을 찾습니다.
연결된 GitHub 계정의 프로젝트 목록에서 사용할 프로젝트를 선택합니다.
Status 필드를 선택합니다 (Single Select 타입 필드).
QA Note 상태와 GitHub Projects 옵션 간의 매핑을 설정합니다.

설정 후, QA Note에서 이슈를 등록하면 GitHub Projects 보드에 자동으로 추가되고, 상태가 변경되면 프로젝트 보드의 상태도 함께 업데이트됩니다.

GitHub 이슈 가져오기

기존 GitHub 이슈를 QA Note로 일괄 가져올 수 있습니다.

프로젝트 설정 → 연동 탭에서 이슈 가져오기 버튼을 클릭합니다.
미리보기에서 가져올 이슈 목록을 확인합니다.
상태, 우선순위, 담당자, 마일스톤 매핑을 설정합니다.
가져오기 시작을 클릭하면 이슈와 댓글이 순차적으로 가져와집니다.

GitHub API 호출 제한을 준수하며, 대량의 이슈도 안정적으로 가져올 수 있습니다.

커밋·배포 기록 (write-back)

GitHub 연동이 활성화되면 push 웹훅이 커밋 메시지의 이슈 키(예: QANOTE-42)를 감지해 해당 이슈를 수정 제출(fix_submitted) 로 전환하고 커밋을 이슈에 연결합니다. deployment 이벤트가 수신되면 수정 커밋의 배포 여부를 상관시켜 이슈에 '검수 가능' 을 표시합니다.

개발자가 어차피 하는 커밋에 편승하는 기록 경로이므로, 에이전트나 대시보드 없이도 처리 기록이 남습니다. 자세한 사용법은 커밋 키 참조.

권한 범위

QA Note GitHub App 은 다음 권한만 요청합니다:

Contents: Read & Write (브랜치·커밋 생성)
Pull Requests: Read & Write (PR 생성·업데이트)
Issues: Read (이슈 동기화 · 상태 라벨 반영)
Metadata: Read (저장소 기본 정보)

저장소 선택은 GitHub App 설치 시점에 지정합니다. 새 저장소를 추가하려면 GitHub 의 App 설정에서 repository selection 을 갱신하세요.

GitHub 이슈 재시도

GitHub 이슈 생성에 실패한 경우, 이슈 상세 페이지에서 재시도 버튼으로 다시 시도할 수 있습니다.