InfoGrab Docs

GitLab for Jira Cloud 앱 관리

요약

이 페이지에는 GitLab for Jira Cloud 앱의 관리자 문서가 포함되어 있습니다. GitLab for Jira Cloud 앱을 사용하면 GitLab과 Jira Cloud를 연결하여 개발 정보를 실시간으로 동기화할 수 있습니다.

Note

이 페이지에는 GitLab for Jira Cloud 앱의 관리자 문서가 포함되어 있습니다. 사용자 문서는 GitLab for Jira Cloud 앱을 참조하세요.

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

GitLab Self-Managed 인스턴스에 GitLab for Jira Cloud 앱을 설정하려면 다음 중 하나를 수행합니다:

개요 보기:

위의 동영상은 새로운 Jira Cloud 인스턴스에서는 사용할 수 없을 수 있는 이전 Universal Plugin Manager 인터페이스를 보여줍니다. 다음 지침은 이전 앱 관리 인터페이스와 새 앱 관리 인터페이스를 모두 다룹니다.

Atlassian Marketplace에서 GitLab for Jira Cloud 앱을 설치하면 Atlassian이 개발하고 유지 관리하는 프로젝트 도구 체인을 사용하여 GitLab 리포지터리를 Jira 프로젝트에 연결할 수 있습니다. 프로젝트 도구 체인은 GitLab과 Jira Cloud 간에 개발 정보가 동기화되는 방식에 영향을 미치지 않습니다.

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

OAuth 인증 설정#

Atlassian Marketplace에서 또는 수동으로 GitLab for Jira Cloud 앱을 설치하려면 OAuth 애플리케이션을 만들어야 합니다.

사전 요구 사항:

  • 관리자 액세스.

GitLab Self-Managed 인스턴스에 OAuth 애플리케이션을 만들려면:

  1. 오른쪽 상단 모서리에서 Admin을 선택합니다.

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

  3. New application을 선택합니다.

  4. Redirect URI에서:

    • Atlassian Marketplace 목록에서 앱을 설치하는 경우 https://gitlab.com/-/jira_connect/oauth_callbacks를 입력합니다.
    • 앱을 수동으로 설치하는 경우 <instance_url>/-/jira_connect/oauth_callbacks를 입력하고 <instance_url>을 인스턴스의 URL로 교체합니다.
  5. TrustedConfidential 체크박스를 지웁니다.

    [!note] 로그인 오류를 방지하려면 이 체크박스를 지워야 합니다.

  6. Scopes에서 api 체크박스만 선택합니다.

  7. Save application을 선택합니다.

  8. Application ID 값을 복사합니다.

  9. 왼쪽 사이드바에서 Settings > General을 선택합니다.

  10. GitLab for Jira App을 확장합니다.

  11. Application ID 값을 Jira Connect Application ID에 붙여 넣습니다.

  12. Save changes를 선택합니다.

Jira 사용자 요구 사항#

히스토리
  • GitLab 16.6에서 org-admins 그룹 지원이 도입되었습니다.

Atlassian 조직에서 GitLab for Jira Cloud 앱을 설정하는 데 사용되는 Jira 사용자가 다음 중 하나의 구성원인지 확인해야 합니다:

  • Organization Administrators (org-admins) 그룹. 새로운 Atlassian 조직은 org-admins 그룹을 포함하는 중앙화된 사용자 관리를 사용합니다. 기존 Atlassian 조직은 중앙화된 사용자 관리로 마이그레이션 중입니다. 가능하면 org-admins 그룹을 사용하여 GitLab for Jira Cloud 앱을 관리할 수 있는 Jira 사용자를 나타내야 합니다. 또는 site-admins 그룹을 사용할 수 있습니다.
  • Site Administrators (site-admins) 그룹. site-admins 그룹은 원래 사용자 관리에서 사용되었습니다.

필요한 경우:

  1. 선호하는 그룹을 만듭니다.
  2. 그룹을 편집하여 Jira 사용자를 그룹의 구성원으로 추가합니다.
  3. Jira에서 전역 권한을 사용자 정의한 경우 Jira 사용자에게 Browse users and groups 권한을 부여해야 할 수도 있습니다.

Atlassian Marketplace에서 GitLab for Jira Cloud 앱 설치#

히스토리
  • GitLab 15.7에서 도입되었습니다.

GitLab Self-Managed 인스턴스와 함께 Atlassian Marketplace의 공식 GitLab for Jira Cloud 앱을 사용할 수 있습니다.

이 방법을 사용하면:

  • GitLab.com이 Jira Cloud에서 전송된 설치 및 제거 라이프사이클 이벤트를 처리하고 GitLab 인스턴스로 전달합니다. GitLab Self-Managed 인스턴스의 모든 데이터는 여전히 Jira Cloud로 직접 전송됩니다.
  • GitLab.com이 인스턴스로 리디렉션하여 브랜치 생성 링크를 처리합니다.
  • GitLab 17.2 이전의 버전에서는 GitLab Self-Managed 인스턴스에서 Jira Cloud를 통해 브랜치를 만들 수 없습니다. 자세한 내용은 이슈 391432를 참조하세요.

다음과 같은 경우 GitLab for Jira Cloud 앱을 수동으로 설치할 수 있습니다:

사전 요구 사항#

  • 인스턴스가 공개적으로 사용 가능해야 합니다.
  • 인스턴스가 GitLab 버전 15.7 이상이어야 합니다.
  • OAuth 인증을 설정해야 합니다.
  • GitLab 인스턴스는 HTTPS를 사용해야 하며 GitLab 인증서는 공개적으로 신뢰받거나 전체 체인 인증서를 포함해야 합니다.
  • 네트워크 구성에서 다음을 허용해야 합니다:
    • GitLab Self-Managed 인스턴스에서 Jira Cloud로의 아웃바운드 연결 (Atlassian IP 주소)
    • GitLab Self-Managed 인스턴스와 GitLab.com 간의 인바운드 및 아웃바운드 연결 (GitLab.com IP 주소)
    • 방화벽 뒤의 인스턴스의 경우:
      1. GitLab Self-Managed 인스턴스 앞에 인터넷 접속 역방향 프록시를 설정합니다.
      2. GitLab.com에서의 인바운드 연결을 허용하도록 역방향 프록시를 구성합니다 (GitLab.com IP 주소).
      3. GitLab Self-Managed 인스턴스가 앞서 설명한 아웃바운드 연결을 여전히 만들 수 있는지 확인합니다.
  • 앱을 설치하고 구성하는 Jira 사용자는 특정 요구 사항을 충족해야 합니다.

Atlassian Marketplace 설치를 위한 인스턴스 설정#

사전 요구 사항

GitLab 15.7 이상에서 Atlassian Marketplace 설치를 위해 GitLab Self-Managed 인스턴스를 설정하려면:

  1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
  3. GitLab for Jira App을 확장합니다.
  4. Jira Connect Proxy URLhttps://gitlab.com을 입력하여 Atlassian Marketplace에서 앱을 설치합니다.
  5. Save changes를 선택합니다.

인스턴스 연결#

사전 요구 사항

GitLab Self-Managed 인스턴스를 GitLab for Jira Cloud 앱에 연결하려면:

  1. GitLab for Jira Cloud 앱을 설치합니다.
  2. GitLab for Jira Cloud 앱을 구성합니다.
  3. 선택 사항. Jira Cloud가 연결되었는지 확인합니다.

Jira Cloud가 연결되었는지 확인#

Rails 콘솔을 사용하여 Jira Cloud가 다음에 연결되어 있는지 확인할 수 있습니다:

  • 특정 그룹:

    JiraConnectSubscription.where(namespace: Namespace.by_path('group/subgroup'))
    
  • 특정 프로젝트:

    Project.find_by_full_path('path/to/project').jira_subscription_exists?
    
  • 모든 그룹:

    installation = JiraConnectInstallation.find_by_base_url("https://customer_name.atlassian.net")
    installation.subscriptions
    

GitLab for Jira Cloud 앱 수동 설치#

히스토리
  • GitLab 19.0에서 Connect 기반 수동 설치 방법이 제거되었습니다.
Warning

이전 수동 설치 방법은 Atlassian Connect 개발 모드에 의존했습니다. Atlassian은 2026-03-31에 Connect 기반 비공개 설치를 비활성화했습니다. App descriptor URL 워크플로우로 앱을 수동으로 설치한 경우 이 섹션에 설명된 Forge 기반 설치로 마이그레이션하세요.

공식 Atlassian Marketplace 목록을 사용할 수 없는 경우 GitLab for Jira Cloud 앱을 수동으로 설치합니다. 예를 들어 다음과 같은 경우:

수동 설치 방법은 이제 Atlassian Forge를 기반으로 합니다. 자체 Atlassian 개발자 계정 아래에 GitLab for Jira Cloud Forge 앱의 비공개 사본을 게시하고 GitLab Self-Managed 또는 GitLab Dedicated 인스턴스를 가리킵니다.

사전 요구 사항#

  • 인스턴스가 공개적으로 HTTPS를 통해 사용 가능하고 공개적으로 신뢰받는 인증서가 있어야 합니다.
  • OAuth 인증을 설정해야 합니다.
  • 네트워크 구성에서 다음을 허용해야 합니다:
    • Jira Cloud에서 <instance_url>/-/jira_connect로의 인바운드 HTTPS 연결 (Atlassian IP 주소).
    • GitLab 인스턴스에서 *.atlassian.net으로의 아웃바운드 HTTPS 연결 (Jira로 개발 데이터 푸시).
    • 방화벽 뒤의 인스턴스의 경우:
      1. GitLab Self-Managed 인스턴스 앞에 인터넷 접속 역방향 프록시를 설정합니다.
      2. Jira Cloud에서의 인바운드 연결을 허용하도록 역방향 프록시를 구성합니다.
      3. GitLab Self-Managed 인스턴스가 앞서 설명한 아웃바운드 연결을 여전히 만들 수 있는지 확인합니다.
    • 완전한 에어 갭 인스턴스는 통합을 사용할 수 없습니다. *.atlassian.net으로의 아웃바운드 경로는 개발 패널 및 다른 Jira 측 표면에 필요합니다.
  • 앱을 설치하고 구성하는 Jira 사용자는 특정 요구 사항을 충족해야 합니다.
  • Atlassian 개발자 계정과 Forge CLI를 위한 Atlassian API 토큰.
  • Node.js 22 LTS, Forge CLI, envsubst, git, curl이 설치된 머신.

수동 설치를 위한 인스턴스 설정#

사전 요구 사항

수동 설치를 위해 GitLab Self-Managed 인스턴스를 설정하려면:

  1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
  3. GitLab for Jira App을 확장합니다.
  4. 앱을 수동으로 설치하려면 Jira Connect Proxy URL을 비워 둡니다.
  5. Save changes를 선택합니다.

비공개 Forge 앱 게시#

GitLab for Jira Cloud Forge 앱의 비공개 사본을 게시하고 Jira 사이트에 설치하려면:

  1. gitlab-jira-forge 저장소를 클론합니다:

    git clone --depth 1 https://gitlab.com/gitlab-org/gitlab-jira-forge.git
    cd gitlab-jira-forge
    
  2. 필수 환경 변수를 내보냅니다. 예시 값을 GitLab 인스턴스 URL, Jira 사이트, Atlassian 자격 증명으로 교체합니다:

    export GITLAB_URL=https://gitlab.example.com
    export JIRA_SITE=acme.atlassian.net
    export FORGE_EMAIL=admin@example.com
    export FORGE_API_TOKEN=<your-atlassian-api-token>
    
  3. 래퍼 스크립트를 실행하여 앱을 등록, 배포, 설치합니다:

    ./scripts/install-self-managed.sh
    

    래퍼는 다음을 수행합니다:

    • 필수 도구와 변수를 확인합니다.
    • 처음 사용 시 forge register를 실행하여 Atlassian 계정에 Forge 앱을 만듭니다.
    • 템플릿에서 GITLAB_URL에 고정된 manifest.yml을 생성합니다.
    • forge deploy -e production을 실행합니다.
    • forge install --site $JIRA_SITE --product jira를 실행합니다.

    스크립트는 .env.self-managed에 등록된 APP_ID를 캐시합니다. 이 파일을 백업하세요: 파일을 잃어버리면 앱을 재등록해야 하며, 이는 설치된 모든 Jira 사이트가 앱을 재설치하도록 강제합니다.

단계별 지침, 수동 forge 명령, 문제 해결, 업그레이드 워크플로우는 gitlab-jira-forge 저장소의 자체 관리형 설치 가이드를 참조하세요.

앱이 설치된 후 Jira에서 GitLab for Jira Cloud 앱을 구성하여 GitLab 네임스페이스를 연결합니다.

수동 설치된 앱 업데이트#

업스트림 매니페스트 변경 사항을 비공개 Forge 앱에 가져오려면 --update를 사용하여 래퍼를 재실행합니다:

./scripts/install-self-managed.sh --update

스크립트는 로컬 클론을 빨리 감기하고 매니페스트를 재생성하며 앱을 재배포합니다. 마이너 및 메이저 버전 업그레이드에 대한 자세한 내용은 자체 관리형 설치 가이드의 업그레이드를 참조하세요.

여러 GitLab 인스턴스 연결#

GitLab for Jira 앱을 사용하여 여러 GitLab 인스턴스를 단일 Jira Cloud 인스턴스에 연결합니다. 설치 방법은 연결하려는 인스턴스에 따라 다릅니다.

사전 요구 사항:

  • 각 인스턴스에는 별도의 OAuth 인증이 필요합니다.
  • 각 설치 방법에 대한 사전 요구 사항을 충족해야 합니다.

GitLab.com + GitLab Self-Managed의 경우:

  • GitLab.com에서: Atlassian Marketplace 설치를 사용합니다.
  • GitLab Self-Managed 인스턴스에서: 앱을 수동으로 설치합니다.

여러 GitLab Self-Managed 인스턴스의 경우:

  • 첫 번째 인스턴스에서: Atlassian Marketplace 설치를 사용하거나 앱을 수동으로 설치합니다.
  • 다른 인스턴스에서: 앱을 수동으로 설치합니다.

Jira Cloud는 각 설치에 대해 GitLab for Jira Cloud 앱을 표시합니다.

조직당 하나의 GitLab 인스턴스만 공식 Atlassian Marketplace 목록을 사용할 수 있습니다.

프록시 역할을 하도록 GitLab 인스턴스 구성#

Note

대부분의 사용자에게 이 구성은 필요하지 않습니다. 여러 인스턴스로 Jira Cloud를 사용하려면 GitLab for Jira Cloud 앱으로 각 인스턴스를 연결할 수 있습니다.

GitLab 인스턴스는 GitLab for Jira Cloud 앱을 통해 다른 GitLab 인스턴스의 프록시 역할을 할 수 있습니다. 여러 GitLab 인스턴스를 관리하지만 앱을 한 번만 수동으로 설치하려는 경우 프록시를 사용할 수 있습니다.

프록시 역할을 하도록 GitLab 인스턴스를 구성하려면:

  1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
  3. GitLab for Jira App을 확장합니다.
  4. Enable public key storage를 선택합니다.
  5. Save changes를 선택합니다.
  6. GitLab for Jira Cloud 앱을 수동으로 설치합니다.

프록시를 사용하는 다른 GitLab 인스턴스는 프록시 인스턴스를 가리키도록 다음 설정을 구성해야 합니다:

보안 고려 사항#

다음 보안 고려 사항은 앱 관리에 특정합니다. 앱 사용과 관련된 고려 사항은 보안 고려 사항을 참조하세요.

앱 라이프사이클 이벤트의 GitLab.com 처리#

Atlassian Marketplace에서 GitLab for Jira Cloud 앱을 설치하면 GitLab.com이 Jira에서 라이프사이클 이벤트를 받습니다. 이러한 이벤트는 Jira 프로젝트에 앱이 설치되거나 제거될 때로 제한됩니다.

설치 이벤트에서 GitLab.com은 Jira에서 비밀 토큰을 받습니다. GitLab.com은 이 토큰을 AES256-GCM으로 암호화하여 저장하고 나중에 Jira에서 들어오는 라이프사이클 이벤트를 확인합니다.

GitLab.com은 인스턴스가 동일한 토큰으로 Jira에 대한 요청을 인증할 수 있도록 토큰을 GitLab Self-Managed 인스턴스로 전달합니다. GitLab Self-Managed 인스턴스도 GitLab for Jira Cloud 앱이 설치되거나 제거되었다는 알림을 받습니다.

GitLab Self-Managed 인스턴스에서 Jira 개발 패널로 데이터가 전송될 때 GitLab.com이 아닌 GitLab Self-Managed 인스턴스에서 직접 Jira로 전송됩니다. GitLab.com은 Jira 프로젝트의 데이터에 액세스하는 데 토큰을 사용하지 않습니다. GitLab Self-Managed 인스턴스는 토큰을 사용하여 데이터에 액세스합니다.

GitLab.com이 받는 라이프사이클 이벤트 및 페이로드에 대한 자세한 내용은 Atlassian 문서를 참조하세요.

Mermaid 다이어그램 (10줄)
소스 코드 보기
sequenceDiagram
accTitle: Dataflow of the GitLab for Jira Cloud app installed from the Atlassian Marketplace
accDescr: How GitLab.com handles lifecycle events when the GitLab for Jira Cloud app was installed from the Atlassian Marketplace
participant Jira
participant Your instance
participant GitLab.com
Jira-&gt;&gt;+GitLab.com: App install/uninstall event
GitLab.com-&gt;&gt;-Your instance: App install/uninstall event
Your instance-&gt;&gt;Jira: Your development data</code></pre></details></div>

브랜치 생성의 GitLab.com 처리#

Atlassian Marketplace에서 GitLab for Jira Cloud 앱을 설치한 경우 개발 패널에서 브랜치를 만들기 위한 링크가 처음에 GitLab.com으로 사용자를 보냅니다.

Jira는 GitLab.com으로 JWT 토큰을 전송합니다. GitLab.com은 토큰을 확인하고 요청을 GitLab 인스턴스로 리디렉션하여 요청을 처리합니다.

OAuth를 통한 GitLab 액세스#

GitLab은 Jira와 액세스 토큰을 공유하지 않습니다. 그러나 사용자는 앱을 구성하기 위해 OAuth를 통해 인증해야 합니다.

액세스 토큰은 PKCE OAuth 흐름을 통해 검색되고 클라이언트 측에만 저장됩니다. OAuth 흐름을 초기화하는 앱 프론트엔드는 Jira의 iframe을 통해 GitLab에서 로드되는 JavaScript 애플리케이션입니다.

OAuth 애플리케이션에는 API에 대한 완전한 읽기 및 쓰기 액세스를 부여하는 api 스코프가 있어야 합니다. 이 액세스에는 모든 그룹 및 프로젝트, 컨테이너 레지스트리 및 패키지 레지스트리가 포함됩니다. 그러나 GitLab for Jira Cloud 앱은 이 액세스를 다음에만 사용합니다:

  • 연결할 그룹 표시.
  • 그룹 연결.

OAuth를 통한 액세스는 사용자가 GitLab for Jira Cloud 앱을 구성하는 동안에만 필요합니다. 자세한 내용은 액세스 토큰 만료를 참조하세요.

역방향 프록시 사용#

가능하면 GitLab Self-Managed 인스턴스 앞에 역방향 프록시를 사용하지 않는 것이 좋습니다. 대신 공용 IP 주소를 사용하고 방화벽으로 도메인을 보호하는 것이 좋습니다.

인터넷에서 직접 액세스할 수 없는 GitLab Self-Managed 인스턴스의 GitLab for Jira Cloud 앱에 역방향 프록시를 사용해야 하는 경우 다음 사항을 염두에 두세요:

외부 NGINX#

이 서버 블록은 Jira Cloud에서 작동하는 GitLab에 대한 역방향 프록시를 구성하는 방법의 예입니다:

server {
  listen *:80;
  server_name gitlab.mycompany.com;
  server_tokens off;
  location /.well-known/acme-challenge/ {
    root /var/www/;
  }
  location / {
    return 301 https://gitlab.mycompany.com:443$request_uri;
  }
}
server {
  listen *:443 ssl;
  server_tokens off;
  server_name gitlab.mycompany.com;
  ssl_certificate /etc/letsencrypt/live/gitlab.mycompany.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/gitlab.mycompany.com/privkey.pem;
  ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384';
  ssl_protocols  TLSv1.2 TLSv1.3;
  ssl_prefer_server_ciphers off;
  ssl_session_cache  shared:SSL:10m;
  ssl_session_tickets off;
  ssl_session_timeout  1d;
  access_log "/var/log/nginx/proxy_access.log";
  error_log "/var/log/nginx/proxy_error.log";
  location / {
    proxy_pass https://gitlab.internal;
    proxy_hide_header upgrade;
    proxy_set_header Host             gitlab.mycompany.com:443;
    proxy_set_header X-Real-IP        $remote_addr;
    proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;
  }
}

이 예시에서:

  • gitlab.mycompany.com을 역방향 프록시 FQDN으로, gitlab.internal을 내부 GitLab FQDN으로 교체합니다.
  • ssl_certificatessl_certificate_key를 유효한 인증서로 설정합니다 (예시에서는 Certbot를 사용).
  • GitLab과 Jira Cloud가 성공적으로 연결될 수 있도록 Host 프록시 헤더를 역방향 프록시 FQDN으로 설정합니다.

GitLab을 Jira Cloud에 연결하는 데만 역방향 프록시 FQDN을 사용해야 합니다. 내부 GitLab FQDN을 통해 GitLab에 계속 액세스해야 합니다. 역방향 프록시 FQDN에서 GitLab에 액세스하면 GitLab이 예상대로 작동하지 않을 수 있습니다. 자세한 내용은 이슈 21319를 참조하세요.

추가 JWT 대상 설정#

히스토리
  • GitLab 17.7에서 도입되었습니다.

GitLab이 Jira에서 JWT 토큰을 받으면 JWT 대상을 확인하여 토큰을 검증합니다. 기본적으로 대상은 내부 GitLab FQDN에서 파생됩니다.

일부 역방향 프록시 구성에서는 역방향 프록시 FQDN을 추가 JWT 대상으로 설정해야 할 수 있습니다. 추가 JWT 대상을 설정하려면:

  1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
  3. GitLab for Jira App을 확장합니다.
  4. Jira Connect Additional Audience URL에 추가 대상을 입력합니다 (예: https://gitlab.mycompany.com).
  5. Save changes를 선택합니다.

GitLab for Jira Cloud 앱 관리

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed
원문 보기
요약

이 페이지에는 GitLab for Jira Cloud 앱의 관리자 문서가 포함되어 있습니다. GitLab for Jira Cloud 앱을 사용하면 GitLab과 Jira Cloud를 연결하여 개발 정보를 실시간으로 동기화할 수 있습니다.

Note

이 페이지에는 GitLab for Jira Cloud 앱의 관리자 문서가 포함되어 있습니다. 사용자 문서는 GitLab for Jira Cloud 앱을 참조하세요.

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

GitLab Self-Managed 인스턴스에 GitLab for Jira Cloud 앱을 설정하려면 다음 중 하나를 수행합니다:

개요 보기:

위의 동영상은 새로운 Jira Cloud 인스턴스에서는 사용할 수 없을 수 있는 이전 Universal Plugin Manager 인터페이스를 보여줍니다. 다음 지침은 이전 앱 관리 인터페이스와 새 앱 관리 인터페이스를 모두 다룹니다.

Atlassian Marketplace에서 GitLab for Jira Cloud 앱을 설치하면 Atlassian이 개발하고 유지 관리하는 프로젝트 도구 체인을 사용하여 GitLab 리포지터리를 Jira 프로젝트에 연결할 수 있습니다. 프로젝트 도구 체인은 GitLab과 Jira Cloud 간에 개발 정보가 동기화되는 방식에 영향을 미치지 않습니다.

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

OAuth 인증 설정#

Atlassian Marketplace에서 또는 수동으로 GitLab for Jira Cloud 앱을 설치하려면 OAuth 애플리케이션을 만들어야 합니다.

사전 요구 사항:

  • 관리자 액세스.

GitLab Self-Managed 인스턴스에 OAuth 애플리케이션을 만들려면:

  1. 오른쪽 상단 모서리에서 Admin을 선택합니다.

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

  3. New application을 선택합니다.

  4. Redirect URI에서:

    • Atlassian Marketplace 목록에서 앱을 설치하는 경우 https://gitlab.com/-/jira_connect/oauth_callbacks를 입력합니다.
    • 앱을 수동으로 설치하는 경우 <instance_url>/-/jira_connect/oauth_callbacks를 입력하고 <instance_url>을 인스턴스의 URL로 교체합니다.
  5. TrustedConfidential 체크박스를 지웁니다.

    [!note] 로그인 오류를 방지하려면 이 체크박스를 지워야 합니다.

  6. Scopes에서 api 체크박스만 선택합니다.

  7. Save application을 선택합니다.

  8. Application ID 값을 복사합니다.

  9. 왼쪽 사이드바에서 Settings > General을 선택합니다.

  10. GitLab for Jira App을 확장합니다.

  11. Application ID 값을 Jira Connect Application ID에 붙여 넣습니다.

  12. Save changes를 선택합니다.

Jira 사용자 요구 사항#

히스토리
  • GitLab 16.6에서 org-admins 그룹 지원이 도입되었습니다.

Atlassian 조직에서 GitLab for Jira Cloud 앱을 설정하는 데 사용되는 Jira 사용자가 다음 중 하나의 구성원인지 확인해야 합니다:

  • Organization Administrators (org-admins) 그룹. 새로운 Atlassian 조직은 org-admins 그룹을 포함하는 중앙화된 사용자 관리를 사용합니다. 기존 Atlassian 조직은 중앙화된 사용자 관리로 마이그레이션 중입니다. 가능하면 org-admins 그룹을 사용하여 GitLab for Jira Cloud 앱을 관리할 수 있는 Jira 사용자를 나타내야 합니다. 또는 site-admins 그룹을 사용할 수 있습니다.
  • Site Administrators (site-admins) 그룹. site-admins 그룹은 원래 사용자 관리에서 사용되었습니다.

필요한 경우:

  1. 선호하는 그룹을 만듭니다.
  2. 그룹을 편집하여 Jira 사용자를 그룹의 구성원으로 추가합니다.
  3. Jira에서 전역 권한을 사용자 정의한 경우 Jira 사용자에게 Browse users and groups 권한을 부여해야 할 수도 있습니다.

Atlassian Marketplace에서 GitLab for Jira Cloud 앱 설치#

히스토리
  • GitLab 15.7에서 도입되었습니다.

GitLab Self-Managed 인스턴스와 함께 Atlassian Marketplace의 공식 GitLab for Jira Cloud 앱을 사용할 수 있습니다.

이 방법을 사용하면:

  • GitLab.com이 Jira Cloud에서 전송된 설치 및 제거 라이프사이클 이벤트를 처리하고 GitLab 인스턴스로 전달합니다. GitLab Self-Managed 인스턴스의 모든 데이터는 여전히 Jira Cloud로 직접 전송됩니다.
  • GitLab.com이 인스턴스로 리디렉션하여 브랜치 생성 링크를 처리합니다.
  • GitLab 17.2 이전의 버전에서는 GitLab Self-Managed 인스턴스에서 Jira Cloud를 통해 브랜치를 만들 수 없습니다. 자세한 내용은 이슈 391432를 참조하세요.

다음과 같은 경우 GitLab for Jira Cloud 앱을 수동으로 설치할 수 있습니다:

사전 요구 사항#

  • 인스턴스가 공개적으로 사용 가능해야 합니다.
  • 인스턴스가 GitLab 버전 15.7 이상이어야 합니다.
  • OAuth 인증을 설정해야 합니다.
  • GitLab 인스턴스는 HTTPS를 사용해야 하며 GitLab 인증서는 공개적으로 신뢰받거나 전체 체인 인증서를 포함해야 합니다.
  • 네트워크 구성에서 다음을 허용해야 합니다:
    • GitLab Self-Managed 인스턴스에서 Jira Cloud로의 아웃바운드 연결 (Atlassian IP 주소)
    • GitLab Self-Managed 인스턴스와 GitLab.com 간의 인바운드 및 아웃바운드 연결 (GitLab.com IP 주소)
    • 방화벽 뒤의 인스턴스의 경우:
      1. GitLab Self-Managed 인스턴스 앞에 인터넷 접속 역방향 프록시를 설정합니다.
      2. GitLab.com에서의 인바운드 연결을 허용하도록 역방향 프록시를 구성합니다 (GitLab.com IP 주소).
      3. GitLab Self-Managed 인스턴스가 앞서 설명한 아웃바운드 연결을 여전히 만들 수 있는지 확인합니다.
  • 앱을 설치하고 구성하는 Jira 사용자는 특정 요구 사항을 충족해야 합니다.

Atlassian Marketplace 설치를 위한 인스턴스 설정#

사전 요구 사항

GitLab 15.7 이상에서 Atlassian Marketplace 설치를 위해 GitLab Self-Managed 인스턴스를 설정하려면:

  1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
  3. GitLab for Jira App을 확장합니다.
  4. Jira Connect Proxy URLhttps://gitlab.com을 입력하여 Atlassian Marketplace에서 앱을 설치합니다.
  5. Save changes를 선택합니다.

인스턴스 연결#

사전 요구 사항

GitLab Self-Managed 인스턴스를 GitLab for Jira Cloud 앱에 연결하려면:

  1. GitLab for Jira Cloud 앱을 설치합니다.
  2. GitLab for Jira Cloud 앱을 구성합니다.
  3. 선택 사항. Jira Cloud가 연결되었는지 확인합니다.

Jira Cloud가 연결되었는지 확인#

Rails 콘솔을 사용하여 Jira Cloud가 다음에 연결되어 있는지 확인할 수 있습니다:

  • 특정 그룹:

    JiraConnectSubscription.where(namespace: Namespace.by_path('group/subgroup'))
    
  • 특정 프로젝트:

    Project.find_by_full_path('path/to/project').jira_subscription_exists?
    
  • 모든 그룹:

    installation = JiraConnectInstallation.find_by_base_url("https://customer_name.atlassian.net")
    installation.subscriptions
    

GitLab for Jira Cloud 앱 수동 설치#

히스토리
  • GitLab 19.0에서 Connect 기반 수동 설치 방법이 제거되었습니다.
Warning

이전 수동 설치 방법은 Atlassian Connect 개발 모드에 의존했습니다. Atlassian은 2026-03-31에 Connect 기반 비공개 설치를 비활성화했습니다. App descriptor URL 워크플로우로 앱을 수동으로 설치한 경우 이 섹션에 설명된 Forge 기반 설치로 마이그레이션하세요.

공식 Atlassian Marketplace 목록을 사용할 수 없는 경우 GitLab for Jira Cloud 앱을 수동으로 설치합니다. 예를 들어 다음과 같은 경우:

수동 설치 방법은 이제 Atlassian Forge를 기반으로 합니다. 자체 Atlassian 개발자 계정 아래에 GitLab for Jira Cloud Forge 앱의 비공개 사본을 게시하고 GitLab Self-Managed 또는 GitLab Dedicated 인스턴스를 가리킵니다.

사전 요구 사항#

  • 인스턴스가 공개적으로 HTTPS를 통해 사용 가능하고 공개적으로 신뢰받는 인증서가 있어야 합니다.
  • OAuth 인증을 설정해야 합니다.
  • 네트워크 구성에서 다음을 허용해야 합니다:
    • Jira Cloud에서 <instance_url>/-/jira_connect로의 인바운드 HTTPS 연결 (Atlassian IP 주소).
    • GitLab 인스턴스에서 *.atlassian.net으로의 아웃바운드 HTTPS 연결 (Jira로 개발 데이터 푸시).
    • 방화벽 뒤의 인스턴스의 경우:
      1. GitLab Self-Managed 인스턴스 앞에 인터넷 접속 역방향 프록시를 설정합니다.
      2. Jira Cloud에서의 인바운드 연결을 허용하도록 역방향 프록시를 구성합니다.
      3. GitLab Self-Managed 인스턴스가 앞서 설명한 아웃바운드 연결을 여전히 만들 수 있는지 확인합니다.
    • 완전한 에어 갭 인스턴스는 통합을 사용할 수 없습니다. *.atlassian.net으로의 아웃바운드 경로는 개발 패널 및 다른 Jira 측 표면에 필요합니다.
  • 앱을 설치하고 구성하는 Jira 사용자는 특정 요구 사항을 충족해야 합니다.
  • Atlassian 개발자 계정과 Forge CLI를 위한 Atlassian API 토큰.
  • Node.js 22 LTS, Forge CLI, envsubst, git, curl이 설치된 머신.

수동 설치를 위한 인스턴스 설정#

사전 요구 사항

수동 설치를 위해 GitLab Self-Managed 인스턴스를 설정하려면:

  1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
  3. GitLab for Jira App을 확장합니다.
  4. 앱을 수동으로 설치하려면 Jira Connect Proxy URL을 비워 둡니다.
  5. Save changes를 선택합니다.

비공개 Forge 앱 게시#

GitLab for Jira Cloud Forge 앱의 비공개 사본을 게시하고 Jira 사이트에 설치하려면:

  1. gitlab-jira-forge 저장소를 클론합니다:

    git clone --depth 1 https://gitlab.com/gitlab-org/gitlab-jira-forge.git
    cd gitlab-jira-forge
    
  2. 필수 환경 변수를 내보냅니다. 예시 값을 GitLab 인스턴스 URL, Jira 사이트, Atlassian 자격 증명으로 교체합니다:

    export GITLAB_URL=https://gitlab.example.com
    export JIRA_SITE=acme.atlassian.net
    export FORGE_EMAIL=admin@example.com
    export FORGE_API_TOKEN=<your-atlassian-api-token>
    
  3. 래퍼 스크립트를 실행하여 앱을 등록, 배포, 설치합니다:

    ./scripts/install-self-managed.sh
    

    래퍼는 다음을 수행합니다:

    • 필수 도구와 변수를 확인합니다.
    • 처음 사용 시 forge register를 실행하여 Atlassian 계정에 Forge 앱을 만듭니다.
    • 템플릿에서 GITLAB_URL에 고정된 manifest.yml을 생성합니다.
    • forge deploy -e production을 실행합니다.
    • forge install --site $JIRA_SITE --product jira를 실행합니다.

    스크립트는 .env.self-managed에 등록된 APP_ID를 캐시합니다. 이 파일을 백업하세요: 파일을 잃어버리면 앱을 재등록해야 하며, 이는 설치된 모든 Jira 사이트가 앱을 재설치하도록 강제합니다.

단계별 지침, 수동 forge 명령, 문제 해결, 업그레이드 워크플로우는 gitlab-jira-forge 저장소의 자체 관리형 설치 가이드를 참조하세요.

앱이 설치된 후 Jira에서 GitLab for Jira Cloud 앱을 구성하여 GitLab 네임스페이스를 연결합니다.

수동 설치된 앱 업데이트#

업스트림 매니페스트 변경 사항을 비공개 Forge 앱에 가져오려면 --update를 사용하여 래퍼를 재실행합니다:

./scripts/install-self-managed.sh --update

스크립트는 로컬 클론을 빨리 감기하고 매니페스트를 재생성하며 앱을 재배포합니다. 마이너 및 메이저 버전 업그레이드에 대한 자세한 내용은 자체 관리형 설치 가이드의 업그레이드를 참조하세요.

여러 GitLab 인스턴스 연결#

GitLab for Jira 앱을 사용하여 여러 GitLab 인스턴스를 단일 Jira Cloud 인스턴스에 연결합니다. 설치 방법은 연결하려는 인스턴스에 따라 다릅니다.

사전 요구 사항:

  • 각 인스턴스에는 별도의 OAuth 인증이 필요합니다.
  • 각 설치 방법에 대한 사전 요구 사항을 충족해야 합니다.

GitLab.com + GitLab Self-Managed의 경우:

  • GitLab.com에서: Atlassian Marketplace 설치를 사용합니다.
  • GitLab Self-Managed 인스턴스에서: 앱을 수동으로 설치합니다.

여러 GitLab Self-Managed 인스턴스의 경우:

  • 첫 번째 인스턴스에서: Atlassian Marketplace 설치를 사용하거나 앱을 수동으로 설치합니다.
  • 다른 인스턴스에서: 앱을 수동으로 설치합니다.

Jira Cloud는 각 설치에 대해 GitLab for Jira Cloud 앱을 표시합니다.

조직당 하나의 GitLab 인스턴스만 공식 Atlassian Marketplace 목록을 사용할 수 있습니다.

프록시 역할을 하도록 GitLab 인스턴스 구성#

Note

대부분의 사용자에게 이 구성은 필요하지 않습니다. 여러 인스턴스로 Jira Cloud를 사용하려면 GitLab for Jira Cloud 앱으로 각 인스턴스를 연결할 수 있습니다.

GitLab 인스턴스는 GitLab for Jira Cloud 앱을 통해 다른 GitLab 인스턴스의 프록시 역할을 할 수 있습니다. 여러 GitLab 인스턴스를 관리하지만 앱을 한 번만 수동으로 설치하려는 경우 프록시를 사용할 수 있습니다.

프록시 역할을 하도록 GitLab 인스턴스를 구성하려면:

  1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
  3. GitLab for Jira App을 확장합니다.
  4. Enable public key storage를 선택합니다.
  5. Save changes를 선택합니다.
  6. GitLab for Jira Cloud 앱을 수동으로 설치합니다.

프록시를 사용하는 다른 GitLab 인스턴스는 프록시 인스턴스를 가리키도록 다음 설정을 구성해야 합니다:

보안 고려 사항#

다음 보안 고려 사항은 앱 관리에 특정합니다. 앱 사용과 관련된 고려 사항은 보안 고려 사항을 참조하세요.

앱 라이프사이클 이벤트의 GitLab.com 처리#

Atlassian Marketplace에서 GitLab for Jira Cloud 앱을 설치하면 GitLab.com이 Jira에서 라이프사이클 이벤트를 받습니다. 이러한 이벤트는 Jira 프로젝트에 앱이 설치되거나 제거될 때로 제한됩니다.

설치 이벤트에서 GitLab.com은 Jira에서 비밀 토큰을 받습니다. GitLab.com은 이 토큰을 AES256-GCM으로 암호화하여 저장하고 나중에 Jira에서 들어오는 라이프사이클 이벤트를 확인합니다.

GitLab.com은 인스턴스가 동일한 토큰으로 Jira에 대한 요청을 인증할 수 있도록 토큰을 GitLab Self-Managed 인스턴스로 전달합니다. GitLab Self-Managed 인스턴스도 GitLab for Jira Cloud 앱이 설치되거나 제거되었다는 알림을 받습니다.

GitLab Self-Managed 인스턴스에서 Jira 개발 패널로 데이터가 전송될 때 GitLab.com이 아닌 GitLab Self-Managed 인스턴스에서 직접 Jira로 전송됩니다. GitLab.com은 Jira 프로젝트의 데이터에 액세스하는 데 토큰을 사용하지 않습니다. GitLab Self-Managed 인스턴스는 토큰을 사용하여 데이터에 액세스합니다.

GitLab.com이 받는 라이프사이클 이벤트 및 페이로드에 대한 자세한 내용은 Atlassian 문서를 참조하세요.

Mermaid 다이어그램 (10줄)
소스 코드 보기
sequenceDiagram
accTitle: Dataflow of the GitLab for Jira Cloud app installed from the Atlassian Marketplace
accDescr: How GitLab.com handles lifecycle events when the GitLab for Jira Cloud app was installed from the Atlassian Marketplace
participant Jira
participant Your instance
participant GitLab.com
Jira-&gt;&gt;+GitLab.com: App install/uninstall event
GitLab.com-&gt;&gt;-Your instance: App install/uninstall event
Your instance-&gt;&gt;Jira: Your development data</code></pre></details></div>

브랜치 생성의 GitLab.com 처리#

Atlassian Marketplace에서 GitLab for Jira Cloud 앱을 설치한 경우 개발 패널에서 브랜치를 만들기 위한 링크가 처음에 GitLab.com으로 사용자를 보냅니다.

Jira는 GitLab.com으로 JWT 토큰을 전송합니다. GitLab.com은 토큰을 확인하고 요청을 GitLab 인스턴스로 리디렉션하여 요청을 처리합니다.

OAuth를 통한 GitLab 액세스#

GitLab은 Jira와 액세스 토큰을 공유하지 않습니다. 그러나 사용자는 앱을 구성하기 위해 OAuth를 통해 인증해야 합니다.

액세스 토큰은 PKCE OAuth 흐름을 통해 검색되고 클라이언트 측에만 저장됩니다. OAuth 흐름을 초기화하는 앱 프론트엔드는 Jira의 iframe을 통해 GitLab에서 로드되는 JavaScript 애플리케이션입니다.

OAuth 애플리케이션에는 API에 대한 완전한 읽기 및 쓰기 액세스를 부여하는 api 스코프가 있어야 합니다. 이 액세스에는 모든 그룹 및 프로젝트, 컨테이너 레지스트리 및 패키지 레지스트리가 포함됩니다. 그러나 GitLab for Jira Cloud 앱은 이 액세스를 다음에만 사용합니다:

  • 연결할 그룹 표시.
  • 그룹 연결.

OAuth를 통한 액세스는 사용자가 GitLab for Jira Cloud 앱을 구성하는 동안에만 필요합니다. 자세한 내용은 액세스 토큰 만료를 참조하세요.

역방향 프록시 사용#

가능하면 GitLab Self-Managed 인스턴스 앞에 역방향 프록시를 사용하지 않는 것이 좋습니다. 대신 공용 IP 주소를 사용하고 방화벽으로 도메인을 보호하는 것이 좋습니다.

인터넷에서 직접 액세스할 수 없는 GitLab Self-Managed 인스턴스의 GitLab for Jira Cloud 앱에 역방향 프록시를 사용해야 하는 경우 다음 사항을 염두에 두세요:

외부 NGINX#

이 서버 블록은 Jira Cloud에서 작동하는 GitLab에 대한 역방향 프록시를 구성하는 방법의 예입니다:

server {
  listen *:80;
  server_name gitlab.mycompany.com;
  server_tokens off;
  location /.well-known/acme-challenge/ {
    root /var/www/;
  }
  location / {
    return 301 https://gitlab.mycompany.com:443$request_uri;
  }
}
server {
  listen *:443 ssl;
  server_tokens off;
  server_name gitlab.mycompany.com;
  ssl_certificate /etc/letsencrypt/live/gitlab.mycompany.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/gitlab.mycompany.com/privkey.pem;
  ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384';
  ssl_protocols  TLSv1.2 TLSv1.3;
  ssl_prefer_server_ciphers off;
  ssl_session_cache  shared:SSL:10m;
  ssl_session_tickets off;
  ssl_session_timeout  1d;
  access_log "/var/log/nginx/proxy_access.log";
  error_log "/var/log/nginx/proxy_error.log";
  location / {
    proxy_pass https://gitlab.internal;
    proxy_hide_header upgrade;
    proxy_set_header Host             gitlab.mycompany.com:443;
    proxy_set_header X-Real-IP        $remote_addr;
    proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;
  }
}

이 예시에서:

  • gitlab.mycompany.com을 역방향 프록시 FQDN으로, gitlab.internal을 내부 GitLab FQDN으로 교체합니다.
  • ssl_certificatessl_certificate_key를 유효한 인증서로 설정합니다 (예시에서는 Certbot를 사용).
  • GitLab과 Jira Cloud가 성공적으로 연결될 수 있도록 Host 프록시 헤더를 역방향 프록시 FQDN으로 설정합니다.

GitLab을 Jira Cloud에 연결하는 데만 역방향 프록시 FQDN을 사용해야 합니다. 내부 GitLab FQDN을 통해 GitLab에 계속 액세스해야 합니다. 역방향 프록시 FQDN에서 GitLab에 액세스하면 GitLab이 예상대로 작동하지 않을 수 있습니다. 자세한 내용은 이슈 21319를 참조하세요.

추가 JWT 대상 설정#

히스토리
  • GitLab 17.7에서 도입되었습니다.

GitLab이 Jira에서 JWT 토큰을 받으면 JWT 대상을 확인하여 토큰을 검증합니다. 기본적으로 대상은 내부 GitLab FQDN에서 파생됩니다.

일부 역방향 프록시 구성에서는 역방향 프록시 FQDN을 추가 JWT 대상으로 설정해야 할 수 있습니다. 추가 JWT 대상을 설정하려면:

  1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
  3. GitLab for Jira App을 확장합니다.
  4. Jira Connect Additional Audience URL에 추가 대상을 입력합니다 (예: https://gitlab.mycompany.com).
  5. Save changes를 선택합니다.