GitLab for Jira Cloud 앱을 사용하면 GitLab과 Jira Cloud를 연결해 개발 정보를 실시간으로 동기화할 수 있습니다. 이 정보는 Jira 개발 패널에서 확인할 수 있습니다.

GitLab for Jira Cloud 앱을 사용해 최상위 그룹이나 하위 그룹을 링크할 수 있습니다. 프로젝트나 개인 네임스페이스는 직접 링크할 수 없습니다.

GitLab.com에서 GitLab for Jira Cloud 앱을 설정하려면 GitLab for Jira Cloud 앱을 설치합니다.

앱을 설정한 뒤에는 Atlassian 이 개발하고 유지 관리하는 프로젝트 툴체인을 사용해 GitLab 리포지터리를 Jira 프로젝트에 링크할 수 있습니다. 프로젝트 툴체인은 GitLab과 Jira Cloud 간 개발 정보 동기화 방식에 영향을 주지 않습니다.

Jira Data Center 또는 Jira Server의 경우, Atlassian 이 개발하고 유지 관리하는 Jira DVCS 커넥터를 사용합니다.

GitLab data synced to Jira#

그룹을 링크하면, Jira 이슈 ID를 언급할 때 해당 그룹의 모든 프로젝트에 대해 다음 GitLab 데이터가 Jira로 동기화됩니다.

• 기존 프로젝트 데이터(그룹을 링크하기 전):
  • 최근 머지 리퀘스트 400건
  • 최근 브랜치 400개와 각 브랜치의 최근 커밋
• 신규 프로젝트 데이터(그룹을 링크한 후):
  • 머지 리퀘스트
    • 머지 리퀘스트 작성자
  • 브랜치
  • 커밋
    • 커밋 작성자
  • 파이프라인
  • 배포
  • 기능 플래그

Install the GitLab for Jira Cloud app#

사전 요구 사항:

• 네트워크에서 GitLab과 Jira 간 인바운드·아웃바운드 연결을 허용해야 합니다.
• 일정한 Jira 사용자 요구 사항을 충족해야 합니다.

GitLab for Jira Cloud 앱을 설치하려면 다음과 같이 합니다.

1. Jira 상단 바에서 Apps > Explore more apps를 선택하고 GitLab for Jira Cloud를 검색합니다.
2. GitLab for Jira Cloud를 선택한 다음 Get it now를 선택합니다.

또는 Atlassian Marketplace에서 직접 앱을 받을 수 있습니다.

이제 GitLab for Jira Cloud 앱을 설정할 수 있습니다.

전체 개요는 GitLab.com 용 GitLab for Jira Cloud 앱을 Atlassian Marketplace에서 설치하기를 참고합니다.

위 영상은 이전 버전의 Universal Plugin Manager 인터페이스를 보여주며, 최신 Jira Cloud 인스턴스에서는 사용할 수 없을 수도 있습니다. 아래 안내는 이전·신규 앱 관리 인터페이스를 모두 다룹니다.

Configure the GitLab for Jira Cloud app#

사전 요구 사항:

• GitLab 그룹에 대해 Maintainer 또는 Owner 권한이 있어야 합니다.
• 일정한 Jira 사용자 요구 사항을 충족해야 합니다.

GitLab for Jira Cloud 앱을 하나 이상의 GitLab 그룹에 링크해 GitLab 데이터를 Jira로 동기화할 수 있습니다. GitLab for Jira Cloud 앱을 설정하려면 다음과 같이 합니다.

1. Jira에서 Apps 옆의 가로 줄임표([ellipsis_h])를 선택하고 Manage your apps를 선택합니다.

2. 다음 방법 중 하나로 앱으로 이동합니다.

   • 앱 관리가 통합된 인스턴스의 경우:

     1. "App management has moved to Administration" 메시지가 표시되면 Take me there를 선택합니다. 표시되지 않으면 아래 레거시 앱 관리 인스턴스의 경우 안내를 따릅니다.
     2. Installed apps 탭에서 GitLab for Jira를 찾습니다. 앱을 설치한 방법에 따라 앱 이름은 다음과 같습니다.
        • Atlassian Marketplace에서 앱을 설치한 경우 GitLab for Jira (gitlab.com).
        • 앱을 수동으로 설치한 경우 GitLab for Jira (<gitlab.example.com>).
     3. 가로 줄임표([ellipsis_h])를 선택한 다음 Get started를 선택해 통합을 설정합니다.

   • 레거시 앱 관리 인스턴스의 경우:

     1. GitLab for Jira를 확장합니다. 앱을 설치한 방법에 따라 앱 이름은 다음과 같습니다.
        • Atlassian Marketplace에서 앱을 설치한 경우 GitLab for Jira (gitlab.com).
        • 앱을 수동으로 설치한 경우 GitLab for Jira (<gitlab.example.com>).
     2. Get started를 선택해 통합을 설정합니다.

3. 선택 사항. GitLab Self-Managed를 Jira와 링크하려면 Change GitLab version을 선택합니다.

   1. 모든 체크박스를 선택한 다음 Next를 선택합니다.
   2. GitLab instance URL을 입력한 다음 Save를 선택합니다.

4. Sign in to GitLab을 선택합니다.

   [!note] 엔터프라이즈 사용자 중 그룹의 비밀번호 인증이 비활성화된 경우, 먼저 소속 그룹의 SSO(싱글 사인온) URL로 GitLab에 로그인해야 합니다.

   GitLab은 그룹을 링크하기 위해 로그인을 요구하지만, 이 설정을 특정 사용자와 연결하지는 않습니다. GitLab 인스턴스는 Jira 로부터 토큰을 받아 Jira의 정보를 업데이트하는 데 사용합니다. 자세한 내용은 GitLab의 Jira 접근을 참고합니다.

5. Authorize를 선택합니다. 이제 그룹 목록이 표시됩니다.

6. Link groups를 선택합니다.

7. 그룹을 링크하려면 Link를 선택합니다.

GitLab 그룹을 링크한 후에는 다음과 같이 동작합니다.

• 해당 그룹의 모든 프로젝트에 대해 데이터가 Jira로 동기화됩니다. 초기 데이터 동기화는 분당 20개 프로젝트 단위 배치로 진행됩니다. 프로젝트가 많은 그룹은 일부 프로젝트의 데이터 동기화가 지연될 수 있습니다.
• 해당 그룹과 그 하위 그룹·프로젝트 전체에 대해 GitLab for Jira Cloud 앱 통합이 자동으로 켜집니다. 이 통합을 통해 Jira Service Management를 설정할 수 있습니다.

Configure Jira Service Management#

히스토리

• Introduced in GitLab 17.2 with a feature flag named enable_jira_connect_configuration. Disabled by default.
• Generally available in GitLab 17.4. Feature flag enable_jira_connect_configuration removed.

사전 요구 사항:

• GitLab for Jira Cloud 앱이 설치되어 있어야 합니다.
• GitLab for Jira Cloud 앱 설정에서 링크된 GitLab 그룹이 있어야 합니다.

GitLab을 IT 서비스 프로젝트에 연결해 배포를 추적할 수 있습니다.

설정은 GitLab의 GitLab for Jira Cloud 앱 통합에서 이루어집니다. GitLab 그룹이 링크된 후에는 GitLab에서 그룹과 그 하위 그룹, 프로젝트에 대해 통합이 켜집니다.

GitLab for Jira Cloud 앱 통합은 그룹 링크를 통해 자동으로 켜지거나 꺼지며, GitLab 통합 설정 화면이나 API를 통해서는 제어할 수 없습니다.

Jira Service Management에서:

1. 서비스 프로젝트에서 Project settings > Change management로 이동합니다.
2. Connect Pipeline > GitLab을 선택한 다음, 설정 흐름 마지막에서 Service ID를 복사합니다.

GitLab에서:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Integrations를 선택합니다.
3. GitLab for Jira Cloud app을 선택합니다. 통합이 꺼져 있다면 먼저 GitLab 그룹을 링크합니다. 그러면 해당 그룹과 하위 그룹, 프로젝트에 대해 GitLab for Jira Cloud 앱 통합이 켜집니다.
4. Service ID 텍스트 상자에 이 프로젝트에 매핑할 서비스 ID를 입력합니다. 여러 서비스 ID를 사용하려면 각 서비스 ID 사이에 쉼표를 넣습니다.

서비스는 최대 100개까지 매핑할 수 있습니다.

Jira 에서의 배포 추적에 대한 자세한 내용은 배포 추적 설정을 참고합니다.

Set up deployment gating with GitLab#

히스토리

• Introduced in GitLab 17.6.

배포 게이팅을 설정하면 GitLab의 변경 요청을 Jira Service Management로 가져와 승인받을 수 있습니다. 배포 게이팅을 사용하면 선택한 환경으로의 모든 GitLab 배포가 자동으로 Jira Service Management로 전송되며, 승인된 경우에만 배포됩니다.

Create the service account token#

GitLab에서 서비스 계정 토큰을 만들려면 먼저 개인 액세스 토큰을 만들어야 합니다. 이 토큰은 Jira Service Management에서 GitLab 배포를 관리하는 데 사용되는 서비스 계정 토큰을 인증합니다.

서비스 계정 토큰을 만들려면 다음과 같이 합니다.

1. 서비스 계정 사용자를 만듭니다.
2. 서비스 계정을 그룹 또는 프로젝트에 추가합니다. 이때 개인 액세스 토큰을 사용합니다.
3. 서비스 계정을 보호된 환경에 추가합니다.
4. 서비스 계정 토큰을 생성합니다. 이때 개인 액세스 토큰을 사용합니다.
5. 서비스 계정 토큰 값을 복사합니다.

Enable deployment gating#

배포 게이팅을 켜려면 다음과 같이 합니다.

• GitLab에서:

  1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
  2. Settings > Integrations를 선택합니다.
  3. GitLab for Jira Cloud app을 선택합니다.
  4. Deployment gating 아래에서 Enable deployment gating 체크박스를 선택합니다.
  5. Environment tiers 텍스트 상자에 배포 게이팅을 켤 환경의 이름을 입력합니다. 환경 이름은 쉼표로 구분해 여러 개 입력할 수 있습니다(예: production, staging, testing, development). 소문자만 사용합니다.
  6. Save changes를 선택합니다.

• Jira Service Management에서:

  1. 배포 게이팅을 설정합니다.
  2. Service account token 텍스트 상자에 GitLab에서 복사한 서비스 계정 토큰 값을 붙여넣습니다.

Add the service account to protected environments#

GitLab에서 보호된 환경에 서비스 계정을 추가하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Protected environments를 확장하고 Protect an environment를 선택합니다.
4. Select environment 드롭다운 목록에서 보호할 환경을 선택합니다(예: staging).
5. Allowed to deploy 드롭다운 목록에서 이 환경에 배포할 수 있는 사람을 선택합니다(예: Developers + Maintainers).
6. Approvers 드롭다운 목록에서 앞서 만든 서비스 계정을 선택합니다.
7. Protect를 선택합니다.

Example API requests#

• 서비스 계정 사용자 만들기:

  curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=<name_of_your_choice>&username=<username_of_your_choice>"  "<https://gitlab.com/api/v4/groups/<group_id>/service_accounts"
  

• 개인 액세스 토큰을 사용해 서비스 계정을 그룹 또는 프로젝트에 추가하기:

  curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
       --data "user_id=<service_account_id>&access_level=30" "https://gitlab.com/api/v4/groups/<group_id>/members"
  curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
       --data "user_id=<service_account_id>&access_level=30" "https://gitlab.com/api/v4/projects/<project_id>/members"
  

• 개인 액세스 토큰을 사용해 서비스 계정 토큰 생성하기:

  curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"
  "https://gitlab.com/api/v4/groups/<group_id>/service_accounts/<service_account_id>/personal_access_tokens" --data "scopes[]=api,read_user,read_repository" --data "name=service_accounts_token"
  

Update the GitLab for Jira Cloud app#

앱 업데이트는 대부분 자동으로 이루어집니다. 자세한 내용은 Atlassian 문서를 참고합니다.

앱에 추가 권한이 필요한 경우, Jira에서 업데이트를 수동으로 승인해야 합니다.

Migration from Atlassian Connect to Forge#

히스토리

• Introduced in GitLab 18.10.

GitLab for Jira Cloud 앱은 Atlassian Connect에서 Atlassian Forge로 마이그레이션되었습니다. 이 변경은 Atlassian의 Connect 앱 지원 종료 발표에 따른 것입니다.

기존 기능은 다음을 포함해 모두 그대로 동작합니다.

• 브랜치, 커밋, 머지 리퀘스트, 파이프라인, 배포, 기능 플래그를 Jira 개발 패널로 동기화합니다.
• Jira 이슈로부터 GitLab 브랜치를 만듭니다.
• Smart Commits를 사용한 시간 추적과 이슈 전환을 지원합니다.
• GitLab.com과 GitLab Self-Managed 인스턴스를 모두 지원합니다.

Atlassian Marketplace에서 GitLab for Jira Cloud 앱을 설치했다면 다음과 같이 진행됩니다.

• Forge 버전은 기존 앱의 주요 업그레이드로 표시됩니다.
• Jira 관리자가 업그레이드를 승인해야 합니다.
• 기존에 동기화된 개발 데이터는 자동으로 보존됩니다. Forge 앱은 동일한 앱 식별자를 사용하므로 데이터를 별도로 마이그레이션할 필요가 없습니다.
• GitLab 설정을 변경할 필요가 없습니다.

이전에 Connect 기반의 App descriptor URL 방식으로 GitLab for Jira Cloud 앱을 수동으로 설치했다면, Forge 기반 방식으로 마이그레이션해야 합니다. Atlassian 이 2026-03-31에 Connect 기반 비공개 설치를 비활성화했으므로, 기존 방식은 더 이상 동작하지 않습니다.

마이그레이션해서 기존 데이터를 보존하려면 다음과 같이 합니다.

1. Connect 앱 디스크립터를 Forge 매니페스트로 변환합니다.
2. 변환한 매니페스트를 사용해 새 Forge 앱을 등록합니다.

이 단계를 거치면 새 Forge 앱이 원래의 connect.app.key를 그대로 유지합니다. Jira는 이 키와 새 Forge 앱 ID를 함께 사용해 두 설치를 연결된 것으로 인식하므로, 기존에 동기화된 개발 데이터가 그대로 유지됩니다.

변환 후에는 Forge 기반 수동 설치 안내를 따라 GitLab for Jira Cloud Forge 앱의 비공개 사본을 본인의 Atlassian 개발자 계정 아래에 게시합니다.

Connect에서 Forge 로의 전환에 대한 자세한 내용은 Forge 도입 방법에 대한 Atlassian 가이드를 참고합니다.

Security considerations#

GitLab for Jira Cloud 앱은 GitLab과 Jira를 연결합니다. 두 애플리케이션 간에 데이터를 공유해야 하며, 양방향으로 접근 권한을 부여해야 합니다.

GitLab access to Jira#

GitLab for Jira Cloud 앱을 설정하면, GitLab은 Jira 로부터 공유 시크릿 토큰을 받습니다. 이 토큰은 Jira 프로젝트에 대해 GitLab에 READ, WRITE, DELETE 앱 스코프를 부여합니다. 이 스코프는 Jira 프로젝트의 개발 패널 정보를 업데이트하는 데 필요합니다. 이 토큰은 앱이 설치된 Jira 프로젝트 외의 다른 Atlassian 제품에 대한 접근 권한은 GitLab에 부여하지 않습니다.

토큰은 AES256-GCM으로 암호화되어 GitLab에 저장됩니다. Jira 프로젝트에서 GitLab for Jira Cloud 앱을 제거하면 GitLab은 토큰을 삭제합니다.

Jira access to GitLab#

Jira는 GitLab에 대한 어떠한 접근 권한도 얻지 않습니다.

Data sent from GitLab to Jira#

Jira로 전송되는 전체 데이터는 Jira로 동기화되는 GitLab 데이터를 참고합니다.

Jira로 전송되는 구체적인 데이터 속성에 대한 자세한 내용은 데이터 동기화에 관여하는 serializer 클래스를 참고합니다.

Data sent from Jira to GitLab#

GitLab for Jira Cloud 앱이 설치되거나 제거될 때, GitLab은 Jira 로부터 생명 주기 이벤트를 받습니다. 이 이벤트에는 이후의 생명 주기 이벤트를 검증하고 Jira로 데이터를 전송할 때 인증하는 데 사용하는 토큰이 포함됩니다. Jira 로부터의 생명 주기 이벤트 요청은 검증됩니다.

Atlassian Marketplace의 GitLab for Jira Cloud 앱을 사용하는 GitLab Self-Managed 인스턴스의 경우, GitLab.com 이 생명 주기 이벤트를 처리해 GitLab Self-Managed 인스턴스로 전달합니다. 자세한 내용은 GitLab.com의 앱 생명 주기 이벤트 처리를 참고합니다.

Data stored by Jira#

Jira로 전송된 데이터는 Jira에 저장되며 Jira 개발 패널에 표시됩니다.

GitLab for Jira Cloud 앱을 제거하면 Jira는 이 데이터를 영구적으로 삭제합니다. 이 처리는 비동기적으로 이루어지며 최대 몇 시간이 걸릴 수 있습니다.

Privacy and security details in the Atlassian Marketplace#

자세한 내용은 Atlassian Marketplace 목록의 개인 정보 보호 및 보안 세부 정보를 참고합니다.

Troubleshooting#

GitLab for Jira Cloud 앱을 사용하는 동안 다음과 같은 문제를 겪을 수 있습니다.

관리자용 문제 해결은 GitLab for Jira Cloud 앱 관리를 참고합니다.

Error: Failed to link group#

GitLab for Jira Cloud 앱을 연결할 때 다음 오류가 발생할 수 있습니다.

Failed to link group. Please try again.

권한이 충분하지 않아 Jira 로부터 사용자 정보를 가져올 수 없는 경우 403 Forbidden 이 반환됩니다.

이 문제를 해결하려면 일정한 Jira 사용자 요구 사항을 충족하는지 확인합니다.

Jira 사용자가 관리자 권한을 가지고 있지만 site-admins 또는 org-admins 그룹의 명시적인 멤버가 아닌 경우, 오류: Jira 사용자가 사이트 또는 조직 관리자가 아님을 참고합니다.

Jira Code does not work after linking to a GitLab group#

GitLab for Jira Cloud 앱을 GitLab 그룹에 링크한 후 Jira Code가 동작하지 않을 수 있습니다. 이 문제를 해결하려면 Bitbucket과 Jira를 모두 설정해야 합니다.

Bitbucket에서:

1. Atlassian 계정으로 로그인합니다.
2. 워크스페이스 이름을 만들어 입력합니다.

Jira에서:

1. Projects에서 프로젝트를 선택합니다.
2. Development > Code를 선택합니다.
3. Connect Bitbucket > Link Bitbucket Cloud workspace를 선택합니다.
4. Bitbucket에서 만든 워크스페이스를 선택합니다.
5. Grant access를 선택합니다.

이제 리포지터리가 Jira Code에 표시됩니다.

자세한 내용은 issue JRACLOUD-95847을 참고합니다.