GitLab for Jira Cloud 앱 관리 문제 해결

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

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

사용자 문서에 대한 내용은 GitLab for Jira Cloud 앱을 참조하십시오.

이미 로그인된 경우 표시되는 로그인 메시지

이미 로그인된 상태에서 GitLab.com에 로그인하라는 메시지가 표시될 수 있습니다:

You need to 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 설정을 비활성화하십시오.

  • GitLab 15.7에서는:

    1. Rails 콘솔을 엽니다.
    2. ApplicationSetting.current_without_cache.update(jira_connect_proxy_url: nil)을 실행합니다.

  • GitLab 15.8 이상에서는:

    1. 왼쪽 사이드바의 하단에서 Admin을 선택합니다.
    2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
    3. GitLab for Jira App을 확장합니다.
    4. Jira Connect Proxy URL 텍스트 상자를 비웁니다.
    5. Save changes를 선택합니다.

문제가 지속되면, 자가 관리형 GitLab 인스턴스가 connect-install-keys.atlassian.com에 연결할 수 있는지 확인하여 Atlassian에서 공개 키를 가져올 수 있습니다.
연결성 테스트를 위해 아래 명령어를 실행합니다:

# A `404 Not Found` is expected because you're not passing a token  
curl --head "https://connect-install-keys.atlassian.com"

Invalid JWT로 동기화 실패

GitLab for Jira Cloud 앱이 자가 관리형 GitLab 인스턴스에서 계속해서 데이터를 동기화하지 못하는 경우, 비밀 토큰이 오래되었을 수 있습니다. Atlassian은 GitLab에 새로운 비밀 토큰을 보낼 수 있습니다.
GitLab이 이러한 토큰을 처리하거나 저장하지 못하면 Invalid JWT 오류가 발생합니다.

자가 관리형 GitLab 인스턴스에서 이 문제를 해결하려면:

앱을 설치하는 방법에 따라 다음 사항을 확인할 수 있습니다:

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

    1. Jira에서 상단 바의 Apps > Manage your apps를 선택합니다.
    2. GitLab for Jira (gitlab.com)을 확장합니다.
    3. Get started를 선택합니다.
    4. Change GitLab version을 선택합니다.
    5. GitLab.com (SaaS)를 선택한 후 Save를 선택합니다.
    6. Change GitLab version을 다시 선택합니다.
    7. GitLab (self-managed)를 선택한 후 Next를 선택합니다.
    8. 모든 체크박스를 선택한 후 Next를 선택합니다.
    9. GitLab 인스턴스 URL을 입력한 후 Save를 선택합니다.

이 방법이 작동하지 않으면, 프리미엄 또는 얼티밋 고객이라면 지원 티켓을 제출하십시오.
GitLab 인스턴스 URL과 Jira URL을 제공하십시오. GitLab 지원팀은 문제를 해결하기 위해 다음 스크립트를 실행할 수 있습니다:

# Check if GitLab.com can connect to the self-managed instance  
checker = Gitlab::TcpChecker.new("gitlab.example.com", 443)  

# Returns `true` if successful  
checker.check  

# Returns an error if the check fails  
checker.error  

# Locate the installation record for the self-managed instance  
installation = JiraConnectInstallation.find_by_instance_url("https://gitlab.example.com")  

# Try to send the token again from GitLab.com to the self-managed instance  
ProxyLifecycleEventService.execute(installation, :installed, installation.instance_url)

오류: GitLab 인스턴스를 업데이트하지 못했습니다.

Jira Cloud 앱을 GitLab에 설정하는 동안, 자체 관리 인스턴스 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. 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)

Jira Connect Proxy 문제 디버깅

Jira Cloud 앱을 설정할 때 Jira Connect Proxy URL을 https://gitlab.com으로 설정한 경우, 다음을 수행할 수 있습니다:

  • 브라우저의 개발 도구에서 네트워크 트래픽을 검사합니다.
  • 추가 정보를 위해 GitLab 인스턴스를 업데이트하지 못했습니다 오류를 재현합니다.

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

이 요청은 200 OK를 반환해야 하지만, 문제가 발생하면 422 Unprocessable Entity를 반환할 수 있습니다.

오류에 대한 응답 본문을 확인할 수 있습니다.

문제를 해결할 수 없고 GitLab 고객인 경우, GitLab 지원에 도움을 요청하십시오.

GitLab 지원에 다음과 같은 정보를 제공하십시오:

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

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

GitLab 지원

참고: 이 단계는 GitLab 지원팀만 완료할 수 있습니다.

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

Kibana에서 관련 로그 항목을 찾으려면, 다음 중 하나를 수행하십시오:

  • 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 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는 자체 관리 인스턴스 또는 인스턴스 앞의 프록시에서 수신한 응답을 포함할 수 있습니다.
    • json.jira_status_code가 401 Unauthorized이고 json.jira_body가 (empty)인 경우:
      • Jira Connect Proxy URL가 https://gitlab.com으로 설정되지 않았을 수 있습니다.
      • 자체 관리 인스턴스가 나가는 연결을 차단하고 있을 수 있습니다. 자체 관리 인스턴스가 connect-install-keys.atlassian.com 및 gitlab.com에 연결할 수 있는지 확인하십시오.
      • 자체 관리 인스턴스가 Jira에서 JWT 토큰을 해독할 수 없습니다. GitLab 16.11부터, exceptions_json.log에 오류에 대한 추가 정보가 포함됩니다.

      • 자체 관리 인스턴스 앞에 리버스 프록시가 있는 경우, 자가 관리 인스턴스에 전송된 Host 헤더가 리버스 프록시 FQDN과 일치하지 않을 수 있습니다. 자가 관리 인스턴스에서 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는 https://docs.gitlab.com/ee/user/gitlab_com/#ip-range에 있는 GitLab.com IP 범위 내에 있어야 합니다.
  "status":401,
  "uri":"/-/jira_connect/events/installed"
}
  • 시나리오 2:
    • json.exception.class 및 json.exception.message가 있습니다.
    • json.exception.class 및 json.exception.message는 자체 관리 인스턴스에 연락하는 동안 문제가 발생했는지 여부를 포함합니다.

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

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 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 for Jira Cloud 앱에 로그인하면 다음과 같은 오류가 발생할 수 있습니다:

Missing required parameter: client_id

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

오류: Failed to sign in to GitLab

앱을 셀프 관리 인스턴스에 포인팅한 후 GitLab for Jira Cloud 앱에 로그인하면 다음과 같은 오류가 발생할 수 있습니다:

Failed to sign in to GitLab

이 문제를 해결하려면 앱을 위해 생성된 OAuth 애플리케이션에서 Trusted 및 Confidential 체크박스가 선택 해제되어 있는지 확인하세요.