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에서 이슈를 close/reopen하거나 `status:*` 라벨을 변경하면 QA Note 상태가 업데이트됩니다.
댓글	GitHub에서 작성한 댓글이 QA Note에 동기화됩니다. 수정, 삭제도 반영됩니다.
라벨	GitHub에서 라벨을 추가/제거하면 QA Note에 반영됩니다. 새 라벨은 자동 생성됩니다.

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

상태 라벨

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

QA Note 상태	GitHub 라벨
open	`status:open`
in_progress	`status:in-progress`
resolved	`status:resolved`
closed	`status: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 호출 제한을 준수하며, 대량의 이슈도 안정적으로 가져올 수 있습니다.

AI Fix 자동 PR 생성

GitHub 연동이 활성화되어 있으면, QA Note 이슈 상세에서 AI Fix · Plan + Implement 버튼을 눌렀을 때 Claude Code 가 생성한 수정본이 해당 GitHub 저장소에 PR 로 직접 push 됩니다.

전제 조건

GitHub 연동에서 QA Note GitHub App 이 해당 저장소에 설치되어 있어야 합니다.
저장소 기본 브랜치(main · master) 외 브랜치 생성 권한이 있어야 합니다.
Vercel 연동도 활성화되어 있으면 PR 생성과 동시에 Preview 배포가 트리거됩니다. Vercel 연동.

PR 생성 흐름

단계	주체	결과
① Plan	Claude Code	수정 계획 텍스트 작성
② Branch	QA Note GitHub App	`qanote/fix/{issue}-{short}` 브랜치 생성
③ Commit	Claude Code	변경사항 커밋·push
④ PR	QA Note GitHub App	PR #N 생성 · 이슈에 링크

PR 본문에는 QA Note 이슈 permalink 가 자동 포함됩니다. 상세 파이프라인은 AI Fix · 자동 PR 가이드 참조.

권한 범위

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

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

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

GitHub 이슈 재시도

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