Jira Cloud 연결: 단계별 안내
실패한 테스트마다 Bug를 하나씩 등록하고, 같은 테스트가 다시 실패하면 댓글을 추가하며, 테스트가 문제없이 통과하면 Done 상태로 변경합니다. 이 안내는 처음부터 연결 확인까지의 과정을 설명하고, 발생할 수 있는 오류와 그 원인 및 해결 방법을 제공합니다.
최종 업데이트:
자격 증명은 비공개로 유지하세요. 토큰, 키, 비밀번호, 웹후크 URL을 채팅에 붙여넣지 마세요. Studio → 설정 → 연동에만 입력하세요. 입력한 정보는 작업 공간의 .env 파일에 저장되며 점으로 표시됩니다. AI 도우미도 마찬가지입니다: 이 안내를 따라 진행하도록 도와줄 수는 있지만, 토큰을 알려줄 필요는 없습니다.
준비 사항
- Jira Cloud 사이트(예: https://your-team.atlassian.net). Jira Cloud만 지원하며, 주소는 https여야 합니다.
- Atlassian 계정의 이메일 주소와 동일한 계정에서 생성한 API 토큰.
- Bug라는 이슈 유형이 있는 프로젝트의 키(예: QA).
- 해당 프로젝트에서 해당 계정에 부여된 찾아보기, 이슈 만들기, 댓글 추가, 첨부 파일 만들기 및 이슈 상태 전환 권한.
자격 증명 발급
- https://id.atlassian.com/manage-profile/security/api-tokens를 열고 API 토큰 만들기를 선택하세요.
- 이름을 지정하고(예: "Nexus StudioQA"), 만료일을 선택한 다음 생성하고 바로 토큰을 복사하세요. Atlassian은 토큰을 한 번만 표시합니다.
- 클립보드에 보관하세요. Studio(다음 단계) 외에는 어디에도 붙여넣지 마세요.
Studio에서 연결
- Studio에서 설정 → 연동 → Jira 연결을 여세요.
- Jira의 아무 링크나(홈페이지, 보드 또는 이슈) 붙여넣고 연결 확인을 누르세요. Studio가 사이트 주소와 프로젝트 키를 저장합니다.
- 입력을 요청하면 Atlassian 이메일과 토큰을 입력하고 저장 & 확인을 누르세요.
- "버그 등록 대상"에서 프로젝트를 선택한 다음
JIRA_ENABLED를 켜세요.
작동 확인
- 연결 확인에 "<your name>(으)로 로그인됨"과 "<KEY>에서 Bug 티켓을 등록할 수 있음"이 표시됩니다. 이 확인은 조회만 하며 티켓을 생성하지 않습니다.
- 설정 → 연동 → 티켓을 열고 테스트 티켓 만들기를 누르세요. nexus-test 라벨이 붙은 티켓 하나를 등록하며, 이 화면에서 Jira를 호출하는 것은 이 버튼뿐입니다.
- Jira에서 해당 티켓을 열고 auto-generated, nexus-studioqa-automation, nexus-test 라벨이 있는지 확인하세요. 확인이 끝나면 삭제하세요.
자주 발생하는 오류
| 관찰되는 결과 | 원인 | 해결 방법 |
|---|---|---|
| "링크가 아닙니다" 또는 "Jira 링크는 https://로 시작해야 합니다" | 붙여넣은 텍스트가 완전한 웹 주소가 아니거나 http://로 시작합니다. | Jira 사이트에 접속한 상태에서 주소 표시줄의 주소를 복사하세요. https://로 시작해야 합니다. |
| HTTP 401 | 이메일이나 토큰이 잘못되었거나, 토큰이 만료 또는 폐기되었거나, 이메일이 토큰을 생성한 계정의 이메일이 아닙니다. | 저장한 이메일의 계정으로 id.atlassian.com에서 새 토큰을 생성한 다음, 설정에서 이메일과 토큰을 모두 다시 저장하세요. |
| HTTP 403 | 로그인은 되지만 Jira에서 해당 계정의 작업을 허용하지 않습니다: 대개 프로젝트의 이슈 만들기, 댓글 추가 또는 첨부 파일 만들기 권한이 없기 때문입니다. | 프로젝트 관리자에게 해당 권한을 요청하거나 다른 프로젝트를 선택하세요. Nexus StudioQA는 이 권한을 부여할 수 없습니다. |
| HTTP 404 | 사이트 주소나 프로젝트 키가 존재하지 않거나, 해당 계정으로 프로젝트를 볼 수 없습니다 (Jira는 숨겨진 프로젝트에 대해 404를 반환합니다). | 올바른 사이트의 링크를 붙여넣고 목록에서 프로젝트를 선택하세요. |
| "해당 주소에서 응답했지만, Jira 계정 정보가 아닙니다" | 해당 주소는 Jira Cloud 사이트가 아닙니다 (예: Server 또는 Data Center 주소나 다른 웹 페이지). | Jira Cloud 사이트의 https://<team>.atlassian.net 주소를 사용하세요. |
| "<KEY>에 Bug라는 이슈 유형이 없습니다" | 프로젝트에 Bug라는 이슈 유형이 없어 티켓을 등록할 수 없습니다. | Jira에서 프로젝트 설정 → 이슈 유형을 열고 Bug를 추가하거나, 다른 프로젝트를 선택하세요. |
| "Jira에 연결할 수 없습니다 (ENOTFOUND)" 또는 "20초 내에 응답하지 않았습니다" | 이 PC에서 사이트에 연결할 수 없습니다: 주소 오타, VPN 또는 프록시, 네트워크 연결 끊김이 원인일 수 있습니다. | 주소를 수정한 뒤 같은 PC의 브라우저에서 사이트를 여세요. 연결 확인을 다시 시도하세요. |
| 모든 확인을 통과했지만 티켓이 나타나지 않음 | JIRA_ENABLED가 false이거나; 판정이 FLAKY 또는 환경 관련 판정이거나; 샌드박스 실행이거나; 해당 테스트에 이미 열린 Bug가 있거나 (반복 실패 시에는 대신 댓글이 추가됩니다); 지난 24시간 내에 같은 제목의 Bug가 등록된 경우입니다. | JIRA_ENABLED를 켜고, 연동 페이지에서 "테스트당 이슈 하나"를 읽은 뒤, 테스트 티켓 만들기로 연결을 확인하세요. |
| 테스트를 통과해도 티켓이 닫히지 않음 | 워크플로에 JIRA_DONE_TRANSITION과 이름이 일치하는 전환이 없어 티켓에 댓글만 추가됩니다. | JIRA_DONE_TRANSITION을 워크플로에 있는 전환 버튼의 정확한 이름으로 설정하세요. |
설정 키
| 키 | 주요 기능 | 유효한 값 | 확인 방법 |
|---|---|---|---|
JIRA_ENABLED | 실패 시 Jira 티켓 만들기 | true 또는 false | 연동을 켠 뒤 테스트 티켓 만들기를 실행하세요. |
JIRA_BASE_URL | Jira 사이트 주소 | https://<site>.atlassian.net | 연결 확인에 사이트가 표시됩니다; 링크를 붙여넣으면 자동으로 입력됩니다. |
JIRA_EMAIL | Jira 로그인 이메일 | 토큰을 소유한 Atlassian 계정의 이메일 | 연결 확인에 이 이메일과 함께 "… 계정으로 로그인됨"이 표시됩니다. |
JIRA_API_TOKEN | Jira 액세스 토큰 (비밀 정보, 이 컴퓨터에만 저장됨) | 따옴표와 공백 없이 한 줄로 입력 | 연결 확인: HTTP 401은 이메일/토큰 조합이 잘못되었음을 뜻합니다. |
JIRA_PROJECT_KEY | Bug 티켓용 Jira 프로젝트 | 프로젝트 키, 보통 대문자 사용, 예: QA | 프로젝트 드롭다운에 표시됩니다; "Bug 티켓 등록 가능"으로 유형을 확인할 수 있습니다. |
JIRA_DONE_TRANSITION | 테스트 통과 시 Jira 상태 | 워크플로 전환의 정확한 이름, 대소문자 구분 없이 일치 여부 확인 | 문제없이 통과하면 티켓 상태가 전환됩니다; 워크플로에 해당 전환이 없으면 댓글만 추가됩니다. |
더 보기: 모든 연동, 설정 안내, 문제 해결. 다른 안내: Azure Boards, Slack, Microsoft Teams, Telegram, GitHub Issues.
아직 해결되지 않았나요? Studio에 표시되는 오류 문구를 그대로 적어 [email protected]으로 보내 주세요. 토큰은 포함하지 마세요.