GitHub Issues 연결: 단계별 가이드
실패한 테스트마다 GitHub 이슈를 하나씩 생성하고, 같은 테스트가 다시 실패하면 해당 이슈에 댓글을 남기며, 테스트가 정상적으로 통과하면 이슈를 닫습니다. GitHub는 파일 업로드를 지원하지 않으므로 스크린샷을 첨부하는 대신 이슈에 증거 자료 폴더 이름을 기재합니다. 이 가이드는 처음부터 연결을 설정하고 확인하는 과정과 발생할 수 있는 오류의 원인 및 해결 방법을 안내합니다.
최종 업데이트:
자격 증명은 비공개로 유지하세요. 토큰, 키, 비밀번호, 웹후크 URL을 채팅에 붙여넣지 마세요. Studio → 설정 → 연동에만 입력하세요. 입력한 정보는 작업 공간의 .env 파일에 저장되며 점으로 표시됩니다. AI 도우미도 마찬가지입니다: 이 안내를 따라 진행하도록 도와줄 수는 있지만, 토큰을 알려줄 필요는 없습니다.
준비 사항
- 저장소에 이슈를 생성할 수 있는 GitHub 계정(공동 작업자 또는 소유자).
- 이슈 기능이 활성화된 저장소(저장소 설정 → 기능 → 이슈).
- 해당 저장소에 대해 이슈 → 읽기 및 쓰기 권한이 있는 세분화된 개인 액세스 토큰 또는 repo 범위가 있는 클래식 토큰.
자격 증명 발급
- https://github.com/settings/personal-access-tokens/new 에 접속합니다(세분화된 토큰).
- 이름과 만료일을 설정하고, 저장소 액세스에서 선택한 저장소만을 선택한 다음 이슈를 생성할 저장소를 고릅니다.
- 권한 → 저장소 권한에서 이슈를 읽기 및 쓰기로 설정합니다. 다른 권한은 필요하지 않습니다.
- 토큰을 생성하고 바로 복사합니다. GitHub에서는 토큰을 한 번만 표시합니다. Studio(다음 단계) 외에는 어디에도 붙여넣지 마세요.
Studio에서 연결
- Studio에서 설정 → 연동 → GitHub Issues 연결을 엽니다.
- 입력 요청이 표시되면 토큰을 입력하고 저장 및 확인을 누릅니다. Studio에 토큰 소유자와 접근 가능한 저장소 수가 표시됩니다.
- "이슈를 생성할 저장소"에서 저장소를 선택합니다. 목록에는 토큰으로 접근할 수 있고 이슈 기능이 활성화된 저장소만 표시됩니다.
GITHUB_ISSUES_ENABLED를 켭니다.
작동 확인
- 연결 확인에 "<you>(으)로 로그인됨"과 "<owner/repo>에 이슈 생성 가능"이 표시됩니다. 확인 과정에서는 조회만 하며 이슈를 생성하지 않습니다.
- 설정 → 연동 → 티켓을 열고 GitHub 대상에서 테스트 티켓 생성을 누릅니다. nexus-test 라벨이 지정된 이슈가 하나 생성됩니다.
- GitHub에서 해당 이슈를 열어 라벨을 확인하고, 확인이 끝나면 닫거나 삭제합니다.
자주 발생하는 오류
| 관찰되는 결과 | 원인 | 해결 방법 |
|---|---|---|
| "GitHub가 토큰을 거부했습니다 (401)" | 토큰이 잘못되었거나, 만료 또는 취소되었거나, 일부만 복사되었습니다. | 이슈 → 읽기 및 쓰기 권한으로 새 토큰을 생성한 다음 다시 저장합니다. |
| HTTP 403 | 토큰에 이슈 권한이 없거나, 해당 토큰에 저장소가 선택되지 않았거나, 요청 한도를 모두 소진했습니다. | 토큰을 수정하여 이슈를 읽기 및 쓰기로 설정하고 저장소를 선택합니다. 요청 한도 문제라면 몇 분 기다립니다. |
| HTTP 404 | 저장소가 존재하지 않거나, 이름이 변경되었거나, 토큰으로 접근할 수 없습니다(비공개 저장소는 세분화된 토큰에서 선택해야 합니다). | 목록에서 저장소를 선택하거나 토큰의 저장소 액세스에 해당 저장소를 추가합니다. |
| HTTP 422 | GitHub가 이슈의 필드 값을 거부했습니다. 주로 공동 작업자가 아닌 담당자 또는 GitHub에서 허용하지 않는 제목이나 라벨이 원인입니다. | 설정 → 연동 → 티켓에서 담당자를 지우거나 해당 사용자를 공동 작업자로 추가합니다. |
| "<repo>의 이슈 기능이 꺼져 있습니다" | 저장소의 이슈 기능이 비활성화되어 있습니다. | 저장소의 설정 → 기능 → 이슈를 켜거나 다른 저장소를 선택합니다. |
| "GitHub에 연결할 수 없습니다 (…)" 또는 "제시간에 응답하지 않았습니다" | VPN이나 프록시 또는 네트워크 연결 부재로 인해 이 PC에서 api.github.com에 연결할 수 없습니다. | 같은 PC의 브라우저에서 github.com을 연 다음 연결 확인을 다시 시도합니다. |
| 확인 결과는 모두 정상이지만 이슈가 생성되지 않음 | GITHUB_ISSUES_ENABLED가 false이거나, 판정이 FLAKY 또는 환경 관련 판정이거나, 샌드박스 실행이거나, 테스트에 이미 열린 이슈가 있습니다(반복 실패 시에는 대신 댓글을 남깁니다). | GITHUB_ISSUES_ENABLED를 켜고 테스트 티켓 생성으로 연결을 확인합니다. |
설정 키
| 키 | 주요 기능 | 유효한 값 | 확인 방법 |
|---|---|---|---|
GITHUB_ISSUES_ENABLED | 실패 시 GitHub 이슈 생성 | true 또는 false | 연결 확인을 통과한 후 켜고, 테스트 티켓 만들기를 실행하세요. |
GITHUB_ISSUES_TOKEN | GitHub 액세스 토큰(비밀 정보, 이 컴퓨터에만 저장됨) | 따옴표와 공백 없이 한 줄로 입력 | 연결 확인: "토큰이 거부됨"은 토큰이 잘못되었거나 만료 또는 철회되었음을 의미합니다. |
GITHUB_ISSUES_REPO | 이슈를 등록할 GitHub 저장소 | 소유자/저장소, 예: acme/web | 목록에서 선택하세요; Studio는 토큰으로 접근할 수 있고 이슈 기능이 켜진 저장소만 저장합니다. |
더 보기: 모든 연동, 설정 안내, 문제 해결. 다른 안내: Jira Cloud, Azure Boards, Slack, Microsoft Teams, Telegram.
아직 해결되지 않았나요? Studio에 표시되는 오류 문구를 그대로 적어 [email protected]으로 보내 주세요. 토큰은 포함하지 마세요.