GitLab for Jira Cloud 앱 관리 문제 해결

Tier: Free, Premium, Ultimate Offering: Self-Managed

GitLab for Jira Cloud 앱을 관리하는 중 다음과 같은 문제에 직면할 수 있습니다.

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

이미 로그인된 상태에서 로그인 메시지가 표시됨

이미 로그인한 상태에서 다음과 같은 메시지를 받을 수 있습니다. 

계속하기 전에 로그인하거나 등록해야 합니다.

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

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

매뉴얼 설치 실패

공식 마켓플레이스 디렉터리에서 GitLab for Jira Cloud 앱을 설치한 후 매뉴얼으로 설치한 경우 다음 오류 중 하나를 받을 수 있습니다. 

앱 "gitlab-jira-connect-gitlab.com"은 Atlassian Marketplace에서 이전에 설치되었으므로 로컬 앱으로 설치할 수 없습니다.

앱 호스트가 설치 중에 연락을 시도할 때 HTTP 응답 코드 401을 반환했습니다. 나중에 다시 시도하거나 앱 공급업체에 문의하세요.

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

  • GitLab 15.7에서:

    1. 레일 콘솔을 엽니다.
    2. ApplicationSetting.current_without_cache.update(jira_connect_proxy_url: null)을 실행합니다.

  • GitLab 15.8 이상에서:

    1. 왼쪽 사이드바에서 아래쪽에 있는 관리 영역(Admin Area)을 선택합니다.
    2. 왼쪽 사이드바에서 설정 > 일반(General)을 선택합니다.
    3. GitLab for Jira App을 확장합니다.
    4. Jira Connect Proxy URL 텍스트 상자를 지웁니다.
    5. 변경 사항 저장을 선택합니다.

문제가 지속되면 Self-Managed형 GitLab 인스턴스가 Atlassian으로부터 공개 키를 가져오기 위해 connect-install-keys.atlassian.com에 연결할 수 있는지 확인하세요. 연결성을 테스트하려면 다음 명령을 실행하세요. 

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

잘못된 JWT로 데이터 동기화 실패

GitLab for Jira Cloud 앱이 지속적으로 Self-Managed형 GitLab 인스턴스에서 데이터를 동기화하지 못할 경우 비밀 토큰이 오래되었을 수 있습니다. Atlassian은 GitLab으로 새로운 비밀 토큰을 보낼 수 있습니다. 그러나 GitLab이 이러한 토큰을 처리하거나 저장하지 못하면 잘못된 JWT 오류가 발생합니다.

이 문제를 해결하려면 Self-Managed형 GitLab 인스턴스에서 다음을 확인하세요:

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

  1. Jira에서 상단 바에서 앱 > 앱 관리를 선택합니다.
  2. GitLab for Jira (gitlab.com)을 확장합니다.
  3. 시작하기를 선택합니다.
  4. GitLab 버전 변경을 선택합니다.
  5. GitLab.com (SaaS)을 선택한 후 저장을 선택합니다.
  6. 다시 GitLab 버전 변경을 선택합니다.
  7. GitLab (Self-Managed)를 선택한 후 다음을 선택합니다.
  8. 모든 확인란을 선택한 후 다음을 선택합니다.
  9. GitLab 인스턴스 URL을 입력한 후 저장을 선택합니다.

이 방법이 작동하지 않으면, Premium이나 Ultimate 고객이라면 지원 티켓을 제출할 수 있습니다. GitLab 지원팀은 다음 스크립트를 실행하여 문제를 해결하려고 시도할 수 있습니다. 

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

  # Self-Managed형 인스턴스에서 설치 레코드 탐색
  installation = JiraConnectInstallation.find_by_instance_url("https://gitlab.example.com")
  
  # GitLab.com에서 Self-Managed형 인스턴스로 토큰을 다시 보내려고 시도
  ProxyLifecycleEventService.execute(installation, :installed, installation.instance_url)

GitLab 인스턴스 업데이트 실패

GitLab for Jira Cloud 앱을 설정한 후 Self-Managed형 인스턴스 URL을 입력한 후 GitLab 인스턴스 업데이트 실패 오류 메시지를 받을 수 있습니다.

이 문제를 해결하려면 설치 방법의 모든 전제 조건이 충족되었는지 확인하세요:

Jira Connect Proxy URL을 구성하고 필요 사항을 확인한 후에도 문제가 지속되면 Jira Connect Proxy 문제 해결을 검토하세요.

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

  1. 레일 콘솔을 엽니다.

  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)

Jira Connect Proxy 문제 해결

만약 인스턴스를 설정할 때 Jira Connect Proxy URL을 https://gitlab.com으로 설정한다면, 다음을 수행할 수 있습니다:

  • 브라우저의 개발 도구에서 네트워크 트래픽을 검사합니다.
  • GitLab 인스턴스 업데이트에 실패했습니다 오류를 재현하여 자세한 정보를 얻을 수 있습니다.

https://gitlab.com/-/jira_connect/installations로 GET 요청을 확인해야 합니다.

이 요청은 200 OK을 반환해야 하지만 문제가 있으면 422 Unprocessable Entity를 반환할 수 있습니다. 응답 본문을 확인할 수 있습니다.

문제를 해결할 수 없고 GitLab 고객이라면, 도움을 받기 위해 GitLab 지원팀에 연락하세요. 다음을 GitLab 지원팀에 제공하세요:

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

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

GitLab 지원팀

note
이러한 단계는 GitLab 지원팀에 의해서만 완료될 수 있습니다.

Kibana에서 로그는 json.meta.caller_id: JiraConnect::InstallationsController#update 및 NOT json.status: 200로 필터링되어야 합니다. 만약 X-Request-Id 값을 제공받았다면, 해당 값을 json.correlation_id에 대해 사용하여 결과를 좁힐 수 있습니다.

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

첫 번째 로그에 대해서:

  • json.status가 422 Unprocessable Entity입니다.
  • json.params.value는 Self-Managed형 GitLab 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는 Self-Managed형 인스턴스나 해당 인스턴스 앞에 있는 프록시로부터 받은 응답을 포함할 수 있습니다.
    • 만약 json.jira_status_code가 401 Unauthorized이고 json.jira_body가 비어있다면:
      • Jira Connect Proxy URL은 아마도 https://gitlab.com로 설정되지 않았을 것입니다.

      • 만약 Self-Managed형 인스턴스 앞에 역방향 프록시가 있다면, 인스턴스로 전송된 Host 헤더가 역방향 프록시 FQDN과 일치하지 않을 수 있습니다. Self-Managed형 인스턴스의 Workhorse 로그를 확인하세요: 

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

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

        {
  "host":"gitlab.mycompany.com:443", // 호스트는 역방향 프록시 FQDN과 일치해야 합니다
  "remote_ip":"34.74.226.3", // 이 IP는 GitLab.com IP 범위 내에 있어야 합니다. https://docs.gitlab.com/ee/user/gitlab_com/#ip-range
  "status":401,
  "uri":"/-/jira_connect/events/installed"
}
  • 시나리오 2:
    • json.exception.class와 json.exception.message가 존재합니다.
    • json.exception.class와 json.exception.message는 Self-Managed형 인스턴스에 연락하는 동안 문제가 발생했는지 여부를 포함합니다.

그룹 링크에 실패함

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

그룹을 링크하는 데 실패했습니다. 다시 시도하세요.

사용자 정보가 부족한 경우 Jira에서 사용자 정보를 가져올 수 없어서 403 Forbidden이 반환됩니다.

이 문제를 해결하려면, 앱을 설치하고 구성하는 Jira 사용자가 일정한 요구 사항을 충족하는지 확인하세요.

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

Jira Connect 애플리케이션 ID를 불러오지 못했습니다

Self-Managed형 인스턴스를 가리키도록 GitLab for Jira Cloud 앱에 로그인한 후 다음의 오류를 받을 수 있습니다: 

Jira Connect 애플리케이션 ID를 불러오지 못했습니다. 다시 시도하세요.

브라우저 콘솔을 확인하면 다음과 같은 메시지를 볼 수도 있습니다: 

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으로 설정되었는지 확인하세요.