GitLab for Jira Cloud 앱 관리 문제 해결

요약

GitLab for Jira Cloud 앱을 관리할 때 다음과 같은 문제가 발생할 수 있습니다. 사용자 대상 문제 해결은 GitLab for Jira Cloud 앱을 참고합니다. 이미 GitLab.com에 로그인한 상태인데도 다음과 같이 로그인을 요구하는 메시지가 표시될 수 있습니다.

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 설정을 끄는 방법은 다음과 같습니다.

오른쪽 위 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > General을 선택합니다.
GitLab for Jira App을 확장합니다.
Jira Connect Proxy URL 텍스트 상자를 비웁니다.
Save changes를 선택합니다.

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

# A `404 Not Found` is expected because you're not passing a token
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에서 Apps 옆의 가로 줄임표([ellipsis_h])를 선택한 다음 Manage your apps를 선택합니다.
2. 다음 방법 중 하나로 앱으로 이동합니다.
  
  중앙 집중식 앱 관리를 사용하는 인스턴스:
  1. "App management has moved to Administration" 이 보이면 Take me there를 선택합니다. 그렇지 않으면 아래의 레거시 앱 관리를 사용하는 인스턴스 안내를 따릅니다.
  2. Installed apps 탭에서 GitLab for Jira (gitlab.com) 앱을 찾아 가로 줄임표([ellipsis_h])를 선택한 다음 Get started를 선택합니다.
  레거시 앱 관리를 사용하는 인스턴스:
  1. GitLab for Jira (gitlab.com) 앱을 찾아 갈매기표([chevron-right])를 선택한 다음 Get started를 선택합니다.
3. Change GitLab version을 선택합니다.
4. **GitLab.com (SaaS)**를 선택한 다음 Save를 선택합니다.
5. 다시 Change GitLab version을 선택합니다.
6. **GitLab (self-managed)**를 선택한 다음 Next를 선택합니다.
7. 모든 체크박스를 선택한 다음 Next를 선택합니다.
8. GitLab instance URL을 입력한 다음 Save를 선택합니다.
이 방법으로 해결되지 않고 Premium 또는 Ultimate 고객이라면 지원 티켓을 제출합니다. GitLab 인스턴스 URL과 Jira URL을 함께 제공합니다. GitLab 지원팀은 문제 해결을 위해 다음 스크립트를 실행할 수 있습니다.
```
# Check if GitLab.com can connect to the GitLab 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 GitLab Self-Managed instance
installation = JiraConnectInstallation.find_by_instance_url("https://gitlab.example.com")

# Try to send the token again from GitLab.com to the GitLab Self-Managed instance
ProxyLifecycleEventService.execute(installation, :installed, installation.instance_url)
```
앱을 수동으로 설치한 경우는 다음과 같습니다.
- Jira Cloud 지원팀에 Jira가 인스턴스에 연결할 수 있는지 확인을 요청합니다.
- 앱을 다시 설치합니다. 이 방법은 Jira 개발 패널에서 동기화된 데이터를 모두 제거할 수 있습니다.

오류: `Failed to update the GitLab instance`#

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

이 문제를 해결하려면 설치 방식에 필요한 사전 요구 사항이 모두 충족되었는지 확인합니다.

Jira Connect Proxy URL을 구성했고 사전 요구 사항을 확인한 뒤에도 문제가 계속된다면 Jira Connect Proxy 문제 디버깅을 참고합니다.

오류: `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 응답 헤더.
선택 사항. 문제를 포착한 HAR 파일을 harcleaner로 처리한 결과.

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

GitLab 지원팀#

Note

이 단계는 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>로 필터링합니다. 로그 항목 두 개가 반환됩니다.
고객의 GitLab Self-Managed URL 이 있다면 다음과 같이 진행합니다.
1. Kibana 로그를 json.meta.caller_id: JiraConnect::InstallationsController#update, NOT json.status: 200, json.params.value: {"instance_url"=>"https://gitlab.example.com"}로 필터링합니다. GitLab Self-Managed 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 토큰을 복호화하지 못하고 있습니다. 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", // The host should match the reverse proxy FQDN entered into the GitLab for Jira Cloud app
  "remote_ip":"34.74.226.3", // This IP should be within the GitLab.com IP range 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 Self-Managed 인스턴스의 통합 허용 목록이 GitLab for Jira Cloud 앱을 허용하는지 확인합니다.
시나리오 2:
- json.exception.class와 json.exception.message가 있습니다.
- json.exception.class와 json.exception.message는 GitLab Self-Managed 인스턴스에 접속하는 과정에서 문제가 발생했는지 알려 줍니다.

오류: `The Jira user is not a site or organization administrator`#

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 사용자 요구 사항을 참고합니다.

OAuth 범위 제약 때문에 GitLab은 Jira 권한 API로 관리자 상태를 직접 확인할 수 없습니다. 자세한 배경은 이슈 #420687과 머지 리퀘스트 !135771을 참고합니다.

오류: `Failed to link group`#

그룹을 연결할 때 다음 오류가 발생할 수 있습니다.

Failed to link group. Please try again.

이 오류는 여러 원인으로 반환될 수 있습니다.

권한이 부족해 Jira에서 사용자 정보를 가져오지 못하면 403 Forbidden 이 반환될 수 있습니다. 이 문제를 해결하려면 앱을 설치하고 구성하는 Jira 사용자가 특정 요구 사항을 충족하는지 확인합니다.
리버스 프록시에서 rewrite 또는 sub_filter 지시문을 사용할 때도 이 오류가 발생할 수 있습니다. 요청에 사용되는 앱 키에는 서버 호스트 이름의 일부가 포함되는데, 일부 리버스 프록시 필터가 이를 가로챌 수 있습니다. 인증이 올바르게 동작하려면 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.

이 문제를 해결하는 방법은 다음과 같습니다.

/-/jira_connect/oauth_application_id가 공개적으로 접근 가능하고 JSON 응답을 반환하는지 확인합니다.
```
curl --include "https://gitlab.example.com/-/jira_connect/oauth_application_id"
```
공식 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

이 문제를 해결하려면 설치 방식에 필요한 사전 요구 사항이 모두 충족되었는지 확인합니다.

오류: `Failed to sign in to GitLab`#

앱이 GitLab Self-Managed 인스턴스를 가리키도록 설정한 뒤 GitLab for Jira Cloud 앱에 로그인할 때 다음 오류가 발생할 수 있습니다.

Failed to sign in to GitLab

이 문제를 해결하려면 앱용으로 만든 OAuth 애플리케이션에서 Trusted와 Confidential 체크박스가 해제되어 있는지 확인합니다. 오류가 계속되면 이슈 581765를 참고합니다.

Chrome 142 이상에서 차단되는 로컬 네트워크 요청#

GitLab Self-Managed 인스턴스가 로컬 또는 사설 네트워크에 있다면 Chrome 142 이상은 Local Network Access 정책에 따라 Jira Cloud에서 오는 연결을 차단합니다. Chrome은 이를 Failed to sign in to GitLab 메시지로 표시하거나 개발자 콘솔에 ERR_BLOCKED_BY_PRIVATE_NETWORK_ACCESS_CHECKS로 표시합니다.

Jira Cloud의 상위 iframe 이 권한을 부여해야 하므로 GitLab 측에서는 이 제약을 우회할 수 없습니다. 제약이 해소될 때까지 앱을 계속 사용하려면 다음 우회 방법 중 하나를 사용합니다.

Local Network Access를 적용하지 않는 Firefox 나 Safari에서 로그인합니다.
프롬프트를 건너뛰도록 관리자에게 *.atlassian.net에 대해 Chrome 엔터프라이즈 정책 LocalNetworkAllowedForUrls 를 배포해 달라고 요청합니다.

추적 내용은 이슈 581765를 참고합니다.

GitLab for Jira Cloud 앱 관리 문제 해결

GitLab v19.5

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

원문 보기

번역일: 2026-09-18

요약

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

사용자 대상 문제 해결은 GitLab for Jira Cloud 앱을 참고합니다.

이미 로그인한 상태에서 표시되는 로그인 메시지#

이미 GitLab.com에 로그인한 상태인데도 다음과 같이 로그인을 요구하는 메시지가 표시될 수 있습니다.

Sign in or sign up before continuing.

이 문제를 해결하려면 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 설정을 끄는 방법은 다음과 같습니다.

오른쪽 위 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > General을 선택합니다.
GitLab for Jira App을 확장합니다.
Jira Connect Proxy URL 텍스트 상자를 비웁니다.
Save changes를 선택합니다.

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

GitLab for Jira Cloud 앱의 설치 변경 내역 검토#

GitLab for Jira Cloud 앱의 설치 변경 내역을 검토하는 방법은 여러 가지가 있습니다. 자세한 내용은 공식 Jira 문서를 참고합니다.

`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에서 Apps 옆의 가로 줄임표([ellipsis_h])를 선택한 다음 Manage your apps를 선택합니다.
2. 다음 방법 중 하나로 앱으로 이동합니다.
  
  중앙 집중식 앱 관리를 사용하는 인스턴스:
  1. "App management has moved to Administration" 이 보이면 Take me there를 선택합니다. 그렇지 않으면 아래의 레거시 앱 관리를 사용하는 인스턴스 안내를 따릅니다.
  2. Installed apps 탭에서 GitLab for Jira (gitlab.com) 앱을 찾아 가로 줄임표([ellipsis_h])를 선택한 다음 Get started를 선택합니다.
  레거시 앱 관리를 사용하는 인스턴스:
  1. GitLab for Jira (gitlab.com) 앱을 찾아 갈매기표([chevron-right])를 선택한 다음 Get started를 선택합니다.
3. Change GitLab version을 선택합니다.
4. **GitLab.com (SaaS)**를 선택한 다음 Save를 선택합니다.
5. 다시 Change GitLab version을 선택합니다.
6. **GitLab (self-managed)**를 선택한 다음 Next를 선택합니다.
7. 모든 체크박스를 선택한 다음 Next를 선택합니다.
8. GitLab instance URL을 입력한 다음 Save를 선택합니다.
이 방법으로 해결되지 않고 Premium 또는 Ultimate 고객이라면 지원 티켓을 제출합니다. GitLab 인스턴스 URL과 Jira URL을 함께 제공합니다. GitLab 지원팀은 문제 해결을 위해 다음 스크립트를 실행할 수 있습니다.
```
# Check if GitLab.com can connect to the GitLab 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 GitLab Self-Managed instance
installation = JiraConnectInstallation.find_by_instance_url("https://gitlab.example.com")

# Try to send the token again from GitLab.com to the GitLab Self-Managed instance
ProxyLifecycleEventService.execute(installation, :installed, installation.instance_url)
```
앱을 수동으로 설치한 경우는 다음과 같습니다.
- Jira Cloud 지원팀에 Jira가 인스턴스에 연결할 수 있는지 확인을 요청합니다.
- 앱을 다시 설치합니다. 이 방법은 Jira 개발 패널에서 동기화된 데이터를 모두 제거할 수 있습니다.

오류: `Failed to update the GitLab instance`#

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

이 문제를 해결하려면 설치 방식에 필요한 사전 요구 사항이 모두 충족되었는지 확인합니다.

Jira Connect Proxy URL을 구성했고 사전 요구 사항을 확인한 뒤에도 문제가 계속된다면 Jira Connect Proxy 문제 디버깅을 참고합니다.

오류: `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 응답 헤더.
선택 사항. 문제를 포착한 HAR 파일을 harcleaner로 처리한 결과.

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

GitLab 지원팀#

Note

이 단계는 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>로 필터링합니다. 로그 항목 두 개가 반환됩니다.
고객의 GitLab Self-Managed URL 이 있다면 다음과 같이 진행합니다.
1. Kibana 로그를 json.meta.caller_id: JiraConnect::InstallationsController#update, NOT json.status: 200, json.params.value: {"instance_url"=>"https://gitlab.example.com"}로 필터링합니다. GitLab Self-Managed 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 토큰을 복호화하지 못하고 있습니다. 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", // The host should match the reverse proxy FQDN entered into the GitLab for Jira Cloud app
  "remote_ip":"34.74.226.3", // This IP should be within the GitLab.com IP range 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 Self-Managed 인스턴스의 통합 허용 목록이 GitLab for Jira Cloud 앱을 허용하는지 확인합니다.
시나리오 2:
- json.exception.class와 json.exception.message가 있습니다.
- json.exception.class와 json.exception.message는 GitLab Self-Managed 인스턴스에 접속하는 과정에서 문제가 발생했는지 알려 줍니다.

오류: `The Jira user is not a site or organization administrator`#

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 사용자를 org-admins 또는 site-admins 그룹에 추가합니다.

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

Jira 사용자 요구 사항에 관한 자세한 내용은 Jira 사용자 요구 사항을 참고합니다.

OAuth 범위 제약 때문에 GitLab은 Jira 권한 API로 관리자 상태를 직접 확인할 수 없습니다. 자세한 배경은 이슈 #420687과 머지 리퀘스트 !135771을 참고합니다.

오류: `Failed to link group`#

그룹을 연결할 때 다음 오류가 발생할 수 있습니다.

Failed to link group. Please try again.

이 오류는 여러 원인으로 반환될 수 있습니다.

권한이 부족해 Jira에서 사용자 정보를 가져오지 못하면 403 Forbidden 이 반환될 수 있습니다. 이 문제를 해결하려면 앱을 설치하고 구성하는 Jira 사용자가 특정 요구 사항을 충족하는지 확인합니다.
리버스 프록시에서 rewrite 또는 sub_filter 지시문을 사용할 때도 이 오류가 발생할 수 있습니다. 요청에 사용되는 앱 키에는 서버 호스트 이름의 일부가 포함되는데, 일부 리버스 프록시 필터가 이를 가로챌 수 있습니다. 인증이 올바르게 동작하려면 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.

이 문제를 해결하는 방법은 다음과 같습니다.

/-/jira_connect/oauth_application_id가 공개적으로 접근 가능하고 JSON 응답을 반환하는지 확인합니다.
```
curl --include "https://gitlab.example.com/-/jira_connect/oauth_application_id"
```
공식 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

이 문제를 해결하려면 설치 방식에 필요한 사전 요구 사항이 모두 충족되었는지 확인합니다.

오류: `Failed to sign in to GitLab`#

앱이 GitLab Self-Managed 인스턴스를 가리키도록 설정한 뒤 GitLab for Jira Cloud 앱에 로그인할 때 다음 오류가 발생할 수 있습니다.

Failed to sign in to GitLab

Chrome 142 이상에서 차단되는 로컬 네트워크 요청#

Local Network Access를 적용하지 않는 Firefox 나 Safari에서 로그인합니다.
프롬프트를 건너뛰도록 관리자에게 *.atlassian.net에 대해 Chrome 엔터프라이즈 정책 LocalNetworkAllowedForUrls 를 배포해 달라고 요청합니다.

추적 내용은 이슈 581765를 참고합니다.

GitLab for Jira Cloud 앱 관리 문제 해결

이미 로그인한 상태에서 표시되는 로그인 메시지#

수동 설치 실패#

GitLab for Jira Cloud 앱의 설치 변경 내역 검토#

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

오류: Failed to update the GitLab instance#

오류: Invalid audience#

Jira Connect Proxy 문제 디버깅#

GitLab 지원팀#

오류: The Jira user is not a site or organization administrator#

오류: Failed to link group#

오류: Failed to load Jira Connect Application ID#

오류: Missing required parameter: client_id#

오류: Failed to sign in to GitLab#

Chrome 142 이상에서 차단되는 로컬 네트워크 요청#

GitLab for Jira Cloud 앱 관리 문제 해결

이미 로그인한 상태에서 표시되는 로그인 메시지#

수동 설치 실패#

GitLab for Jira Cloud 앱의 설치 변경 내역 검토#

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

오류: Failed to update the GitLab instance#

오류: Invalid audience#

Jira Connect Proxy 문제 디버깅#

GitLab 지원팀#

오류: The Jira user is not a site or organization administrator#

오류: Failed to link group#

오류: Failed to load Jira Connect Application ID#

오류: Missing required parameter: client_id#

오류: Failed to sign in to GitLab#

Chrome 142 이상에서 차단되는 로컬 네트워크 요청#

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

오류: `Failed to update the GitLab instance`#

오류: `Invalid audience`#

오류: `The Jira user is not a site or organization administrator`#

오류: `Failed to link group`#

오류: `Failed to load Jira Connect Application ID`#

오류: `Missing required parameter: client_id`#

오류: `Failed to sign in to GitLab`#

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

오류: `Failed to update the GitLab instance`#

오류: `Invalid audience`#

오류: `The Jira user is not a site or organization administrator`#

오류: `Failed to link group`#

오류: `Failed to load Jira Connect Application ID`#

오류: `Missing required parameter: client_id`#

오류: `Failed to sign in to GitLab`#