Azure Boards 연결: 단계별 안내
실패한 테스트마다 작업 항목을 하나씩 생성하고, 같은 테스트가 다시 실패하면 해당 항목에 댓글을 추가하며, 테스트가 문제없이 통과하면 완료 상태로 변경합니다. 같은 토큰으로 테스트 결과를 게시하고 파이프라인을 실행 대기열에 추가할 수도 있습니다. 이 안내에서는 처음부터 연결을 확인하기까지의 과정을 설명하고, 발생할 수 있는 오류와 원인 및 해결 방법을 정리합니다.
최종 업데이트:
자격 증명은 비공개로 유지하세요. 토큰, 키, 비밀번호, 웹후크 URL을 채팅에 붙여넣지 마세요. Studio → 설정 → 연동에만 입력하세요. 입력한 정보는 작업 공간의 .env 파일에 저장되며 점으로 표시됩니다. AI 도우미도 마찬가지입니다: 이 안내를 따라 진행하도록 도와줄 수는 있지만, 토큰을 알려줄 필요는 없습니다.
준비 사항
- Azure DevOps Services 조직: https://dev.azure.com/<organization> 또는 https://<organization>.visualstudio.com (자체 장비에서 운영하는 Azure DevOps Server는 지원하지 않습니다).
- 작업 항목을 생성할 프로젝트의 이름.
- 작업 항목 → 읽기 & 쓰기 권한이 있는 개인용 액세스 토큰(PAT). CI에서 실행 기능도 사용한다면 빌드 → 읽기 & 실행 권한도 필요합니다.
- 작업 항목 유형을 결정하는 프로젝트의 프로세스 확인: 기본에는 문제, 에픽, 작업이 있고 버그는 없으며; Agile, Scrum, CMMI에는 버그가 있습니다.
자격 증명 발급
- dev.azure.com을 열고 사용자 설정 → 개인용 액세스 토큰 → 새 토큰으로 이동하세요.
- 조직을 선택하고 만료일을 설정한 다음, 범위에서 사용자 지정 정의를 선택하세요.
- 작업 항목 → 읽기 & 쓰기를 선택하고(CI에서 실행을 사용하려면 빌드 → 읽기 & 실행도 추가), 토큰을 생성한 후 바로 복사하세요. 토큰은 한 번만 표시됩니다.
- 클립보드에 보관하세요. Studio(다음 단계) 외에는 어디에도 붙여넣지 마세요.
Studio에서 연결
- Studio에서 설정 → 연동 → Azure DevOps 연결을 여세요.
- Azure DevOps의 링크(보드, 작업 항목 또는 프로젝트 페이지)를 붙여넣고 연결 확인을 누르세요. Studio가 조직과 프로젝트를 저장합니다.
- 입력을 요청하면 PAT를 입력하고 저장 & 확인을 누르세요. "작업 항목을 생성할 위치"에서 프로젝트를 선택하세요.
- 확인 결과 프로젝트에 버그라는 작업 항목 유형이 없다고 표시되면,
AZURE_BOARDS_WORK_ITEM_TYPE을 표시된 유형 중 하나(기본 프로젝트에서는 문제)로 설정하고,AZURE_BOARDS_DONE_STATE를 해당 프로세스에 있는 상태(기본: 완료)로 설정하세요. AZURE_BOARDS_ENABLED를 켜세요.
작동 확인
- 연결 확인에 "토큰으로 N개의 프로젝트에 접근할 수 있습니다"와 "<project>에서 <type> 작업 항목을 사용할 수 있습니다"가 표시됩니다. 확인 과정에서는 읽기만 수행하며 작업 항목을 생성하지 않습니다.
- 설정 → 연동 → 티켓을 열고 테스트 티켓 만들기를 누르세요. nexus-test 태그와 스크린샷 첨부 파일이 있는 작업 항목 하나가 생성됩니다.
- Azure Boards에서 해당 항목을 열어 태그와 첨부 파일을 확인하고, 확인이 끝나면 삭제하세요.
자주 발생하는 오류
| 관찰되는 결과 | 원인 | 해결 방법 |
|---|---|---|
| "Azure DevOps에서 토큰을 거부했습니다" (HTTP 203 또는 401) | PAT가 잘못되었거나, 만료 또는 해지되었거나, 일부만 복사되었거나, 다른 조직에서 생성되었습니다. | AZURE_DEVOPS_ORG_URL과 동일한 조직에서 작업 항목 → 읽기 & 쓰기 권한으로 새 PAT를 생성하고 다시 저장하세요. |
| HTTP 403 | PAT는 유효하지만 필요한 범위가 없거나, 사용자에게 해당 프로젝트의 권한이 없습니다. | PAT의 범위를 수정하거나(작업 항목 → 읽기 & 쓰기; CI에서 실행을 사용하려면 빌드 → 읽기 & 실행), 프로젝트 관리자에게 접근 권한을 요청하세요. |
| HTTP 404 | 조직 또는 프로젝트 이름이 존재하지 않거나, 프로젝트 이름이 변경되었습니다. | 올바른 프로젝트의 링크를 붙여넣고 목록에서 해당 프로젝트를 선택하세요. |
| VS402323 "작업 항목 유형 버그가 존재하지 않습니다" | 프로젝트의 프로세스에 해당 이름의 작업 항목 유형이 없습니다. 기본 프로젝트에는 문제, 에픽, 작업이 있으며 버그는 없습니다. | AZURE_BOARDS_WORK_ITEM_TYPE을 확인 결과에 표시된 유형(기본: 문제)으로 설정하고 AZURE_BOARDS_DONE_STATE를 해당 유형의 상태 중 하나(기본: 완료)로 설정한 다음, 연결 확인을 다시 실행하세요. |
| "<project>에 …라는 작업 항목 유형이 없습니다" | VS402323과 원인은 같지만, 항목을 등록하기 전에 연결 확인에서 감지됩니다. | AZURE_BOARDS_WORK_ITEM_TYPE을 해당 메시지에 나열된 유형 중 하나로 설정하거나, 다른 프로젝트를 선택하세요. |
| "Azure DevOps 링크가 아닙니다" | 주소가 dev.azure.com/<organization> 또는 <organization>.visualstudio.com 형식이 아니거나, http://로 시작합니다. | Azure DevOps Services의 주소 표시줄에서 주소를 복사하세요. Azure DevOps Server는 지원되지 않습니다. |
| "Azure DevOps에 연결할 수 없습니다 (…) " 또는 "20초 이내에 응답하지 않았습니다" | VPN이나 프록시 또는 네트워크 연결 부재로 인해 이 PC에서 Azure DevOps에 연결할 수 없습니다. | 같은 PC의 브라우저에서 dev.azure.com을 연 다음, 연결 확인을 다시 시도하세요. |
| 테스트를 통과해도 완료 상태로 설정되지 않음 | 프로세스에서 해당 유형의 AZURE_BOARDS_DONE_STATE 값을 허용하지 않아 항목에 댓글만 추가됩니다. | AZURE_BOARDS_DONE_STATE을 해당 유형의 상태로 설정하세요 (Basic: Done; Agile 버그: Resolved). |
| 모든 확인을 통과했지만 작업 항목이 표시되지 않음 | AZURE_BOARDS_ENABLED가 false이거나; 판정이 FLAKY 또는 환경 관련 판정이거나; 샌드박스 실행이었거나; 테스트에 이미 열린 작업 항목이 있습니다 (반복 실패 시에는 대신 댓글이 추가됩니다). | AZURE_BOARDS_ENABLED를 켜고 테스트 티켓 만들기로 연결을 검증하세요. |
설정 키
| 키 | 주요 기능 | 유효한 값 | 확인 방법 |
|---|---|---|---|
AZURE_BOARDS_ENABLED | 실패 시 Azure 작업 항목 만들기 | true 또는 false | 연결 확인을 통과한 후 켜고, 테스트 티켓 만들기를 실행하세요. |
AZURE_DEVOPS_ORG_URL | Azure DevOps 조직 주소 | https://dev.azure.com/<organization> 또는 https://<organization>.visualstudio.com | 연결 확인에 조직이 표시됩니다; 링크를 붙여 넣으면 자동으로 입력됩니다. |
AZURE_DEVOPS_PROJECT | Azure DevOps 프로젝트 이름 | Azure DevOps에 표시된 그대로의 프로젝트 이름 | 연결 확인에 토큰으로 조회할 수 있는 프로젝트 목록이 표시됩니다. |
AZURE_DEVOPS_PAT | Azure DevOps 액세스 토큰 (비밀 정보, 이 컴퓨터에만 저장됨) | 따옴표와 공백 없이 한 줄로 입력 | 연결 확인: "토큰이 거부되었습니다"는 토큰이 잘못되었거나, 만료되었거나, 다른 조직의 토큰임을 뜻합니다. |
AZURE_BOARDS_WORK_ITEM_TYPE | 실패 시 사용할 Azure 티켓 유형 | 프로젝트 프로세스에 있는 유형: Bug (Agile, Scrum, CMMI) 또는 Issue (Basic) | 연결 확인에 "<project>에서 <type> 작업 항목을 사용할 수 있습니다"라고 표시되거나 프로젝트에 있는 유형 목록이 표시됩니다. |
AZURE_BOARDS_DONE_STATE | 테스트 통과 시 Azure 상태 | 해당 작업 항목 유형의 상태: Resolved (Agile 버그), Done (Basic 이슈) | 문제없이 통과하면 항목의 상태가 변경됩니다; 프로세스에서 해당 상태를 허용하지 않으면 댓글만 추가됩니다. |
AZURE_PIPELINE_ID | CI에서 실행할 Azure 파이프라인 | Azure 파이프라인의 숫자 ID (CI에서 실행에만 사용) | nexus ci-remote --provider=azure 명령으로 해당 파이프라인을 실행 대기열에 추가합니다; 빌드 → 읽기 & 실행 권한이 필요합니다. |
더 보기: 모든 연동, 설정 가이드, 문제 해결. 기타 가이드: Jira Cloud, Slack, Microsoft Teams, Telegram, GitHub Issues.
아직 해결되지 않았나요? Studio에 표시되는 오류 문구를 그대로 적어 [email protected]으로 보내 주세요. 토큰은 포함하지 마세요.