Jira REST API 토큰 발급 및 이슈 조회

📌 문제 상황

우리 스터디에서는 주차별로 스프린트를 관리하며, 각 주차에 맞는 이슈를 등록하여 일정을 관리하고 있다. 예를 들어, 1주차에 해당하는 이슈들은 '1주차' 에픽에, 2주차에 해당하는 이슈들은 '2주차' 에픽에 할당된다. Confluence 문서에 Jira의 특정 이슈를 삽입할 경우 특정 에픽을 필터링할 수 없어, 모든 주차의 이슈가 한꺼번에 불러와지는 문제가 있었다. 이는 JQL에서 and parent = "에픽 키" 조건을 추가하여 해결할 수 있었다.

(자세한 내용은 [도구 #1] Jira 및 Confluence 사용 방법 글의 "📌 Confluence 콘텐츠 생성 (jira 이슈 연동)" 참고)

 

위를 통해 프로젝트, 이슈 유형, 상태, 담당자 뿐만 아니라 JQL을 수정하여 에픽까지 필터링하는 것은 가능했다. 그러나 또 다른 문제가 발생했다. 특정 에픽의 이슈들은 정상적으로 불러와졌지만, 그 이슈들의 하위 이슈들은 포함되지 않았다. 이는 JQL에서 특정 에픽을 parent로 설정했기 때문이다. 즉, 하위 이슈들은 해당 에픽이 아닌, 그 상위 이슈를 parent로 가지므로 자동으로 포함되지 않는 것이다. 하위 이슈까지 포함하려면 JQL에서 parent in () 조건을 사용해야 한다. 하지만, 이 방법은 하위 이슈를 가진 모든 이슈의 키를 직접 입력해야 하는 번거로움이 있다.

 

[ 예시 ]

예를 들어, 홍길동 담당자에게 다음과 같은 이슈가 할당되어 있다고 하자.

• A 이슈 (parent: "3주차" 에픽)
• B 이슈 (parent: "3주차" 에픽 / 하위 이슈: a, b, c)
• C 이슈 (parent "3주차" 에픽 / 하위 이슈: d)

이슈를 불러올 때, A, B, C 이슈뿐만 아니라 B와 C의 하위 이슈들까지 모두 포함하려면, JQL의 parent를 다음과 같이 작성해야 한다.

... and parent in ("3주차 에픽 키", "B 이슈 키", "C 이슈 키") ...

 

📌 해결 방법

스터디 주차가 끝나는 날, Confluence로 문서를 취합하면서 문득 떠오른 생각이 '최근에 배운 Selenium을 활용하면 이 작업을 자동화할 수 있지 않을까?' 였다. 처음에는 Selenium을 사용해 담당자별로 하위 이슈를 가진 이슈들의 키를 자동으로 찾아주는 스크립트를 만들려고 했다. 그러나 실제로 구현을 시도하면서 몇 가지 문제점이 발생했다.

 

Selenium을 통한 자동화의 문제점

1. Jira는 SPA(Single Page Application) 구조를 사용하므로, 사용자가 특정 작업을 수행해야만 일부 요소들이 로드된다.
2. 대부분의 이슈 상태 변경, 검색, 필터링 등은 AJAX 요청을 통해 비동기적으로 처리되므로, Selenium이 요소를 감지하기 전에 상태가 변경될 가능성이 크다.
3. 일부 UI 요소가 iframe 내부에 위치하여, Selenium에서 바로 접근하려면 switch_to.frame()을 사용해야 하며, 이로 인해 추가적인 복잡성이 발생한다.
4. HTML 구조가 복잡하고, 클래스 네이밍을 난독화하여 랜덤한 고유 식별자를 사용한다.
5. jira의 로딩 속도가 일정하지 않아 WebDriverWait와 time.sleep()을 사용해도 예외가 자주 발생한다.

 

'그렇다면 Selenium 말고 다른 방법이 없을까?'에 대한 고민 끝에 찾은 해결 방법이 바로 Jira REST API 였다. Jira REST API를 활용하면, UI 요소에 의존하지 않고 직접 데이터를 요청해 가져올 수 있어, Selenium보다 훨씬 안정적이고 효율적인 자동화가 가능하다.

 

+ 가장 간단한 해결 방법

사실 Confluence에서는 하위 작업을 불러오는 기능을 제공했지만, 본인은 이를 알지 못했다. 단순히 열 구성에서 하위 작업을 추가하면 해결되는 문제였지만, JQL 생성 자동화 스크립트를 만든 후 해당 JQL을 Confluence 문서에 적용해보면서 이를 알게 되었다. 어찌 보면 혼자 삽질한 셈이지만, 긍정적으로 보면 덕분에 Selenium을 연습하고 Jira REST API도 활용해볼 수 있었다. (자세한 내용은 [도구 #1] Jira 및 Confluence 사용 방법 글의 "📌 Confluence 콘텐츠 생성 (jira 이슈 연동)" 참고)

 

📌 Jira REST API란?

Jira REST API는 HTTP 요청을 통해 Jira의 데이터(이슈, 프로젝트, 사용자 정보 등)에 접근하고 조작할 수 있도록 제공되는 인터페이스이다. 즉, 브라우저에서 UI를 통해 직접 이슈를 확인하는 대신, API를 통해 프로그램적으로 데이터를 생성, 조회, 수정, 삭제할 수 있다. Jira REST API는 기본적으로 JSON 형식의 데이터를 주고받으며, GET, POST, PUT, DELETE 같은 HTTP 메서드를 통해 다양한 작업을 수행할 수 있다.

 

📌 Jira API Token 발급 방법

Jira API Token을 발급하려면, 오른쪽 상단의 [ 프로필 및 설정 ] > [ 계정 관리 ] 버튼을 클릭한다.

다음으로, [ API 토큰 만들기 및 관리 ] 버튼을 클릭한다.

다음으로, [ API 토큰 만들기 ] 버튼을 클릭한다.

새로 생성할 API 토큰의 이름과, 만료일을 설정한 뒤 [ 만들기 ] 버튼을 클릭하여 새로운 API 토큰을 생성한다.

API 토큰을 생성하면 위와 같은 창이 뜨는데, 이 창은 한 번만 표시되므로 닫으면 다시 확인할 수 없다. 즉, 복사하지 않으면 이후에 해당 토큰을 다시 볼 수 없기 때문에, 반드시 안전한 곳에 저장해두어야 한다.

 

📌 Jira REST API를 통한 이슈 조회

현재 스터디 프로젝트는 Jira Cloud를 사용 중이므로, Jira Cloud Platform REST API 공식 문서를 확인하였다.

만약 Jira Server(Data Center)를 사용 중이라면, Jira Server/Data Center REST API 문서에서 확인할 수 있다.

 

프로젝트의 REST API 버전을 확인하려면, 브라우저 주소창에 "https://your-instance.atlassian.net/rest/api/3/serverInfo" URL을 입력한다. 이때, "your-instance.atlassian.net" 부분을 본인의 Jira 도메인으로 변경해야 한다. 만약 응답이 정상적으로 JSON 형태로 반환된다면, 해당 프로젝트는 REST API v3를 지원하는 것이다. 반대로, 404 Not Found 오류가 발생하면, REST API v3를 지원하지 않는 것이다. Jira REST API는 버전에 따라 사용 방법이 다를 수 있기 때문에, 본인의 프로젝트가 지원하는 REST API 버전을 먼저 확인한 후, 공식 문서에서 적절한 버전을 선택하여 본인의 환경에 맞는 내용을 참고하는 것이 중요하다.

 

[ 구현 코드 ]

import os
import requests

JIRA_URL = "jira 프로젝트 도메인"
JIRA_API_TOKEN = "발급받은 Jira API 토큰"
JIRA_EMAIL = "본인의 이메일"

AUTH = (JIRA_EMAIL, JIRA_API_TOKEN)
HEADERS = {"Content-Type": "application/json"}

def getAccountID(userName): # 사용자 Account ID 조회 함수
    response = requests.get(f"{JIRA_URL}/rest/api/3/user/search", auth=AUTH, headers=HEADERS, params={"query": userName})
    return response.json()[0]["accountId"] if response.status_code == 200 and response.json() else None

def hasSubtasks(issueKey): # 특정 이슈에 하위 이슈가 있는지 확인하는 함수
    jql = f'parent="{issueKey}"'
    response = requests.get(f"{JIRA_URL}/rest/api/3/search", auth=AUTH, headers=HEADERS, params={"jql": jql, "fields": "key"})
    return bool(response.json().get("issues", [])) if response.status_code == 200 else False

def getIssues(project, epicKey, userName): # 특정 Epic에 속한 사용자의 이슈 & 하위 이슈 조회
    assigneeID = getAccountID(userName)
    if not assigneeID:
        return print(f"❌ '{userName}' 사용자를 찾을 수 없습니다.")

    jql = f'project="{project}" AND assignee="{assigneeID}" AND parent="{epicKey}" ORDER BY created DESC'
    response = requests.get(f"{JIRA_URL}/rest/api/3/search", auth=AUTH, headers=HEADERS, params={"jql": jql, "fields": "key"})

    if response.status_code != 200:
        return print("❌ API 요청 실패!")

    issues = [issue["key"] for issue in response.json().get("issues", [])]
    print(f"✅ {userName}의 이슈 키:", issues)

    subtasks = [key for key in issues if hasSubtasks(key)]
    print(f"📌 하위 이슈가 있는 이슈 키:", subtasks if subtasks else "없음")

# 실행
os.system('cls')
getIssues("STUDY", "STUDY-100", "강연수")

 

위와 같이, Jira REST API를 통해 데이터를 정상적으로 불러왔음을 확인할 수 있다.

 

+ 추가 지식

Jira Cloud vs Jira Server(Data Center)

구분	Jira Cloud	Jira Server(Data Center)
배포 방식	Atlassian이 클라우드에서 운영 (SaaS)	자체 서버에 설치 및 운영 (On-Premise)
유지보수	Atlassian이 자동 관리 (업데이트, 보안 등)	사용자가 직접 유지보수 및 업그레이드 수행
확장성	자동 확장 지원	사용자가 직접 인프라 확장 필요
업데이트	자동 업데이트	직접 업그레이드 필요
백업 및 복구	Atlassian이 관리 (기본 7일 유지)	사용자가 직접 백업 및 복구 설정
커스터마이징	제한적 (Cloud용 앱만 사용 가능)	고도의 커스터마이징 (플러그인, 스크립트 활용)
보안 및 규정 준수	Atlassian이 SOC2, ISO27001 등 보안 인증	기업 내부 보안 정책에 따라 설정 가능
사용자 관리	Atlassian Access(SAML, SSO) 지원	LDAP, Active Directory 연동 가능
가격 모델	월/연 구독형 (사용자 수 기반)	연간 라이센스 구매 (Data Center는 최소 500명)
무료 플랜	최대 10명 무료	없음 (유료 라이선스 필요)
대상	스타트업, 중소기업, 유지보수 부담이 적은 조직	대기업, 보안이 중요한 조직, 커스터마이징이 필요한 팀

Jira REST API의 인증 방식

1. Basic Authentication (기본 인증)

 ~> 사용 방법 (Jira Cloud Platform REST API 공식 문서)

  1. 사용자 ID + API Token을 Base64 인코딩 후 Authorization 헤더에 추가

 ~> 특징

  • 간단하고 빠르게 구현 가능

  • 보안상 취약할 수 있어 HTTPS 사용 필수

  • Jira Cloud는 비밀번호 대신 API Token 사용 필수

2. OAuth 2.0 인증

 ~> 사용 방법

  1. OAuth 앱 생성 후 Client ID & Client Secret 획득

  2. 사용자 인증 후 Access Token 발급

  3. API 요청 시 Authorization 헤더에 Bearer 토큰 추가

 ~> 특징

  • 보안이 강력하고, 세밀한 권한 관리 가능

  • 외부 애플리케이션과의 연동에 유리

  • 설정 과정이 복잡할 수 있음

3. Session-based Authentication (쿠키 인증)

 ~> 사용 방법

  1.  로그인 API를 호출해 JSESSIONID 획득

  2. API 요청 시 Cookie 헤더에 추가

 ~> 특징

  • Jira Server (On-Premise)에서만 사용 가능

  • 기존 로그인 방식과 유사하여 친숙함

  • Jira Cloud에서는 지원하지 않음

 

📌 Jira REST API의 추가 활용 방안

사실 본인은 Jira REST API를 통해 간단하게 이슈를 불러오는 기능만을 다뤘지만, 이를 활용할 수 있는 가능성은 무궁무진하다고 느꼈다. 예를 들어, Selenium이나 기타 테스트 자동화 도구를 활용해 테스트가 실패했을 때 자동으로 Jira에 버그 티켓을 생성하거나, 테스트가 성공하면 해당 이슈의 상태를 ‘진행 중’에서 ‘완료’로 자동 변경하는 등의 기능을 구현할 수 있을 것이다. 또한, 테스트 결과를 이슈의 댓글로 등록하거나, 특정 이슈 발생 시 Slack이나 Discord로 알림을 전송하는 것도 가능할 것이다. 앞으로는 이러한 확장 기능을 직접 구현하며, Jira REST API를 보다 효과적으로 활용하는 방법을 포스팅할 계획이다.