Jira 이슈 통합은 하나 이상의 GitLab 프로젝트를 Jira 인스턴스에 연결합니다. Jira 인스턴스는 직접 호스팅하거나 Jira Cloud를 사용할 수 있습니다. 지원되는 Jira 버전은 6.x, 7.x, 8.x, 9.x, 10.x입니다.

통합 구성#

사전 요구 사항:

• GitLab 설치 환경이 상대 URL을 사용하지 않아야 합니다.
• Jira Cloud의 경우:
  • 클래식(범위 미지정) API 토큰으로 Basic authentication을 사용하려면 Jira Cloud API 토큰과 토큰을 생성할 때 사용한 이메일 주소가 있어야 합니다.
  • 범위가 지정된 API 토큰으로 Basic authentication을 사용하려면 사용자 계정용 범위 지정 토큰을 생성하고 Jira API URL을 Jira Platform API 게이트웨이 (https://api.atlassian.com/ex/jira/{cloudId})로 설정해야 합니다. 자세한 내용은 Atlassian 계정의 API 토큰 관리를 참고합니다.
  • Jira Cloud service account를 사용하려면 Jira Cloud 서비스 계정과 해당 서비스 계정용 범위 지정 API 토큰이 있어야 합니다. 자세한 내용은 서비스 계정의 API 토큰 관리를 참고합니다.
  • IP 허용 목록을 켠 경우, GitLab에서 Jira 이슈를 조회하려면 허용 목록에 GitLab.com IP 범위를 추가합니다.
• Jira Data Center 또는 Jira Server의 경우, 다음 중 하나가 있어야 합니다:
  • Jira 사용자 이름과 비밀번호.
  • Jira 개인 액세스 토큰.

GitLab 프로젝트 설정을 구성하여 Jira 이슈 통합을 켤 수 있습니다. GitLab Self-Managed에서는 특정 그룹 또는 전체 인스턴스에 대해 통합을 구성할 수도 있습니다.

이 통합을 사용하면 GitLab 프로젝트가 인스턴스의 모든 Jira 프로젝트와 상호 작용할 수 있습니다. GitLab에서 프로젝트 설정을 구성하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. 왼쪽 사이드바에서 Settings > Integrations를 선택합니다.

3. Jira issues를 선택합니다.

4. Enable integration 아래에서 Active 체크박스를 선택합니다.

5. Authentication method 아래에서 다음 중 하나를 선택합니다:

   • Basic authentication: Jira Cloud의 경우 이메일과 API 토큰을 사용하고, Jira Data Center 또는 Jira Server의 경우 사용자 이름과 비밀번호를 사용합니다.

     • Email or username:
       • Jira Cloud의 경우 이메일을 입력합니다.
       • Jira Data Center 또는 Jira Server의 경우 사용자 이름을 입력합니다.
     • API token or password:
       • Jira Cloud의 경우 API 토큰을 입력합니다.
       • Jira Data Center 또는 Jira Server의 경우 비밀번호를 입력합니다.

   • Personal access token(Jira Data Center 및 Jira Server 전용): Jira 개인 액세스 토큰을 입력합니다.

   • Jira Cloud service account(Jira Cloud 전용):

     • Service account token: Jira Cloud service account 용 범위 지정 API 토큰을 입력합니다.
     • GitLab 이 액세스할 Jira 프로젝트에 대해 서비스 계정이 충분한 권한을 갖고 있는지 확인합니다.

6. 연결 세부 정보를 입력합니다:

   • Web URL: 이 GitLab 프로젝트와 연결할 Jira 인스턴스 웹 인터페이스의 기본 URL 입니다 (예: https://jira.example.com 또는 https://example.atlassian.net).
   • Jira API URL: Jira 인스턴스 API의 기본 URL 입니다. 설정하지 않으면 Web URL 값이 사용됩니다.
     • 클래식(범위 미지정) API 토큰을 사용하는 Jira Cloud의 경우, 이 필드를 비워 둡니다.
     • 범위 지정 API 토큰(사용자 계정 또는 서비스 계정)을 사용하는 Jira Cloud의 경우, Jira Platform API 게이트웨이인 https://api.atlassian.com/ex/jira/{cloudId}를 입력합니다. Cloud ID를 확인하려면 Atlassian 안내를 참고합니다.

7. 트리거 설정을 입력합니다:

   • 트리거로 Commit, Merge request, 또는 둘 다를 선택합니다. GitLab에서 Jira 이슈 ID를 언급하면 GitLab 이 해당 이슈로 링크를 연결합니다.
   • GitLab로 다시 연결되는 링크를 Jira 이슈에 댓글로 추가하려면 Enable comments 체크박스를 선택합니다.
   • GitLab에서 Jira 이슈를 자동으로 전환하려면 Enable Jira transitions 체크박스를 선택합니다.

8. Jira issue matching 섹션에서:

   • Jira issue regex에는 정규식 패턴을 입력합니다.
   • Jira issue prefix에는 접두사를 입력합니다.

9. 선택 사항. GitLab에서 Jira 이슈를 조회하려면, Jira issues 섹션에서:

   1. View Jira issues 체크박스를 선택합니다.

      [!warning] GitLab 프로젝트에 액세스할 수 있는 모든 사용자는 인증에 사용된 API 토큰이 액세스할 수 있는 모든 Jira 이슈를 조회할 수 있습니다. 아래에 입력하는 Jira 프로젝트 키는 GitLab에 표시되는 이슈 목록만 필터링합니다. API 토큰의 액세스 권한을 제한하지는 않습니다. 통합이 읽을 수 있는 이슈를 제한하려면 노출하려는 Jira 프로젝트에만 액세스할 수 있는 Jira 계정을 사용하고, 해당 계정에서 API 토큰을 생성합니다.

   2. 표시할 Jira 프로젝트 키를 하나 이상 입력합니다. 비워 두면 API 토큰이 액세스할 수 있는 모든 키가 표시됩니다.

10. 선택 사항. 취약점용 Jira 이슈를 생성하려면, Jira issues for vulnerabilities 섹션에서:

    1. Create Jira issues for vulnerabilities 체크박스를 선택합니다.

       [!note] 이 설정은 개별 프로젝트와 그룹에 대해서만 켤 수 있습니다.

    2. Jira 프로젝트 키를 입력합니다.

    3. Fetch issue types for this project key([retry])를 선택한 다음, 생성할 Jira 이슈 유형을 선택합니다.

    4. 선택 사항. 취약점용으로 생성되는 Jira 이슈의 세부 정보를 검토, 수정, 추가하려면 Customize Jira issues 체크박스를 선택합니다.

11. 선택 사항. Test settings를 선택합니다.

12. Save changes를 선택합니다.

Jira 이슈 조회#

사전 요구 사항:

• Jira 이슈 통합이 구성되어 있고 View Jira issues 체크박스가 선택되어 있는지 확인합니다.

특정 그룹이나 프로젝트에서 Jira 이슈를 켤 수 있지만, 이슈는 GitLab 프로젝트에서만 조회할 수 있습니다. GitLab 프로젝트에서 하나 이상의 Jira 프로젝트의 이슈를 조회하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Plan > Jira issues를 선택합니다.

기본적으로 이슈는 Created date 기준으로 정렬됩니다. 가장 최근에 생성된 이슈가 상단에 표시됩니다. 이슈를 필터링하고 이슈를 선택하여 GitLab에서 해당 이슈를 조회할 수 있습니다.

이슈는 Jira 상태를 기준으로 다음 탭으로 그룹화됩니다:

• Open: Done 이 아닌 Jira 상태를 가진 이슈입니다.
• Closed: Done Jira 상태를 가진 이슈입니다.
• All: 모든 Jira 상태의 이슈입니다.

Jira 이슈 필터링#

사전 요구 사항:

• Jira 이슈 통합이 구성되어 있고 View Jira issues 체크박스가 선택되어 있는지 확인합니다.

GitLab에서 Jira 이슈를 조회할 때, 요약과 설명의 텍스트로 이슈를 필터링할 수 있습니다. 다음 기준으로도 이슈를 필터링할 수 있습니다:

• Label: URL의 labels[] 파라미터에 하나 이상의 Jira 이슈 레이블을 지정합니다. 여러 레이블을 지정하면 지정한 레이블을 모두 가진 이슈만 표시됩니다 (예: /-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA).
• Status: URL의 status 파라미터에 Jira 이슈 상태를 지정합니다 (예: /-/integrations/jira/issues?status=In Progress).
• Reporter: URL의 author_username 파라미터에 Jira 표시 이름을 지정합니다 (예: /-/integrations/jira/issues?author_username=John Smith).
• Assignee: URL의 assignee_username 파라미터에 Jira 표시 이름을 지정합니다 (예: /-/integrations/jira/issues?assignee_username=John Smith).
• Project: URL의 project 파라미터에 Jira 프로젝트 키를 지정합니다 (예: /-/integrations/jira/issues?project=GTL).

Jira 검증#

사전 요구 사항:

• Jira 이슈 통합이 구성되어 있고 View Jira issues 체크박스가 선택되어 있는지 확인합니다.

커밋 메시지에서 참조하는 Jira 이슈가 푸시를 허용하기 전에 특정 기준을 충족하는지 확인하는 검증 규칙을 설정할 수 있습니다. 이 기능은 GitLab과 Jira 간에 일관된 워크플로를 유지하는 데 도움이 됩니다.

GitLab 이 검증 검사를 수행할 때:

• 커밋 메시지에 여러 Jira 이슈 키가 포함된 경우, 검증 검사에는 첫 번째 키만 사용됩니다.
• 알려진 문제로 인해 Check issue exists 설정을 해제해도 검사 실행이 중지되지 않습니다. 검사 실행을 중지하는 유일한 방법은 모든 Jira 검증 검사를 해제하는 것입니다.

Jira 검증을 구성하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Integrations를 선택합니다.
3. Jira issues를 선택합니다.
4. Jira verification 섹션으로 이동합니다.
5. 다음 검증 검사를 구성합니다:
   • Check issue exists: 커밋 메시지에서 참조하는 Jira 이슈가 Jira에 존재하는지 확인합니다.
   • Check assignee: 커밋 작성자가 커밋 메시지에서 참조하는 Jira 이슈의 담당자인지 확인합니다.
   • Check issue status: 커밋 메시지에서 참조하는 Jira 이슈가 허용된 상태 중 하나인지 확인합니다.
   • Allowed statuses: 허용되는 Jira 이슈 상태를 쉼표로 구분한 목록입니다 (예: Ready, In Progress, Review). 이 텍스트 상자는 Check issue status가 선택된 경우에만 사용할 수 있습니다.
6. Save changes를 선택합니다.

사용자가 검증 기준을 충족하지 않는 변경 사항을 푸시하려고 하면, GitLab은 푸시가 거부된 이유를 나타내는 오류 메시지를 표시합니다.

오류 메시지 예시#

• 참조된 Jira 이슈가 존재하지 않는 경우(Check issue exists가 선택된 경우):

  Jira issue PROJECT-123 does not exist.
  

• 참조된 Jira 이슈가 커밋 작성자에게 할당되지 않은 경우(Check assignee가 선택된 경우):

  Jira issue PROJECT-123 is not assigned to you. It is assigned to Jane Doe.
  

• 참조된 Jira 이슈의 상태가 허용 목록에 없는 경우(Check issue status가 선택된 경우):

  Jira issue PROJECT-123 has status 'Done', which is not in the list of allowed statuses: Ready, In Progress, Review.
  

검증 검사 사용 사례#

다음 예시를 살펴봅니다:

1. 팀에서 작업이 진행 중일 때 Jira 이슈가 특정 상태에 있어야 하는 워크플로를 사용합니다.
2. Jira 검증을 다음과 같이 구성합니다:
   • 이슈가 존재하는지 확인
   • 이슈가 "In Progress" 또는 "Review" 상태인지 확인
3. 개발자가 "Fix PROJECT-123 by adding validation" 이라는 커밋 메시지로 변경 사항을 푸시하려고 시도합니다.
4. GitLab은 다음을 확인합니다:
   • Jira 이슈 PROJECT-123 이 존재하는지
   • 이슈가 "In Progress" 또는 "Review" 상태 중 하나인지
5. 모든 검사를 통과하면 푸시가 허용됩니다. 검사 중 하나라도 실패하면 오류 메시지와 함께 푸시가 거부됩니다.

이를 통해 해당 Jira 이슈가 올바른 상태가 아닐 때 코드 변경 사항이 푸시되는 것을 방지하여 팀이 올바른 워크플로를 따르도록 보장합니다.

취약점용 Jira 이슈 생성#

사전 요구 사항:

• Jira 이슈 통합이 구성되어 있고 Create Jira issues for vulnerabilities 체크박스가 선택되어 있는지 확인합니다.
• 대상 프로젝트에서 이슈를 생성할 권한이 있는 Jira 사용자 계정이 있어야 합니다.

취약점을 해결하거나 완화하기 위해 취한 조치를 추적하기 위해 GitLab에서 Jira 이슈를 생성할 수 있습니다. 취약점용 Jira 이슈를 생성하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. 왼쪽 사이드바에서 Secure > Vulnerability report를 선택합니다.

3. 취약점의 설명을 선택합니다.

4. Create Jira issue를 선택합니다.

   Customize Jira issues 설정이 선택되어 있으면, 취약점 데이터가 미리 입력된 Jira 인스턴스의 이슈 생성 양식으로 리디렉션됩니다. Jira 이슈를 생성하기 전에 세부 정보를 검토, 수정, 추가할 수 있습니다.

이슈는 취약점 보고서의 정보와 함께 대상 Jira 프로젝트에 생성됩니다.

GitLab 이슈를 생성하려면 취약점용 GitLab 이슈 생성을 참고합니다.

Jira Cloud API 토큰 생성#

Jira Cloud 용 Jira 이슈 통합을 구성하려면 API 토큰이 있어야 합니다.

사용자 계정의 경우#

1. Jira 프로젝트에 쓰기 액세스 권한이 있는 계정으로 Atlassian에 로그인합니다.

   이 링크는 API tokens 페이지를 엽니다. 또는 Atlassian 프로필에서 Account Settings > Security > Create and manage API tokens를 선택합니다.

2. Create API token을 선택합니다.

3. 대화 상자에서 토큰의 레이블을 입력하고 Create를 선택합니다.

4. API 토큰을 복사하려면 Copy를 선택합니다.

서비스 계정의 경우#

1. Jira Cloud 서비스 계정을 생성하거나 확인합니다. 자세한 내용은 Atlassian 서비스 계정 문서를 참고합니다.

2. 서비스 계정용 범위 지정 API 토큰을 생성합니다. 자세한 내용은 서비스 계정의 API 토큰 관리를 참고합니다.

3. 토큰에 최소한 다음 클래식 Jira 범위가 있는지 확인합니다:

   • read:jira-user
   • read:jira-work
   • write:jira-work

다른 Jira 사이트로 마이그레이션#

GitLab에서 Jira 이슈 통합을 유지하면서 다른 Jira 사이트로 마이그레이션하려면:

1. 통합 구성의 단계를 따릅니다.
2. 새 Jira 사이트 URL을 입력합니다(예: https://myjirasite.atlassian.net).

GitLab 18.6 이상에서는 기존 Jira 이슈 참조가 새 Jira 사이트 URL을 사용하도록 자동으로 업데이트됩니다.

GitLab 18.5 이하에서는 기존 Jira 이슈 참조를 업데이트하려면 Markdown 캐시를 무효화해야 합니다.