Jira 도 쓰고, GitLab 도 쓰고, IntelliJ 도 쓰는 팀은 많다. 그런데 세 도구가 서로 모르는 채로 돌아가는 팀이 대부분이다. 이슈는 Jira 에서 손으로 옮기고, 커밋과 이슈의 연결은 기억에 의존하고, 코드 리뷰 하려면 브라우저 탭을 세 개 띄운다. 도구가 세 개라서 일이 3배가 되는 상태다.

이 글의 주장은 단순하다. 세 도구를 엮는 접착제는 이슈 키(예: PROJ-123) 하나이고, 각 도구에는 그 키를 알아듣는 공식 기능이 이미 들어 있다. 새로 살 것도, 설치할 플러그인도 거의 없다. 안 쓰고 있을 뿐이다.

0. 전체 그림 — 한 작업의 이상적인 동선

Jira 이슈 PROJ-123 생성
   ↓ (IntelliJ Tasks & Contexts 로 이슈를 IDE 에서 열기)
브랜치 PROJ-123-fix-timeout 자동 생성 + 커밋 메시지에 키 자동 삽입
   ↓ (커밋 메시지: "PROJ-123 #comment 타임아웃 상한 수정")
GitLab push → MR 생성 → Jira 개발 패널에 브랜치·커밋·MR 자동 표시
   ↓ (MR 머지 → smart commit 으로 이슈 상태 전환)
Confluence 릴리스 노트에 Jira 매크로로 이슈 목록 자동 집계

손으로 옮겨 적는 단계가 없다. 아래에서 구간별로 공식 기능을 확인한다.

1. Jira ↔ GitLab: 커밋 메시지가 이슈를 움직인다

연동의 기본 — 개발 패널

GitLab 에는 Jira 연동이 공식 기능으로 들어 있다. 연동을 켜면 커밋 메시지·브랜치명·MR 제목에 Jira 이슈 키를 넣는 것만으로 Jira 이슈의 개발 패널에 해당 브랜치·커밋·MR 이 자동으로 나타난다. PM 이 “이 이슈 코드 어디까지 갔어요?” 를 개발자에게 묻지 않고 Jira 에서 직접 보게 되는 게 이 연동의 실질 효과다.

Smart Commits — 커밋 메시지로 Jira 를 조작

Atlassian 이 Smart Commits 라고 부르는 문법이다. 커밋 메시지에 명령을 실어 보낸다:

PROJ-123 #comment 커넥션 풀 고갈 원인 수정 #time 2h #transition 코드리뷰
명령 효과
#comment <텍스트> 이슈에 코멘트가 달린다
#time 2h 30m 작업 시간이 기록된다 (worklog)
#<transition 이름> 이슈 상태가 전환된다 (예: In Progress → In Review)

GitLab 쪽에서도 이 문법을 지원한다. 즉 “커밋했으면 Jira 가서 상태 바꾸고 코멘트 남기세요” 라는 팀 규칙은 커밋 메시지 한 줄로 대체 가능한 수작업이다.

주의할 점 하나 — smart commit 은 커밋 작성자의 이메일이 Jira 계정 이메일과 일치해야 동작한다(Atlassian 공식 문서의 전제 조건). git config user.email 이 회사 계정과 다르면 조용히 무시되므로, 팀에 처음 도입할 때 이것부터 맞춘다.

GitLab 이슈를 쓰는 팀이라면 — 종결 패턴

Jira 없이 GitLab 이슈만 쓰는 프로젝트도 같은 원리가 있다. MR 설명에 Closes #45 를 쓰면 머지 시점에 이슈가 자동으로 닫힌다. 원리는 동일하다 — 이슈 번호를 코드 쪽 텍스트에 넣으면 트래커가 알아서 움직인다.

2. IntelliJ: Tasks & Contexts — 가장 저평가된 내장 기능

IntelliJ 에는 Tasks & Contexts 라는 내장 기능이 있다 (Tools → Tasks & Contexts). Jira·GitLab 을 포함한 이슈 트래커를 태스크 서버로 등록하면:

  1. IDE 안에서 이슈 목록을 검색해서 연다 — 브라우저로 안 가도 된다
  2. 태스크를 열면 브랜치를 이슈 키 이름으로 자동 생성하도록 설정할 수 있다
  3. 커밋 메시지에 이슈 키가 자동으로 들어간다 — 1장의 smart commit 이 공짜로 시작된다
  4. 컨텍스트(열린 편집기·북마크·브레이크포인트)가 태스크별로 저장된다 — 긴급 이슈로 갈아탔다가 돌아와도 아까 보던 파일 배치가 그대로 복원된다

4번이 핵심이다. 컨텍스트 스위칭에서 진짜 비싼 건 브랜치 전환이 아니라 “내가 어디까지 봤더라”를 다시 구축하는 시간인데, 이 기능은 그걸 저장/복원한다.

GitLab MR 을 IDE 에서

IntelliJ 는 GitLab 연동을 내장하고 있다 (2023.2 부터). MR 목록 조회, 코멘트, 리뷰를 IDE 안에서 처리할 수 있다. 리뷰 중 “이 함수 정의가 뭐더라” 는 브라우저 diff 뷰에서는 클릭 한 번에 안 되지만 IDE 에서는 Go to Definition 그 자체다. 리뷰를 브라우저에서 IDE 로 옮기는 것이 이 연동의 목적이다.

3. Confluence: “왜” 를 담는 곳, 그리고 Jira 매크로

Jira 이슈는 “무엇을 했는가” 는 남기지만 “왜 그렇게 결정했는가” 는 담기 어렵다. 그 자리가 Confluence 다. 생산적으로 쓰는 요령은 두 가지로 압축된다.

첫째, 이슈와 문서를 서로 링크한다. Confluence 페이지에 Jira 이슈 링크를 붙이면 Jira 이슈 매크로가 이슈의 현재 상태를 실시간으로 보여준다 — 문서에 박제된 “진행중” 이 아니라 지금 상태다. JQL 을 넣으면 이슈 목록·개수 집계도 된다. 스프린트 회고나 릴리스 노트에서 “이번에 나간 이슈 목록” 을 손으로 복사하는 일이 사라진다.

둘째, 결정 기록(Decision Log)을 문서 한 페이지로 남긴다. 아키텍처 선택, 라이브러리 채택 같은 결정을 배경·대안·선택 이유와 함께 적고 관련 Jira 이슈를 링크한다. 6개월 뒤 “왜 이렇게 돼 있지?” 의 답이 커밋 로그가 아니라 문서에서 나오게 하는 것이 목적이다. 이건 도구 기능이라기보다 습관이지만, 위의 매크로·링크가 있어야 유지 비용이 낮아져 지속된다.

4. 이것만은 하지 말자 — 안티패턴 3개

안티패턴 왜 문제인가 대체
커밋 메시지에 이슈 키 생략 개발 패널이 비고, 나중에 이슈↔코드 추적이 고고학이 된다 브랜치명에 키를 넣으면 IntelliJ 가 커밋 메시지에 자동 삽입
Jira 상태를 손으로 옮기기 잊어버리면 보드가 현실과 어긋나고, 보드를 못 믿게 되면 아무도 안 본다 smart commit #transition 또는 MR 머지 연동
결정을 메신저에만 남기기 검색 안 되고, 스레드는 흘러간다 Confluence 결정 기록 + Jira 이슈 링크

셋 다 공통 원인은 같다 — 사람이 두 시스템 사이에서 복사기 역할을 하는 것. 위에서 본 연동 기능들은 전부 그 복사기 역할을 기계에 넘기는 장치다.

5. 도입 순서 제안

한꺼번에 하면 실패한다. 순서는 이렇게 권한다.

  1. 1주차: 커밋 메시지·브랜치명에 이슈 키 넣기만 팀 규칙으로. (도구 설정 없이 시작 가능, GitLab-Jira 연동만 관리자가 켠다)
  2. 2주차: IntelliJ 태스크 서버 등록 — 키 삽입이 자동화되면서 1주차 규칙의 마찰이 사라진다
  3. 3주차: smart commit 으로 상태 전환 자동화
  4. 그 다음: Confluence 릴리스 노트에 Jira 매크로, 결정 기록 페이지 도입

포인트는 1→2 순서다. 규칙을 먼저 만들고 자동화가 마찰을 없애는 순서로 가야, “도구가 강제해서” 가 아니라 “편해서” 정착한다.

References