GitLab for Jira Cloud 앱을 관리할 때 다음 문제가 발생할 수 있습니다.

사용자 문서는 GitLab for Jira Cloud 앱을 참조하세요.

이미 로그인했는데 로그인 메시지가 표시됨#

GitLab.com에 이미 로그인되어 있는데 다음과 같은 로그인 메시지가 표시될 수 있습니다:

Sign in or sign up before continuing.

GitLab for Jira Cloud 앱은 설정 페이지에서 그룹을 추가하기 위해 iframe을 사용합니다. 일부 브라우저는 크로스 사이트 쿠키를 차단하여 이 문제가 발생할 수 있습니다.

이 문제를 해결하려면 OAuth 인증을 설정하세요.

수동 설치 실패#

공식 마켓플레이스 목록에서 GitLab for Jira Cloud 앱을 설치하고 수동 설치로 교체한 경우 다음 오류 중 하나가 발생할 수 있습니다:

The app "gitlab-jira-connect-gitlab.com" could not be installed as a local app as it has previously been installed from Atlassian Marketplace

The app host returned HTTP response code 401 when we tried to contact it during installation. Please try again later or contact the app vendor.

이 문제를 해결하려면 Jira Connect Proxy URL 설정을 비활성화하세요.

사전 요구 사항:

• 관리자 액세스 권한.

Jira Connect Proxy URL 설정을 비활성화하려면:

• GitLab 15.7:
  1. Rails 콘솔을 엽니다.
  2. ApplicationSetting.current_without_cache.update(jira_connect_proxy_url: nil)을 실행합니다.
• GitLab 15.8 이상:
  1. 오른쪽 상단에서 관리자를 선택합니다.
  2. 왼쪽 사이드바에서 설정 > 일반을 선택합니다.
  3. GitLab for Jira App을 확장합니다.
  4. Jira Connect Proxy URL 텍스트 상자를 지웁니다.
  5. 변경 사항 저장을 선택합니다.

문제가 지속되면 인스턴스가 Atlassian에서 공개 키를 가져오기 위해 connect-install-keys.atlassian.com에 연결할 수 있는지 확인하세요. 연결을 테스트하려면 다음 명령을 실행합니다:

# 토큰을 전달하지 않기 때문에 `404 Not Found`가 예상됩니다
curl --head "https://connect-install-keys.atlassian.com"

GitLab for Jira Cloud 앱 설치 변경 사항 검토#

GitLab for Jira Cloud 앱에 대한 설치 변경 사항을 검토하는 방법이 여러 가지 있습니다. 자세한 내용은 공식 Jira 문서를 참조하세요.

Invalid JWT로 데이터 동기화 실패#

GitLab for Jira Cloud 앱이 인스턴스에서 데이터를 지속적으로 동기화하지 못하는 경우 시크릿 토큰이 오래되었을 수 있습니다. Atlassian은 GitLab에 새 시크릿 토큰을 전송할 수 있습니다. GitLab이 이러한 토큰을 처리하거나 저장하지 못하면 Invalid JWT 오류가 발생합니다.

이 문제를 해결하려면:

• 인스턴스가 공개적으로 액세스 가능한지 확인합니다:

  • GitLab.com (공식 Atlassian Marketplace 목록에서 앱을 설치한 경우).
  • Jira Cloud (앱을 수동으로 설치한 경우).

• 앱을 설치할 때 /-/jira_connect/events/installed 엔드포인트로 전송되는 토큰 요청이 Jira에서 액세스 가능한지 확인합니다. 다음 명령은 401 Unauthorized를 반환해야 합니다:

  curl --include --request POST "https://gitlab.example.com/-/jira_connect/events/installed"
  

• 인스턴스에 SSL이 구성되어 있는 경우 인증서가 유효하고 공개적으로 신뢰할 수 있는지 확인합니다.

앱을 설치한 방법에 따라 다음을 확인할 수 있습니다:

• 공식 Atlassian Marketplace 목록에서 앱을 설치한 경우 GitLab for Jira Cloud 앱에서 GitLab 버전을 전환합니다:

  1. Jira에서 앱 옆의 수평 줄임표([ellipsis_h])를 선택하고 앱 관리를 선택합니다.

  2. 다음 방법 중 하나를 사용하여 앱으로 이동합니다:

     중앙 집중식 앱 관리가 있는 인스턴스의 경우:

     1. "앱 관리가 관리로 이동되었습니다"가 표시되면 여기로 이동을 선택합니다. 그렇지 않으면 아래의 레거시 앱 관리가 있는 인스턴스 지침을 따르세요.
     2. 설치된 앱 탭에서 GitLab for Jira (gitlab.com) 앱을 찾아 수평 줄임표([ellipsis_h])를 선택한 다음 시작하기를 선택합니다.

     레거시 앱 관리가 있는 인스턴스의 경우:

     1. GitLab for Jira (gitlab.com) 앱을 찾아 갈매기([chevron-right])를 선택한 다음 시작하기를 선택합니다.

  3. GitLab 버전 변경을 선택합니다.

  4. **GitLab.com (SaaS)**를 선택한 다음 저장을 선택합니다.

  5. GitLab 버전 변경을 다시 선택합니다.

  6. **GitLab(자체 관리형)**을 선택한 다음 다음을 선택합니다.

  7. 모든 확인란을 선택한 다음 다음을 선택합니다.

  8. GitLab 인스턴스 URL을 입력한 다음 저장을 선택합니다.

  이 방법이 작동하지 않으면 Premium 또는 Ultimate 고객인 경우 지원 티켓을 제출하세요. GitLab 인스턴스 URL과 Jira URL을 제공합니다. GitLab 지원팀은 다음 스크립트를 실행하여 문제를 해결하려고 시도할 수 있습니다:

  # GitLab.com이 GitLab Self-Managed 인스턴스에 연결할 수 있는지 확인
  checker = Gitlab::TcpChecker.new("gitlab.example.com", 443)
  
  # 성공하면 `true`를 반환
  checker.check
  
  # 확인이 실패하면 오류를 반환
  checker.error
  

  # GitLab Self-Managed 인스턴스의 설치 레코드 찾기
  installation = JiraConnectInstallation.find_by_instance_url("https://gitlab.example.com")
  
  # GitLab.com에서 GitLab Self-Managed 인스턴스로 다시 토큰 전송 시도
  ProxyLifecycleEventService.execute(installation, :installed, installation.instance_url)
  

• 앱을 수동으로 설치한 경우:

  • Jira가 인스턴스에 연결할 수 있는지 Jira Cloud 지원에 확인을 요청합니다.
  • 앱을 재설치합니다. 이 방법은 Jira 개발 패널에서 모든 동기화된 데이터를 제거할 수 있습니다.

오류: Failed to update the GitLab instance#

GitLab for Jira Cloud 앱을 설정할 때 GitLab Self-Managed 인스턴스 URL을 입력한 후 Failed to update the GitLab instance 오류가 발생할 수 있습니다.

이 문제를 해결하려면 설치 방법에 대한 모든 사전 요구 사항이 충족되었는지 확인하세요:

• GitLab for Jira Cloud 앱 연결을 위한 사전 요구 사항
• GitLab for Jira Cloud 앱 수동 설치를 위한 사전 요구 사항

Jira Connect Proxy URL을 구성했고 사전 요구 사항을 확인한 후에도 문제가 지속되면 Jira Connect Proxy 문제 디버깅을 검토하세요.

GitLab 15.8 이하를 사용하고 이전에 jira_connect_oauth_self_managed와 jira_connect_oauth 기능 플래그를 모두 활성화한 경우 알려진 문제로 인해 jira_connect_oauth_self_managed 플래그를 비활성화해야 합니다. 이러한 플래그를 확인하려면:

1. Rails 콘솔을 엽니다.

2. 다음 코드를 실행합니다:

   # 두 기능 플래그가 모두 활성화되어 있는지 확인합니다.
   # 플래그가 활성화되어 있으면 이 명령은 `true`를 반환합니다.
   Feature.enabled?(:jira_connect_oauth)
   Feature.enabled?(:jira_connect_oauth_self_managed)
   
   # 두 플래그가 모두 활성화된 경우 `jira_connect_oauth_self_managed` 플래그를 비활성화합니다.
   Feature.disable(:jira_connect_oauth_self_managed)
   

오류: Invalid audience#

역방향 프록시를 사용하는 경우 exceptions_json.log에 다음과 같은 메시지가 포함될 수 있습니다:

Invalid audience. Expected https://proxy.example.com/-/jira_connect, received https://gitlab.example.com/-/jira_connect

이 문제를 해결하려면 역방향 프록시 FQDN을 추가 JWT 대상으로 설정하세요.

Jira Connect Proxy 문제 디버깅#

인스턴스를 설정할 때 Jira Connect Proxy URL을 https://gitlab.com으로 설정한 경우:

• 브라우저의 개발 도구에서 네트워크 트래픽을 검사합니다.
• Failed to update the GitLab instance 오류를 재현하여 자세한 정보를 얻습니다.

https://gitlab.com/-/jira_connect/installations로 GET 요청이 표시되어야 합니다.

이 요청은 200 OK를 반환해야 하지만 문제가 있는 경우 422 Unprocessable Entity를 반환할 수 있습니다. 응답 본문에서 오류를 확인할 수 있습니다.

문제를 해결할 수 없고 GitLab 고객인 경우 GitLab 지원에 도움을 요청하세요. GitLab 지원팀에 다음을 제공합니다:

• GitLab Self-Managed 인스턴스 URL.
• GitLab.com 사용자 이름.
• 선택 사항. https://gitlab.com/-/jira_connect/installations로의 실패한 GET 요청에 대한 X-Request-Id 응답 헤더.
• 선택 사항. 문제를 캡처하고 harcleaner로 처리한 HAR 파일.

GitLab 지원팀은 GitLab.com 서버 로그에서 문제를 조사할 수 있습니다.

GitLab 지원#

Jira Connect Proxy URL https://gitlab.com/-/jira_connect/installations로의 각 GET 요청은 두 개의 로그 항목을 생성합니다.

Kibana에서 관련 로그 항목을 찾으려면:

• https://gitlab.com/-/jira_connect/installations로의 GET 요청에 대한 X-Request-Id 값 또는 상관 관계 ID가 있는 경우 Kibana 로그는 json.meta.caller_id: JiraConnect::InstallationsController#update, NOT json.status: 200 및 json.correlation_id: <X-Request-Id>로 필터링해야 합니다. 이렇게 하면 두 개의 로그 항목이 반환됩니다.

• 고객의 자체 관리형 URL이 있는 경우:

  1. Kibana 로그는 json.meta.caller_id: JiraConnect::InstallationsController#update, NOT json.status: 200 및 json.params.value: {"instance_url"=>"https://gitlab.example.com"}으로 필터링해야 합니다. 자체 관리형 URL에는 앞에 슬래시가 없어야 합니다. 이렇게 하면 로그 항목 중 하나가 반환됩니다.
  2. json.correlation_id를 필터에 추가합니다.
  3. json.params.value 필터를 제거합니다. 이렇게 하면 다른 로그 항목이 반환됩니다.

첫 번째 로그의 경우:

• json.status는 422 Unprocessable Entity입니다.
• json.params.value는 GitLab Self-Managed URL [[FILTERED], {"instance_url"=>"https://gitlab.example.com"}]과 일치해야 합니다.

두 번째 로그의 경우 다음 시나리오 중 하나가 발생할 수 있습니다:

• 시나리오 1:

  • json.message, json.jira_status_code, json.jira_body가 있습니다.

  • json.message는 Proxy lifecycle event received error response 또는 유사한 내용입니다.

  • json.jira_status_code와 json.jira_body는 GitLab Self-Managed 인스턴스 또는 인스턴스 앞에 있는 프록시에서 수신한 응답을 포함할 수 있습니다.

  • json.jira_status_code가 401 Unauthorized이고 json.jira_body가 (empty)인 경우:

    • Jira Connect Proxy URL이 https://gitlab.com으로 설정되지 않았을 수 있습니다.

    • GitLab Self-Managed 인스턴스가 발신 연결을 차단하고 있을 수 있습니다. GitLab Self-Managed 인스턴스가 connect-install-keys.atlassian.com과 gitlab.com 모두에 연결할 수 있는지 확인합니다.

    • GitLab Self-Managed 인스턴스가 Jira의 JWT 토큰을 복호화할 수 없습니다. GitLab 16.11부터 exceptions_json.log에 오류에 대한 자세한 정보가 포함됩니다.

    • GitLab Self-Managed 인스턴스 앞에 역방향 프록시가 있는 경우 GitLab Self-Managed 인스턴스로 전송되는 Host 헤더가 역방향 프록시 FQDN과 일치하지 않을 수 있습니다. GitLab Self-Managed 인스턴스의 Workhorse 로그를 확인합니다:

      grep /-/jira_connect/events/installed /var/log/gitlab/gitlab-workhorse/current
      

      출력에는 다음이 포함될 수 있습니다:

      {
        "host":"gitlab.mycompany.com:443", // 호스트는 GitLab for Jira Cloud 앱에 입력된 역방향 프록시 FQDN과 일치해야 합니다
        "remote_ip":"34.74.226.3", // 이 IP는 GitLab.com IP 범위 https://docs.gitlab.com/user/gitlab_com/#ip-range 내에 있어야 합니다
        "status":401,
        "uri":"/-/jira_connect/events/installed"
      }
      

  • json.jira_status_code가 404 Not Found이고 json.jira_body에 일반적인 GitLab 404 페이지의 HTML이 포함된 경우 자체 관리형 인스턴스의 통합 허용 목록이 GitLab for Jira Cloud 앱을 허용하는지 확인합니다.

• 시나리오 2:

  • json.exception.class와 json.exception.message가 있습니다.
  • json.exception.class와 json.exception.message에는 GitLab Self-Managed 인스턴스에 연락하는 동안 문제가 발생했는지 여부가 포함됩니다.

오류: Jira 사용자가 사이트 또는 조직 관리자가 아님#

GitLab 그룹을 링크하려고 할 때 다음 오류 중 하나가 발생할 수 있습니다:

The Jira user is not a site or organization administrator. Check the permissions in Jira and try again.

Failed to link group. Please try again.

이 문제는 Jira 사용자가 site-admins 또는 org-admins 그룹의 구성원이 아닐 때 발생합니다. GitLab은 Jira API 엔드포인트 /rest/api/3/user?expand=groups를 호출하여 그룹 구성원 자격을 확인하고 사용자가 두 그룹 중 하나에 속하는지 검증합니다.

사용자가 Atlassian 조직에서 사이트 관리자로 표시되고 전체 관리자 권한을 가지고 있더라도, site-admins 또는 org-admins 그룹에 명시적으로 추가되지 않으면 GitLab 권한 확인이 실패합니다. 또한 사용자 정의 그룹이나 제품별 역할을 통해 부여된 관리자 권한은 GitLab에서 감지되지 않습니다.

이 문제를 해결하려면 Jira 사용자를 org-admins 또는 site-admins 그룹에 추가합니다:

• Atlassian 조직에 로그인합니다.
• Directory > Groups로 이동합니다.
• org-admins 그룹(권장) 또는 site-admins 그룹을 선택합니다. 그룹이 없으면 생성합니다.
• Jira 사용자를 그룹에 추가합니다.

Jira 사용자 요구 사항에 대한 자세한 내용은 Jira 사용자 요구 사항을 참조하세요.

GitLab은 OAuth 범위 제한으로 인해 Jira의 권한 API를 사용하여 관리자 상태를 직접 확인할 수 없습니다. 자세한 내용은 이슈 #420687 및 병합 요청 !135771을 참조하세요.

오류: Failed to link group#

그룹을 링크할 때 다음 오류가 발생할 수 있습니다:

Failed to link group. Please try again.

이 오류는 여러 가지 이유로 반환될 수 있습니다.

• 권한이 부족하여 Jira에서 사용자 정보를 가져올 수 없는 경우 403 Forbidden이 반환될 수 있습니다. 이 문제를 해결하려면 앱을 설치하고 구성하는 Jira 사용자가 특정 요구 사항을 충족하는지 확인합니다.

• 역방향 프록시와 함께 재작성 또는 하위 필터를 사용하는 경우에도 이 오류가 발생할 수 있습니다. 요청에 사용된 앱 키에는 일부 역방향 프록시 필터가 캡처할 수 있는 서버 호스트 이름의 일부가 포함됩니다. 인증이 올바르게 작동하려면 Atlassian과 GitLab의 앱 키가 일치해야 합니다.

• GitLab for Jira Cloud 앱이 처음 설치될 때 GitLab 인스턴스가 초기에 잘못 구성된 경우 이 오류가 발생할 수 있습니다. 이 경우 jira_connect_installation 테이블의 데이터를 삭제해야 할 수 있습니다. 기존 GitLab for Jira 앱 설치를 유지할 필요가 없다고 확실한 경우에만 이 데이터를 삭제하세요.

  1. Jira 프로젝트에서 GitLab for Jira Cloud 앱을 제거합니다.

  2. 레코드를 삭제하려면 GitLab Rails 콘솔에서 다음 명령을 실행합니다:

     JiraConnectInstallation.delete_all
     

오류: Failed to load Jira Connect Application ID#

앱을 GitLab Self-Managed 인스턴스로 연결한 후 GitLab for Jira Cloud 앱에 로그인할 때 다음 오류가 발생할 수 있습니다:

Failed to load Jira Connect Application ID. Please try again.

브라우저 콘솔을 확인하면 다음 메시지도 표시될 수 있습니다:

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://gitlab.example.com/-/jira_connect/oauth_application_id. (Reason: CORS header 'Access-Control-Allow-Origin' missing). Status code: 403.

이 문제를 해결하려면:

1. /-/jira_connect/oauth_application_id가 공개적으로 액세스 가능하고 JSON 응답을 반환하는지 확인합니다:

   curl --include "https://gitlab.example.com/-/jira_connect/oauth_application_id"
   

2. 공식 Atlassian Marketplace 목록에서 앱을 설치한 경우 Jira Connect Proxy URL이 후행 슬래시 없이 https://gitlab.com으로 설정되어 있는지 확인합니다.

오류: Missing required parameter: client_id#

앱을 GitLab Self-Managed 인스턴스로 연결한 후 GitLab for Jira Cloud 앱에 로그인할 때 다음 오류가 발생할 수 있습니다:

Missing required parameter: client_id

이 문제를 해결하려면 설치 방법에 대한 모든 사전 요구 사항이 충족되었는지 확인하세요:

• GitLab for Jira Cloud 앱 연결을 위한 사전 요구 사항
• GitLab for Jira Cloud 앱 수동 설치를 위한 사전 요구 사항

오류: Failed to sign in to GitLab#

앱을 GitLab Self-Managed 인스턴스로 연결한 후 GitLab for Jira Cloud 앱에 로그인할 때 다음 오류가 발생할 수 있습니다:

Failed to sign in to GitLab

이 문제를 해결하려면 앱을 위해 생성된 OAuth 애플리케이션에서 신뢰됨 및 기밀 확인란이 해제되어 있는지 확인합니다. 오류가 지속되면 이슈 581765를 참조하세요.

앱에 Google Chrome을 사용하는 경우 다른 브라우저를 사용해 보세요.