Jira 이슈 통합의 문제 해결

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

Jira 이슈 통합을 사용할 때, 다음과 같은 문제가 발생할 수 있습니다.

GitLab이 Jira 이슈에 링크를 걸 수 없음

GitLab에서 Jira 이슈 ID를 언급해도 이슈 링크가 누락될 수 있습니다. sidekiq.log에 다음과 같은 예외가 포함될 수 있습니다: 

No Link Issue Permission for issue 'JIRA-1234'

이 문제를 해결하려면, Jira 이슈 통합을 위해 생성한 Jira 사용자가 이슈를 링크할 권한을 가지고 있는지 확인하세요.

GitLab이 Jira 이슈에 코멘트를 달 수 없음

GitLab이 Jira 이슈에 코멘트를 남길 수 없는 경우, Jira 이슈 통합을 위해 생성한 Jira 사용자가 다음 권한을 가지고 있는지 확인하세요:

  • Jira 이슈에 코멘트를 작성할 수 있는지 확인하세요.
  • Jira 이슈를 전환할 수 있는지 확인하세요.

GitLab 이슈 트래커가 비활성화된 경우, Jira 이슈 참조 및 코멘트가 작동하지 않습니다. 만약 Jira 액세스를 위해 IP 주소를 제한했다면, 자체 호스팅된 IP 주소나 GitLab IP 주소를 Jira의 허용 목록에 추가해야 합니다.

원인을 확인하려면, integrations_json.log 파일을 확인하세요. GitLab이 Jira 이슈에 코멘트를 남기려고 할 때, Error sending message 로그 항목이 나타날 수 있습니다.

GitLab 16.1 이상에서 오류가 발생한 경우, integrations_json.log 파일에 나가는 Jira로의 API 요청에 client_* 키가 포함됩니다. 이 client_* 키를 사용하여 발생한 오류에 대한 원인을 확인할 수 있습니다. 자세한 내용은 Atlassian API 문서를 확인하세요.

다음 예제에서는 Jira가 404 Not Found로 응답합니다. 이 오류는 다음과 같은 경우 발생할 수 있습니다:

  • Jira 이슈 통합을 위해 생성한 Jira 사용자가 이슈를 보기 위한 권한이 없는 경우
  • 지정한 Jira 이슈 ID가 존재하지 않는 경우 
{
  "severity": "ERROR",
  "time": "2023-07-25T21:38:56.510Z",
  "message": "Error sending message",
  "client_url": "https://my-jira-cloud.atlassian.net",
  "client_path": "/rest/api/2/issue/ALPHA-1",
  "client_status": "404",
  "exception.class": "JIRA::HTTPError",
  "exception.message": "Not Found",
}

반환된 상태 코드에 대한 자세한 내용은 Jira Cloud 플랫폼 REST API 문서를 확인하세요.

curl을 사용하여 Jira 이슈에 대한 액세스 검증

특정 Jira 사용자가 특정 Jira 이슈에 액세스할 수 있는지 확인하려면, 다음 스크립트를 실행하세요: 

curl --verbose --user "$USER:$API_TOKEN" "https://$ATLASSIAN_SUBDOMAIN.atlassian.net/rest/api/2/issue/$JIRA_ISSUE"

사용자가 이 문제에 접근할 수 있는 경우, Jira는 200 OK로 응답하고 반환된 JSON에 Jira 이슈 세부 정보가 포함됩니다.

GitLab이 Jira 이슈에 코멘트를 올릴 수 있는지 확인

경고: 데이터를 변경하는 명령은 올바르게 실행되지 않거나 올바른 조건에서 실행되지 않으면 손상을 일으킬 수 있습니다. 명령어를 먼저 테스트 환경에서 실행하고 복구할 대비용 인스턴스를 준비하세요.

Jira 통합을 문제 해결하기 위해, 프로젝트의 Jira 통합 설정을 사용하여 GitLab이 Jira 이슈에 코멘트를 올릴 수 있는지 확인할 수 있습니다.

다음과 같이 진행하세요:

  • Rails 콘솔에서 다음을 실행하세요: 

    jira_issue_id = "ALPHA-1" # 사용자의 Jira 이슈 ID로 변경
project = Project.find_by_full_path("group/project") # 프로젝트 경로로 변경

integration = project.integrations.find_by(type: "Integrations::Jira")
jira_issue = integration.client.Issue.find(jira_issue_id)
jira_issue.comments.build.save!(body: 'This is a test comment from GitLab via the Rails console')

명령이 성공하면, Jira 이슈에 코멘트가 추가됩니다.

GitLab이 Jira 이슈를 생성할 수 없음

취약점에서 Jira 이슈를 생성하려고 하면, “field is required” 오류가 발생할 수 있습니다. 예를 들어, Components is required라는 오류가 발생하는 경우, GitLab이 전달하지 않은 필드인 “Components가 필요합니다”. 이 문제를 해결하려면 다음을 수행하세요:

  1. Jira 인스턴스에서 새로운 “Vulnerability” 이슈 유형을 생성하세요.
  2. 새로운 이슈 유형을 프로젝트에 할당하세요.
  3. 프로젝트의 모든 “Vulnerabilities”에 대한 필드 계획을 변경하여 누락된 필드를 필수로 하지 않도록 설정하세요.

GitLab이 Jira 이슈를 닫을 수 없음

GitLab이 Jira 이슈를 닫지 못하는 경우:

  • Jira 설정에 설정한 전환 ID가 이슈를 닫기 위해 프로젝트가 가져야 하는 ID와 일치하는지 확인하세요. 자세한 내용은 자동 이슈 전환 및 사용자 정의 이슈 전환을 확인하세요.
  • Jira 이슈가 이미 해결된 것이 아닌지 확인하세요:
    • Jira 이슈 해결 필드가 설정되어 있지 않은지 확인하세요.
    • 이슈가 Jira 목록에서 취소선이 그어져 있는지 확인하세요.

로그인 시도 후 CAPTCHA

연속적인 로그인 실패 후에는 CAPTCHA가 트리거될 수 있습니다. 이러한 실패한 시도로 인해 Jira 이슈 통합 설정을 테스트할 때 401 Unauthorized가 발생할 수 있습니다. CAPTCHA가 트리거된 경우, Jira REST API를 사용하여 Jira 사이트와 인증할 수 없습니다.

이 문제를 해결하려면, Jira 인스턴스에 로그인하여 CAPTCHA를 완료하세요.

통합된 프로젝트에서 가져온 프로젝트의 통합이 작동하지 않음

가져온 프로젝트에서는 Jira 이슈 통합이 작동하지 않을 수 있습니다. 자세한 내용은 이슈 341571를 참조하십시오.

이 문제를 해결하려면 통합을 비활성화한 다음 통합을 다시 활성화하십시오.

오류: certificate verify failed

Jira 이슈 통합 설정을 테스트할 때 다음 오류가 발생할 수 있습니다. 

Connection failed. Check your integration settings. SSL_connect returned=1 errno=0 peeraddr=<jira.example.com> state=error: certificate verify failed (unable to get local issuer certificate)

이 오류는 또한 integrations_json.log 파일에도 나타날 수 있습니다. 

{
  "severity":"ERROR",
  "integration_class":"Integrations::Jira",
  "message":"Error sending message",
  "exception.class":"OpenSSL::SSL::SSLError",
  "exception.message":"SSL_connect returned=1 errno=0 peeraddr=x.x.x.x:443 state=error: certificate verify failed (unable to get local issuer certificate)"
}

이 오류는 Jira 인증서가 공개적으로 신뢰되지 않거나 인증서 체인이 불완전하기 때문에 발생합니다. 이 문제가 해결될 때까지 GitLab은 Jira에 연결되지 않습니다.

이 문제를 해결하려면 공통 SSL 오류를 참조하십시오.

모든 Jira 프로젝트를 인스턴스 수준 또는 그룹 수준 값으로 변경

경고: 데이터를 변경하는 명령은 올바르게 실행되지 않거나 올바른 조건하에서 실행되지 않는 경우에 피해를 줄 수 있습니다. 항상 먼저 테스트 환경에서 명령을 실행하고 복원할 수 있는 백업 인스턴스를 준비하십시오.

인스턴스에서 모든 프로젝트 변경

모든 Jira 프로젝트를 인스턴스 수준 통합 설정을 사용하도록 변경하려면 다음을 수행하십시오:

  1. 레일즈 콘솔에서 다음을 실행하십시오: 

    Integrations::Jira.where(active: true, instance: false, inherit_from_id: nil).find_each do |integration|
  default_integration = Integration.default_integration(integration.type, integration.project)

  integration.inherit_from_id = default_integration.id

  if integration.save(context: :manual_change)
    if Gitlab.version_info >= Gitlab::VersionInfo.new(16, 9)
      Integrations::Propagation::BulkUpdateService.new(default_integration, [integration]).execute
    else
      BulkUpdateIntegrationService.new(default_integration, [integration]).execute
    end
  end
end

  2. UI에서 인스턴스 수준 통합을 수정하고 저장하여 변경 사항을 모든 그룹 수준 및 프로젝트 수준 통합에 전파하십시오.

그룹 내 모든 프로젝트 변경

그룹(및 해당 하위 그룹)의 모든 Jira 프로젝트를 그룹 수준 통합 설정을 사용하도록 변경하려면 다음을 실행하십시오:

  • 레일즈 콘솔에서 다음을 실행하십시오: 

    def reset_integration(target)
  integration = target.integrations.find_by(type: Integrations::Jira)

  return if integration.nil? # Jira 이슈 통합이 없는 경우 건너뜁니다.
  return unless integration.inherit_from_id.nil? # 이미 상속되고 있는 통합들을 건너뜁니다.

  default_integration = Integration.default_integration(integration.type, target)

  integration.inherit_from_id = default_integration.id

  if integration.save(context: :manual_change)
    if Gitlab.version_info >= Gitlab::VersionInfo.new(16, 9)
      Integrations::Propagation::BulkUpdateService.new(default_integration, [integration]).execute
    else
      BulkUpdateIntegrationService.new(default_integration, [integration]).execute
    end
  end
end

parent_group = Group.find_by_full_path('top-level-group') # 최상위 그룹의 전체 경로를 추가하십시오
current_user = User.find_by_username('admin-user') # 관리자 액세스 권한이 있는 사용자의 사용자 이름을 추가하십시오

unless parent_group.nil?
  groups = GroupsFinder.new(current_user, { parent: parent_group, include_parent_descendants: true }).execute

  # 하위 그룹에서 프로젝트를 재설정하여 상위 그룹 통합 설정을 사용하도록 변경합니다.
  groups.find_each do |group|
    reset_integration(group)

    group.projects.find_each do |project|
      reset_integration(project)
    end
  end

  # 상위 그룹의 직접 프로젝트를 사용하도록 변경합니다.
  parent_group.projects.find_each do |project|
    reset_integration(project)
  end
end

모든 프로젝트의 통합 암호를 업데이트

경고: 데이터를 변경하는 명령은 올바르게 실행되지 않거나 올바른 조건하에서 실행되지 않는 경우에 피해를 줄 수 있습니다. 항상 먼저 테스트 환경에서 명령을 실행하고 복원할 수 있는 백업 인스턴스를 준비하십시오.

모든 활성 Jira 통합이 있는 프로젝트의 Jira 사용자 암호를 재설정하려면, 레일즈 콘솔에서 다음을 실행하십시오: 

p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN integrations i ON p.id = i.project_id WHERE i.type_new = 'Integrations::Jira' AND i.active = true")

p.each do |project|
  project.jira_integration.update_attribute(:password, '<your-new-password>')
end

Jira 이슈 목록

GitLab에서 Jira 이슈를 보는 중 다음과 같은 문제가 발생할 수 있습니다.

오류: 500 We're sorry

GitLab에서 Jira 이슈에 액세스할 때 500 We're sorry. Something went wrong on our end 오류가 발생할 수 있습니다. 파일에 다음 예외가 포함되어 있는지 production.log를 확인하십시오. 

:NoMethodError (undefined method 'duedate' for #<JIRA::Resource::Issue:0x00007f406d7b3180>)

이러한 경우 통합된 Jira 프로젝트에서 Due date 필드가 표시되도록 확인하십시오.

오류: An error occurred while requesting data from Jira

GitLab에서 Jira 이슈 목록을 보거나 Jira 이슈를 생성하려고 하면 다음과 같은 오류가 발생할 수 있습니다: 

An error occurred while requesting data from Jira

An error occurred while fetching issue list. Connection failed. Check your integration settings.

이러한 오류는 Jira 이슈 통합의 인증이 완료되거나 올바르지 않을 때 발생합니다.

이 문제를 해결하려면 Jira 이슈 통합을 다시 구성하십시오. 인증 세부 정보가 올바른지 확인하고 API 토큰 또는 암호를 다시 입력한 후 변경 사항을 저장하십시오.

프로젝트 키에 예약된 JQL 단어가 포함되어 있으면 Jira 이슈 목록이 로드되지 않습니다. 자세한 내용은 이슈 426176을 참조하십시오. 귀하의 Jira 프로젝트 키에는 제한된 단어 및 문자가 포함되어서는 안 됩니다.

Jira 자격 증명 오류

GitLab에서 Jira 이슈 목록을 보려고 시도할 때 다음과 같은 오류 메시지가 표시될 수 있습니다.

오류: The value '<project>' does not exist for the field 'project'

Jira 설치에 잘못된 인증 자격 증명을 사용하면 다음 오류가 표시될 수 있습니다: 

Jira에서 데이터를 요청하는 중 오류가 발생했습니다:
The value '<project>' does not exist for the field 'project'.
Jira 통합 구성을 확인하고 다시 시도하세요.

인증 자격 증명은 Jira 설치 유형에 따라 다릅니다:

  • Jira Cloud의 경우, Jira Cloud API 토큰과 해당 토큰을 생성한 이메일 주소가 필요합니다.
  • Jira Data Center 또는 Jira Server의 경우, Jira 사용자 이름과 암호, 또는 GitLab 16.0 이상의 경우 Jira 개인 액세스 토큰이 필요합니다.

자세한 내용은 Jira 이슈 통합을 참조하세요.

이 문제를 해결하려면 Jira 설치에 맞는 인증 자격 증명을 업데이트하세요.

오류: The credentials for accessing Jira are not allowed to access the data

만약 Jira 자격 증명이 Jira 이슈 통합에서 지정한 Jira 프로젝트 키에 액세스할 수 없다면, 다음과 같은 오류가 표시될 수 있습니다: 

Jira에 액세스할 수 있는 자격 증명이 데이터에 액세스할 수 없습니다.
Jira 통합 자격 증명을 확인하고 다시 시도하세요.

이 문제를 해결하려면 Jira 이슈 통합에서 구성한 Jira 사용자가 지정한 Jira 프로젝트 키와 관련된 이슈를 볼 권한이 있는지 확인하세요.

Jira 사용자에게 이 권한이 있는지 확인하려면 다음 중 하나를 수행하세요:

  • 브라우저에서 Jira에 Jira 이슈 통합에서 구성한 사용자로 로그인하세요. Jira API가 쿠키 기반 인증을 지원하므로 브라우저에서 이슈가 반환되는지 확인할 수 있습니다: 

    https://<ATLASSIAN_SUBDOMAIN>.atlassian.net/rest/api/2/search?jql=project=<JIRA PROJECT KEY>

  • HTTP 기본 인증을 사용하여 API에 액세스하고 이슈가 반환되는지 확인하기 위해 curl을 사용하세요: 

    curl --verbose --user "$USER:$API_TOKEN" "https://$ATLASSIAN_SUBDOMAIN.atlassian.net/rest/api/2/search?jql=project=$JIRA_PROJECT_KEY" | jq

양쪽 방법 모두 JSON 응답을 반환해야 합니다:

  • total은 Jira 프로젝트 키와 일치하는 이슈의 수를 제공합니다.
  • issues는 Jira 프로젝트 키와 일치하는 이슈의 배열을 포함합니다.

반환된 상태 코드에 대한 자세한 정보는 Jira Cloud 플랫폼 REST API 문서를 참조하세요.