GitLab Value Stream Analytics(VSA)는 개발 워크플로에 대한 인사이트를 제공하며 다음과 같은 주요 지표를 추적합니다.

• Lead time: 이슈 생성부터 완료까지 걸리는 시간
• Issues created: 특정 기간 동안 생성된 새 이슈 수
• Issues closed: 특정 기간 동안 해결된 이슈 수

이슈 추적에는 Jira를 사용하고 개발에는 GitLab을 사용하는 팀의 경우, 이 통합을 사용하면 Jira 이슈를 실시간으로 GitLab에 자동 복제할 수 있습니다. 이를 통해 팀이 기존 Jira 워크플로를 변경하지 않고도 정확한 VSA 지표를 확보할 수 있습니다.

이 통합은 GitLab Value Streams Dashboard(Ultimate 전용)에도 데이터를 채워 넣으며, 이 대시보드는 GitLab 프로젝트 또는 그룹의 Analyze > Analytics dashboards에서 찾을 수 있고 주요 DevSecOps 지표를 한눈에 보여줍니다.

아키텍처#

Jira automation을 사용해 2개의 자동화 워크플로를 생성합니다.

1. Jira에서 이슈가 생성되면 GitLab 이슈를 생성합니다.
2. Jira에서 이슈가 해결되면 GitLab 이슈를 닫습니다.

이슈 생성#

Jira에서 새 이슈가 생성되면 자동화 워크플로가 GitLab Issues API에 POST 요청을 전송하여 지정된 GitLab 프로젝트에 해당 이슈를 생성합니다.

이슈 해결#

Jira 이슈가 해결 상태(Closed, Done, Resolved)로 전환되면 자동화 워크플로가 PUT 요청을 전송하여 해당 GitLab 이슈를 닫습니다.

설정#

사전 요구 사항#

이 안내는 다음 사항이 준비되어 있다고 가정합니다.

• VSA 분석을 생성할 GitLab 프로젝트
• 이슈를 복제할 원본 Jira 프로젝트
• GitLab Ultimate 또는 Premium 라이선스(Value Stream Analytics 기능용)

Jira는 라이선스에 따라 Automation 실행 빈도에 제한을 둡니다.

이슈 생성 1건과 이슈 해결 1건은 각각 1회 실행으로 계산됩니다.

GitLab 프로젝트 액세스 토큰#

먼저 API를 통해 이슈를 생성하고 업데이트하는 데 필요한 권한을 가진 GitLab 프로젝트 액세스 토큰을 생성해야 합니다.

1. Jira 이슈를 복제할 GitLab 프로젝트로 이동합니다. 사이드바에서 Settings > Access Tokens로 이동합니다.
2. Add new token을 클릭합니다.
3. 다음과 같이 설정합니다.
   • Token name: Jira VSA Integration(또는 다른 설명적인 이름)
   • Expiration date: 보안 정책에 따라 설정합니다.
   • Role: Owner(사용자 지정 이슈 ID를 설정하려면 필요합니다)
   • Scopes: api(전체 API 액세스)를 선택합니다.

중요: 이 통합은 GitLab에서 이슈를 생성할 때 사용자 지정 이슈 ID를 강제로 설정해야 하므로 Owner 수준의 액세스 토큰이 필요합니다. 이를 통해 Jira 이슈가 닫힐 때 자동화가 동일한 ID 매핑을 사용하여 해당 GitLab 이슈를 식별하고 닫을 수 있습니다. Owner 권한이 없으면 GitLab API가 사용자 지정 이슈 ID 설정을 허용하지 않아 Jira 이슈 닫기와 GitLab 이슈 닫기 사이의 동기화가 깨집니다.

1. Create project access token을 클릭하고 생성된 토큰을 안전하게 저장합니다. Jira automation 설정에 이 토큰이 필요합니다.

Jira 이슈 생성 워크플로#

Jira 이슈가 생성될 때 GitLab 이슈를 자동으로 생성하기 위해 Jira automation을 사용합니다.

1. Jira 프로젝트로 이동합니다. 사이드바에서 Project settings > Automation으로 이동합니다.

2. 오른쪽 상단의 Create rule을 클릭합니다.

3. 트리거로 Issue created를 검색해 선택합니다. Save를 클릭합니다.

4. 선택 사항: 복제할 이슈를 필터링하는 조건을 추가합니다. 예를 들어 특정 유형이나 특정 레이블이 있는 이슈만 복제하려면 Issue fields condition을 추가할 수 있습니다.

5. THEN: Add an action을 선택합니다. Send web request를 검색해 선택합니다.

6. 웹 요청을 다음과 같이 구성합니다.

   • Web request URL: https://gitlab.com/api/v4/projects//issues(셀프 호스팅인 경우 gitlab.com을 사용 중인 GitLab 인스턴스 URL로, 를 GitLab 프로젝트의 숫자 ID(예: 42718690)로 바꿉니다)
   • HTTP method: POST
   • Web request body: Custom data

7. 다음 헤더를 추가합니다.

   이름	값
   Authorization	Bearer
   Content-Type	application/json

   보안을 위해 Authorization 헤더를 "Hidden"으로 설정합니다.

8. Custom data 필드에 다음을 입력합니다.

   {
     "title": "{{issue.summary}}",
     "iid": {{issue.key.replace("VSA-", "1000")}}
   }
   

   "VSA-"를 사용 중인 Jira 프로젝트 접두사로 바꿉니다(예: Jira 이슈 번호가 PROJ-123 형식이면 "PROJ-"를 사용합니다). 1000은 GitLab UI에서 직접 생성했을 수 있는 이슈와 충돌하지 않도록 더해지는 기준 숫자이며, 필요에 따라 조정할 수 있습니다.

9. Save를 클릭하고 자동화에 설명적인 이름(예: Jira to GitLab Issue Creation)을 지정한 다음 Turn it on을 클릭합니다.

Jira 이슈 해결 워크플로#

Jira 이슈가 해결될 때 GitLab 이슈를 닫는 두 번째 자동화 워크플로를 생성합니다.

1. 생성 워크플로의 1~2단계를 따라 새 규칙을 시작합니다.

2. 트리거를 Issue transitioned로 설정합니다.

   • "From status" 필드는 비워 둡니다.
   • "To status"를 해결 상태인 Closed, Done, Resolved로 설정합니다(Jira 워크플로에 맞게 조정합니다).

3. 조건은 건너뜁니다(필요하면 사용자 지정 조건을 추가합니다).

4. 다음과 같이 Send web request 액션을 추가합니다.

   • Web request URL: https://gitlab.com/api/v4/projects//issues/{{issue.key.replace("-", "1000").urlEncode}}(셀프 호스팅인 경우 gitlab.com을 사용 중인 GitLab 인스턴스 URL로, 를 GitLab 프로젝트의 숫자 ID로, 를 VSA나 PROJ와 같은 Jira 프로젝트 접두사로 바꿉니다)
   • HTTP method: PUT
   • Web request body: Custom data

5. 생성 워크플로와 동일한 헤더를 사용합니다.

6. Custom data 필드에 다음을 입력합니다.

   {
     "state_event": "close"
   }
   

7. 설명적인 이름(예: Jira to GitLab Issue Closer)으로 자동화 규칙을 저장하고 활성화합니다.

Value Stream Analytics 구성#

자동화 워크플로가 활성화되면 GitLab이 이슈 데이터를 수신하기 시작합니다. 분석에 액세스하는 방법은 다음과 같습니다.

Value Streams Dashboard(자동 - Ultimate 전용)#

Value Streams Dashboard는 복제된 이슈의 지표로 자동으로 채워지며 GitLab Ultimate에서 사용할 수 있습니다.

1. GitLab 프로젝트 또는 그룹에서 Analyze > Analytics dashboards로 이동합니다.
2. Value Streams Dashboard를 클릭합니다.
3. Issues created, Issues closed, Lead time, Cycle time 등의 지표를 확인할 수 있습니다.

Value Stream Analytics(설정 필요 - Premium 및 Ultimate)#

더 상세한 분석과 사용자 지정 밸류 스트림이 필요하면 다음과 같이 진행합니다(GitLab Premium 및 Ultimate에서 사용 가능).

1. GitLab 프로젝트 또는 그룹에서 Analyze > Value stream analytics로 이동합니다.
2. New value stream을 클릭해 사용자 지정 밸류 스트림을 생성합니다.
3. 개발 프로세스에 맞게 스테이지와 워크플로를 구성합니다.
4. lead time, 신규 이슈 수와 같은 지표가 자동으로 생성되어 생성한 스테이지 옆에 표시됩니다.
5. 자세한 설정 방법은 GitLab Value Stream Analytics 문서를 참고합니다.

다중 프로젝트 고려 사항#

단일 자동화 규칙 세트로 여러 Jira 프로젝트의 이슈를 복제하려면, 프로젝트 접두사 방식 대신 타임스탬프 기반 방식으로 고유한 이슈 ID를 생성하는 것을 고려합니다.

custom data의 iid 값을 다음으로 바꿉니다.

"iid": {{issue.created.replace("-","").replace("T","").replace(":","").replace(".","").replace("+","")}}

이는 생성 타임스탬프(형식: 2025-02-15T09:45:32.7+0000)를 숫자 값으로 변환합니다. 이 방식은 이슈 ID가 매우 길어질 수 있으며, 두 이슈가 정확히 같은 시각에 생성되면 충돌이 발생할 가능성이 약간 있다는 점에 유의합니다.

참고 자료#

• GitLab Value Stream Analytics
  • 밸류 스트림 생성
• GitLab Value Streams Dashboard
• GitLab Issues API
  • 새 이슈 생성
  • 이슈 수정
• GitLab 프로젝트 액세스 토큰
• 웹 요청을 사용한 Jira automation