서비스 데스크 구성

세부정보:
Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed

기본적으로 서비스 데스크는 새로운 프로젝트에서 활성화됩니다.
활성이 아니면 프로젝트의 설정에서 할 수 있습니다.

사전 요구 사항:

프로젝트에서 서비스 데스크를 활성화하려면:

  1. 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
  2. Settings > General을 선택합니다.
  3. Service Desk를 확장합니다.
  4. Activate Service Desk 토글을 켭니다.
  5. 선택 사항. 필드를 완료합니다.
    • 서비스 데스크 이메일 주소에 접미사를 추가합니다.
    • 아래의 모든 서비스 데스크 이슈에 추가할 템플릿 목록이 비어 있으면,
      리포지토리에서 설명 템플릿을 만듭니다.
  6. Save changes를 선택합니다.

이제 이 프로젝트에 대해 서비스 데스크가 활성화되었습니다.
아래의 서비스 데스크에 사용할 이메일 주소로 이메일을 보내면,
GitLab은 이메일의 내용으로 기밀 이슈를 생성합니다.

서비스 데스크 용어집

이 용어집은 서비스 데스크와 관련된 용어에 대한 정의를 제공합니다.

용어 정의
외부 참여자 GitLab 계정 없이 이메일로만 이슈 또는 서비스 데스크 티켓과 상호작용할 수 있는 사용자입니다.
요청자 서비스 데스크 티켓을 생성했거나 /convert_to_ticket 빠른 작업을 사용하여 요청자로 추가된 외부 참여자입니다.

프로젝트 보안 개선

서비스 데스크 프로젝트의 보안을 개선하기 위해 다음을 권장합니다:

  • 서비스 데스크 이메일 주소를 이메일 시스템의 별칭 뒤에 두어 나중에 변경할 수 있도록 합니다.
  • GitLab 인스턴스에서 Akismet를 활성화하여 이 서비스에 스팸 검사를 추가합니다.
    차단되지 않은 이메일 스팸은 많은 스팸 이슈가 생성될 수 있습니다.

외부 참여자에게 보내는 이메일 사용자 정의

  • UNSUBSCRIBE_URL, SYSTEM_HEADER, SYSTEM_FOOTER, 그리고 ADDITIONAL_TEXT 자리 표시자가 GitLab 15.9에서 도입됨.
  • %{ISSUE_DESCRIPTION} 자리 표시자가 GitLab 16.0에서 도입됨.
  • %{ISSUE_URL} 자리 표시자가 GitLab 16.1에서 도입됨.

요청자가 서비스 데스크에 이메일로 새로운 티켓를 제출할 때,

  • 외부 참여자가 서비스 데스크 티켓에 추가될 때,
  • 서비스 데스크 티켓에 새로운 공개 댓글이 추가될 때,
    • 댓글을 편집해도 새로운 이메일이 발송되지 않습니다.

이러한 이메일 메시지의 본문을 서비스 데스크 이메일 템플릿으로 사용자 정의할 수 있습니다. 템플릿은
GitLab Flavored Markdown일부 HTML 태그를 포함할 수 있습니다.
예를 들어, 귀하의 조직 브랜드 가이드라인에 따라 이메일에 헤더와 푸터를 포함하도록 이메일 형식을 지정할 수 있습니다.
또한 서비스 데스크 티켓 또는 GitLab 인스턴스에 특정한 동적 콘텐츠를 표시하기 위해 다음 자리 표시자를 포함할 수 있습니다.

자리 표시자 thank_you.mdnew_participant new_note.md 설명
%{ISSUE_ID} 티켓 IID.
%{ISSUE_PATH} 티켓 IID가 추가된 프로젝트 경로.
%{ISSUE_URL} 티켓의 URL. 외부 참여자는 프로젝트가 공개적이고 티켓이 기밀이 아닌 경우에만 티켓을 볼 수 있습니다(서비스 데스크 티켓은 기본적으로 기밀입니다).
%{ISSUE_DESCRIPTION} 티켓 설명. 사용자가 설명을 편집한 경우, 외부 참여자에게 전달할 의도가 아닌 민감한 정보가 포함될 수 있습니다. 이 자리 표시자는 주의하여 사용해야 하며, 이상적으로는 설명을 수정하지 않는 경우에만 사용해야 하며, 팀이 템플릿 디자인을 알고 있어야 합니다.
%{UNSUBSCRIBE_URL} 구독 해지 URL.
%{NOTE_TEXT} 아니오 사용자에 의해 티켓에 추가된 새로운 댓글. 이 자리 표시자를 new_note.md에 포함하도록 주의해야 합니다. 그렇지 않으면 외부 참여자는 서비스 데스크 티켓에서 업데이트를 절대 볼 수 없습니다.

감사합니다 이메일

요청자가 서비스 데스크를 통해 문제를 제출하면 GitLab은 감사합니다 이메일을 보냅니다.

추가 구성 없이 GitLab은 기본 감사 이메일을 보냅니다.

사용자 정의 감사 이메일 템플릿을 만들려면:

  1. 리포지토리의 .gitlab/service_desk_templates/ 디렉터리에 thank_you.md라는 파일을 만듭니다.

  2. Markdown 파일에 텍스트, GitLab Flavored Markdown,
    일부 선택된 HTML 태그 및 자리 표시자를 채워
    서비스 데스크 요청자에게 회신을 사용자 지정합니다.

새로운 참여자 이메일

  • new_participant 이메일은 GitLab 17.0에서 소개됨.

외부 참여자가 티켓에 추가되면 GitLab은 새로운 참여자 이메일을 보내어 그들이 대화의 일원임을 알립니다.

추가 구성 없이 GitLab은 기본 새로운 참여자 이메일을 보냅니다.

사용자 정의 새로운 참여자 이메일 템플릿을 만들려면:

  1. 리포지토리의 .gitlab/service_desk_templates/ 디렉터리에 new_participant.md라는 파일을 만듭니다.

  2. Markdown 파일에 텍스트, GitLab Flavored Markdown,
    일부 선택된 HTML 태그 및 자리 표시자를 채워
    서비스 데스크 요청자에게 회신을 사용자 지정합니다.

새로운 노트 이메일

서비스 데스크 티켓에 새로운 공개 댓글이 있을 때 GitLab은 새로운 노트 이메일을 보냅니다.

추가 구성 없이 GitLab은 댓글의 내용을 보냅니다.

브랜드에 맞게 이메일을 유지하려면 사용자 정의 새로운 노트 이메일 템플릿을 만들 수 있습니다. 이렇게 하려면:

  1. 리포지토리의 .gitlab/service_desk_templates/ 디렉터리에 new_note.md라는 파일을 만듭니다.

  2. Markdown 파일에 텍스트, GitLab Flavored Markdown,
    일부 선택된 HTML 태그 및 자리 표시자를 채워
    새로운 노트 이메일을 사용자 지정합니다. 템플릿에 %{NOTE_TEXT}를 포함하여 이메일 수신자가
    댓글의 내용을 읽을 수 있도록 하세요.

인스턴스 전역 이메일 헤더, 바닥글 및 추가 텍스트

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

인스턴스 관리자는 GitLab 인스턴스에 헤더, 바닥글 또는 추가 텍스트를 추가하고 이를
GitLab에서 전송하는 모든 이메일에 적용할 수 있습니다. 사용자 정의 thank_you.md, new_participant 또는 new_note.md을 사용하는 경우,
이 콘텐츠를 포함하려면 템플릿에 %{SYSTEM_HEADER}, %{SYSTEM_FOOTER} 또는 %{ADDITIONAL_TEXT}를 추가하세요.

자세한 내용은 시스템 헤더 및 바닥글 메시지
사용자 정의 추가 텍스트를 참조하세요.

서비스 데스크 티켓에 사용자 정의 템플릿 사용

프로젝트마다 하나의 설명 템플릿을 선택하여
모든 새로운 서비스 데스크 티켓의 설명에 추가할 수 있습니다.

다양한 수준에서 설명 템플릿을 설정할 수 있습니다:

템플릿은 상속됩니다. 예를 들어, 프로젝트에서는 인스턴스 또는 프로젝트의 상위 그룹에 설정된 템플릿에 접근할 수 있습니다.

사전 요구 사항:

서비스 데스크와 함께 사용자 정의 설명 템플릿을 사용하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동하여 프로젝트를 찾습니다.

  2. 설정 > 일반을 선택합니다.

  3. 서비스 데스크를 확장합니다.

  4. 드롭다운 목록 모든 서비스 데스크 이슈에 추가할 템플릿에서 템플릿을 검색하거나 선택합니다.

지원 봇 사용자

백그라운드에서 서비스 데스크는 특별한 지원 봇 사용자가 문제를 생성하여 작동합니다.

이 사용자는 청구 가능한 사용자가 아니므로 라이센스 제한 카운트에 포함되지 않습니다.

GitLab 16.0 및 이전 버전에서는 서비스 데스크 이메일에서 생성된 댓글이 작성자로 GitLab Support Bot을 표시합니다. GitLab 16.1 및 이후 버전에서는 이러한 댓글이 이메일을 보낸 사용자의 이메일을 표시합니다. 이 기능은 GitLab 16.1 및 이후에 작성된 댓글에만 적용됩니다.

지원 봇의 표시 이름 변경

지원 봇 사용자의 표시 이름을 변경할 수 있습니다. 서비스 데스크에서 발송된 이메일의 From 헤더에는 이 이름이 포함됩니다. 기본 표시 이름은 GitLab Support Bot입니다.

사용자 정의 이메일 표시 이름을 편집하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.

  2. 설정 > 일반을 선택합니다.

  3. 서비스 데스크를 확장합니다.

  4. 이메일 표시 이름 아래에 새 이름을 입력합니다.

  5. 변경 사항 저장을 선택합니다.

기본 티켓 가시성

새 티켓은 기본적으로 비밀이며, 최소한 리포터 역할을 가진 프로젝트 구성원만 볼 수 있습니다.

비공식 및 내부 프로젝트에서는 GitLab을 구성하여 새 티켓이 기본적으로 비밀이 아니도록 하여 모든 프로젝트 구성원이 볼 수 있도록 할 수 있습니다.

공개 프로젝트에서는 이 설정을 사용할 수 없으며, 새 티켓은 항상 기본적으로 비밀입니다.

선행 조건:

  • 프로젝트에 대해 최소한 유지 관리 역할이 있어야 합니다.

이 설정을 비활성화하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.

  2. 설정 > 일반을 선택합니다.

  3. 서비스 데스크를 확장합니다.

  4. 새 티켓은 기본적으로 비밀입니다 체크 박스를 비워 둡니다.

  5. 변경 사항 저장을 선택합니다.

외부 참가자가 댓글을 달 때 문제 다시 열기

새로운 댓글을 이메일로 추가하는 외부 참가자가 있을 때 GitLab을 구성하여 닫힌 문제를 다시 열 수 있습니다. 이렇게 하면 문제의 담당자를 언급하는 내부 댓글이 추가되고 그들을 위한 작업 항목이 생성됩니다.

사용법에 대한 짧은 시연 비디오를 참조하세요.

선행 조건:

  • 프로젝트에 대해 최소한 유지 관리 역할이 있어야 합니다.

이 설정을 활성화하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.

  2. 설정 > 일반을 선택합니다.

  3. 서비스 데스크를 확장합니다.

  4. 외부 참가자의 새 노트에서 문제 다시 열기 체크 박스를 선택합니다.

  5. 변경 사항 저장을 선택합니다.

사용자 정의 이메일 주소

상태: Beta

지원 커뮤니케이션의 발신자로 표시될 사용자 정의 이메일 주소를 구성하세요.
브랜드 아이덴티티를 유지하고 지원 요청자들에게 신뢰를 심어줄 수 있는 도메인을 통해.

개요는 짧은 시연 비디오를 참조하세요.

이 기능은 베타입니다.
베타 기능은 프로덕션 준비가 되어 있지 않지만, 릴리스되기 전에 급격히 변경될 가능성은 적습니다.
우리는 사용자들이 베타 기능을 사용해 보고 피드백 문제에 피드백을 제공할 것을 권장합니다.

필수 조건

프로젝트당 하나의 맞춤 이메일 주소를 Service Desk용으로 사용할 수 있으며, 인스턴스 전체에서 고유해야 합니다.

사용하려는 맞춤 이메일 주소는 다음 요구 사항을 모두 충족해야 합니다:

  • 이메일 포워딩을 설정할 수 있습니다.
  • 전달된 이메일은 원래 보낸 사람 헤더를 유지합니다.
  • 서비스 제공자가 서브 주소 지정(sub-addressing)을 지원해야 합니다. 이메일 주소는 로컬 부분(@ 이전의 모든 것)과 도메인 부분으로 구성됩니다.

    이메일 서브 주소 지정을 사용하면 로컬 부분에 + 기호와 텍스트를 추가하여 이메일 주소의 고유한 변형을 만들 수 있습니다. 예를 들어, support@example.com이라는 이메일 주소가 있을 때, support+1@example.com으로 이메일을 보내 서브 주소 지지가 지원되는지 확인합니다. 이 이메일은 귀하의 메일박스에 나타나야 합니다.

  • SMTP 자격 증명이 있어야 합니다(이상적으로는 앱 비밀번호를 사용하는 것이 좋습니다). 사용자 이름과 비밀번호는 256비트 키를 사용하는 고급 암호화 표준(AES)으로 데이터베이스에 저장됩니다.

  • SMTP 호스트는 귀하의 GitLab 인스턴스의 네트워크(자가 관리 GitLab) 또는 공용 인터넷(소프트웨어로 제공되는 GitLab)에서 해석 가능해야 합니다.

  • 프로젝트에 대해 최소한 유지 관리(Maintainer) 역할이 있어야 합니다.

  • 프로젝트에 대해 Service Desk가 구성되어 있어야 합니다.

맞춤 이메일 주소 구성

Service Desk 이메일을 사용자의 이메일 주소로 보내고자 할 때 맞춤 이메일 주소를 구성하고 확인하십시오.

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 일반을 선택합니다.
  3. Service Desk를 확장하고 맞춤 이메일 주소 구성 섹션을 찾습니다.
  4. 이 프로젝트의 Service Desk 주소를 기록하고, 귀하의 이메일 제공자(예: Gmail)에서 맞춤 이메일 주소에서 Service Desk 주소로 이메일 포워딩을 설정합니다.
  5. GitLab에서 필드를 완료합니다.
  6. 저장 및 연결 테스트를 선택합니다.

구성이 저장되었으며 맞춤 이메일 주소 확인이 시작됩니다.

확인

  1. 구성을 완료한 후, 모든 프로젝트 소유자와 맞춤 이메일 구성을 저장한 관리자가 알림 이메일을 받습니다.
  2. 제공된 SMTP 자격 증명을 사용하여 맞춤 이메일 주소(서브 주소 지정 부분 포함)로 확인 이메일이 전송됩니다. 이메일에는 확인 토큰이 포함되어 있습니다. 이메일 포워딩이 올바르게 설정되고 모든 필수 조건이 충족되면 이메일은 Service Desk 주소로 전달되어 GitLab에 의해 수신됩니다. GitLab은 다음 조건을 확인합니다:
    1. GitLab은 SMTP 자격 증명을 사용하여 이메일을 보낼 수 있습니다.
    2. 서브 주소 지정이 지원됩니다( +verify 서브 주소 지정 부분 포함).
    3. 포워딩 후 보낸 사람 헤더가 유지됩니다.
    4. 확인 토큰이 올바릅니다.
    5. 이메일이 30분 이내에 수신됩니다.

일반적으로 이 과정은 몇 분이면 끝납니다.

언제든지 확인을 취소하거나 실패한 경우 맞춤 이메일 재설정을 선택합니다. 설정 페이지는 이에 따라 업데이트되어 확인의 현재 상태를 반영합니다. SMTP 자격 증명은 삭제되며 구성을 다시 시작할 수 있습니다.

실패하거나 성공할 경우, 모든 프로젝트 소유자와 확인 프로세스를 트리거한 사용자에게 확인 결과가 담긴 알림 이메일이 전송됩니다. 확인이 실패한 경우, 이메일에는 실패 이유에 대한 세부 정보도 포함됩니다.

확인이 성공적으로 이루어지면 맞춤 이메일 주소를 사용할 준비가 된 것입니다. 이제 맞춤 이메일 주소를 통해 Service Desk 이메일을 전송하도록 설정할 수 있습니다.

구성 문제 해결

사용자 지정 이메일을 구성할 때 다음과 같은 문제에 직면할 수 있습니다.

잘못된 자격 증명

잘못된 자격 증명이 사용되었다는 오류가 발생할 수 있습니다.

이 문제는 SMTP 서버가 인증에 실패했다고 반환할 때 발생합니다.

이 문제를 해결하려면:

  1. SMTP 자격 증명을 확인하세요. 특히 사용자 이름과 비밀번호를 확인하세요.
  2. 때때로 GitLab은 SMTP 서버가 지원하는 인증 방법을 자동으로 선택할 수 없습니다. 다음 중 하나를 시도하세요:
    • 지원되는 인증 방법(Plain, LoginCRAM-MD5)를 시도하세요.
    • swaks 명령줄 도구를 사용하여 SMTP 서버가 지원하는 인증 방법을 확인하세요:

      1. 자격 증명을 사용하여 다음 명령을 실행하고 250-AUTH로 시작하는 줄을 찾으세요:

        swaks --to user@example.com \
              --from support@example.com \
              --auth-user support@example.com \
              --server smtp@example.com:587 \
              -tls-optional \
              --auth-password your-app-password
        
      2. 사용자 지정 이메일 설정 양식에서 지원되는 인증 방법 중 하나를 선택하세요.

잘못된 전달 대상

잘못된 전달 대상이 사용되었다는 오류가 발생할 수 있습니다.

이 문제는 확인 이메일이 사용자 지정 이메일 구성 양식에 표시된 프로젝트별 서비스 데스크 주소와 다른 이메일 주소로 전달되었을 때 발생합니다.

incoming_email에서 생성된 서비스 데스크 주소를 사용해야 합니다. service_desk_email에서 생성된 추가 서비스 데스크 별칭 주소로 전달하는 것은 모든 이메일 회신 기능을 지원하지 않기 때문에 지원되지 않습니다.

이 문제를 해결하려면:

  1. 이메일을 전달할 올바른 이메일 주소를 찾으세요. 다음 중 하나를 선택하세요:
    • 모든 프로젝트 소유자와 확인 프로세스를 트리거한 사용자가 수신하는 확인 결과 이메일에서 주소를 기록하세요.
    • 사용자 지정 이메일 설정 양식의 이메일을 전달할 서비스 데스크 이메일 주소 입력란에서 주소를 복사하세요.
  2. 모든 이메일을 사용자 지정 이메일 주소에서 올바른 대상 이메일 주소로 전달하세요.

사용자 지정 이메일 주소 활성화 또는 비활성화

사용자 지정 이메일 주소가 확인된 후, 관리자는 사용자 지정 이메일 주소를 통해 서비스 데스크 이메일을 보내는 기능을 활성화하거나 비활성화할 수 있습니다.

사용자 지정 이메일 주소 활성화:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요.
  2. 설정 > 일반을 선택하세요.
  3. 서비스 데스크를 확장하세요.
  4. 사용자 지정 이메일 활성화 토글을 켭니다.
    외부 참가자에게 보내는 서비스 데스크 이메일은 SMTP 자격 증명을 사용하여 전송됩니다.

사용자 지정 이메일 주소 비활성화:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요.
  2. 설정 > 일반을 선택하세요.
  3. 서비스 데스크를 확장하세요.
  4. 사용자 지정 이메일 활성화 토글을 끕니다.
    이메일 전달을 설정했기 때문에 사용자 지정 이메일 주소로의 이메일은 계속 처리되며 프로젝트에 서비스 데스크 티켓으로 표시됩니다.

    외부 참가자에게 보내는 서비스 데스크 이메일은 이제 GitLab 인스턴스의 기본 발신 이메일 구성으로 전송됩니다.

사용자 지정 이메일 구성 변경 또는 제거

사용자 지정 이메일 구성을 변경하려면 이를 재설정하고 제거한 후 다시 구성해야 합니다.

프로세스의 어느 단계에서든 구성을 재설정하려면 사용자 지정 이메일 재설정을 선택하세요.
그런 다음 자격 증명이 데이터베이스에서 제거됩니다.

사용자 지정 이메일 회신 주소

외부 참가자는 이메일로 회신하여 서비스 데스크 티켓에 회신할 수 있습니다.
GitLab은 티켓에 해당하는 32자 회신 키가 포함된 이메일 회신 주소를 사용합니다.
사용자 지정 이메일이 구성되면 GitLab은 해당 이메일에서 회신 주소를 생성합니다.

Google Workspace를 사용하여 자체 도메인 설정하기

자체 도메인을 사용하여 Google Workspace에 대한 서비스 데스크의 맞춤 이메일 주소를 설정하십시오.

필수 조건:

  • 이미 Google Workspace 계정이 있습니다.
  • 귀하의 테넌트에 대해 새 계정을 생성할 수 있습니다.

Google Workspace에서 맞춤 서비스 데스크 이메일 주소를 구성하려면:

  1. Google Workspace 계정 구성하기
  2. 이메일 포워딩 구성하기
  3. 맞춤 이메일 주소 구성하기

Google Workspace 계정 구성하기

먼저 Google Workspace 계정을 생성하고 구성해야 합니다.

Google Workspace에서:

  1. 사용하려는 맞춤 이메일 주소용으로 새 계정을 생성합니다(예: support@example.com).
  2. 해당 계정에 로그인하고 2단계 인증을 활성화합니다.
  3. SMTP 비밀번호로 사용할 수 있는 앱 비밀번호를 생성합니다.
    안전한 장소에 저장하고 문자 사이의 공백을 제거하십시오.

다음으로, 이메일 포워딩 구성해야 합니다.

이메일 포워딩 구성하기

다음 단계는 GitLab과 Google Workspace 간에 이동해야 합니다.

GitLab에서:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 일반을 선택합니다.
  3. 서비스 데스크를 확장합니다.
  4. 서비스 데스크 이메일 주소로 이메일을 전달할 주소 아래의 이메일 주소를 참조합니다.

Google Workspace에서:

  1. 맞춤 이메일 계정에 로그인하고 포워딩 및 POP/IMAP 설정 페이지를 엽니다.
  2. 전달 주소 추가를 선택합니다.
  3. 맞춤 이메일 양식에서 서비스 데스크 주소를 입력합니다.
  4. 다음을 선택합니다.
  5. 입력 내용을 확인하고 진행을 선택합니다. Google이 서비스 데스크 주소로 이메일을 보내고 확인 코드를 요구합니다.

GitLab에서:

  1. 프로젝트의 문제로 이동하고 Google의 확인 이메일에서 새 문제가 생성될 때까지 기다립니다.
  2. 문제를 열고 확인 코드를 기록합니다.
  3. (선택 사항) 문제를 삭제합니다.

Google Workspace에서:

  1. 확인 코드를 입력하고 확인을 선택합니다.
  2. 들어오는 메일의 복사본을 다음으로 전달을 선택하고 드롭다운 목록에서 서비스 데스크 주소가 선택되어 있는지 확인합니다.
  3. 페이지 하단에서 변경 사항 저장을 선택합니다.

다음으로, 맞춤 이메일 주소 구성을 하여 서비스 데스크와 함께 사용할 수 있습니다.

맞춤 이메일 주소 구성하기

GitLab에서:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 일반을 선택합니다.
  3. 서비스 데스크를 확장하고 맞춤 이메일 설정을 찾습니다.
  4. 필드를 완료합니다:
    • 맞춤 이메일 주소: 귀하의 맞춤 이메일 주소입니다.
    • SMTP 호스트: smtp.gmail.com.
    • SMTP 포트: 587.
    • SMTP 사용자 이름: 맞춤 이메일 주소로 미리 채워짐.
    • SMTP 비밀번호: 맞춤 이메일 계정용으로 이전에 생성한 앱 비밀번호입니다.
    • SMTP 인증 방법: GitLab이 서버 지원 방법을 선택하도록 합니다(권장).
  5. 저장하고 연결 테스트를 선택합니다.
  6. 확인 프로세스 후에 귀하가 맞춤 이메일 주소를 활성화할 수 있어야 합니다.

알려진 문제

  • 일부 서비스 제공업체는 더 이상 SMTP 연결을 허용하지 않습니다.

    종종 사용자별로 이를 활성화하고 앱 암호를 생성할 수 있습니다.

  • Microsoft Exchange는 From 헤더를 유지하지 않으므로 동일한 테넌트에서 사용자 지정 이메일을 사용할 수 없습니다.

    해결 방법으로:

    • GitLab SaaS에서는 전송 규칙을 사용하여 사용자 지정 이메일 주소에서 GitLab SaaS의 서비스 데스크 이메일로 이메일을 포워딩하세요. 현재 테넌트 외부의 이메일 주소로 포워딩하면 원래의 From 헤더가 유지됩니다.

    • GitLab 자체 관리에서는 다른 서비스 제공업체의 하위 도메인이나 다른 도메인을 사용자 지정 이메일 주소 또는 GitLab 인스턴스의 incoming_email 또는 service_desk_email에 사용하세요.

추가 서비스 데스크 별칭 이메일 사용

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

인스턴스를 위한 서비스 데스크의 추가 별칭 이메일 주소를 사용할 수 있습니다.

이를 위해서는

인스턴스 구성에서 service_desk_email를 설정해야 합니다. 기본 -issue- 부분을 대체하는 사용자 지정 접미사도 설정할 수 있습니다.

서비스 데스크 별칭 이메일 구성

note
GitLab.com에서는 이메일 주소로 contact-project+%{key}@incoming.gitlab.com으로 이미 사용자 지정 메일박스가 구성되어 있습니다. 여전히 프로젝트 설정에서 사용자 지정 접미사를 구성할 수 있습니다.

서비스 데스크는 기본적으로 수신 이메일 구성을 사용합니다. 그러나 서비스 데스크에 대해 별도의 이메일 주소를 사용하려면 프로젝트 설정에서 사용자 지정 접미사와 함께 service_desk_email을 구성하세요.

전제 조건:

  • address는 주소의 user 부분에 +%{key} 자리표시자를 포함해야 하며, @ 앞에 있어야 합니다. 이 자리표시자는 문제가 생성되어야 하는 프로젝트를 식별하는 데 사용됩니다.

  • service_desk_emailincoming_email 구성은 항상 별도의 메일박스를 사용해야 서비스 데스크 이메일이 올바르게 처리됩니다.

IMAP을 통해 서비스 데스크에 대한 사용자 지정 메일박스를 구성하려면 전체 구성 파일에 다음 스니펫을 추가하세요:

리눅스 패키지 (Omnibus)
note
GitLab 15.3 이후 버전에서는 서비스 데스크가 기본적으로 Sidekiq 작업을 대기열에 넣는 대신 webhook (내부 API 호출)을 사용합니다. GitLab 15.3에서 실행 중인 리눅스 패키지 설치에서 webhook을 사용하려면 비밀 파일을 생성해야 합니다. 자세한 내용은 병합 요청 5927를 참조하세요. GitLab 15.4에서는 리눅스 패키지 설치를 재구성하면 이 비밀 파일이 자동으로 생성되므로 비밀 파일 구성 설정이 필요하지 않습니다. 자세한 내용은 이슈 1462를 참조하세요.
gitlab_rails['service_desk_email_enabled'] = true
gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com"
gitlab_rails['service_desk_email_email'] = "project_contact@gmail.com"
gitlab_rails['service_desk_email_password'] = "[REDACTED]"
gitlab_rails['service_desk_email_mailbox_name'] = "inbox"
gitlab_rails['service_desk_email_idle_timeout'] = 60
gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log"
gitlab_rails['service_desk_email_host'] = "imap.gmail.com"
gitlab_rails['service_desk_email_port'] = 993
gitlab_rails['service_desk_email_ssl'] = true
gitlab_rails['service_desk_email_start_tls'] = false
소스에서 컴파일한 버전
service_desk_email:
  enabled: true
  address: "project_contact+%{key}@example.com"
  user: "project_contact@example.com"
  password: "[REDACTED]"
  host: "imap.gmail.com"
  delivery_method: webhook
  secret_file: .gitlab-mailroom-secret
  port: 993
  ssl: true
  start_tls: false
  log_path: "log/mailroom.log"
  mailbox: "inbox"
  idle_timeout: 60
  expunge_deleted: true

구성 옵션은 수신 이메일 구성을 위한 것과 동일합니다.

암호화된 자격 증명 사용

서비스 데스크 이메일 자격 증명을 구성 파일에 일반 텍스트로 저장하는 대신, 수신 이메일 자격 증명에 대해 옵션으로 암호화된 파일을 사용할 수 있습니다.

사전 요구 사항:

  • 암호화된 자격 증명을 사용하려면 먼저 암호화된 구성을 활성화해야 합니다.

암호화된 파일에서 지원되는 구성 항목은 다음과 같습니다:

  • user
  • password
Linux 패키지 (Omnibus)
  1. 처음에 /etc/gitlab/gitlab.rb의 서비스 데스크 구성은 다음과 같았습니다:

    gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com"
    gitlab_rails['service_desk_email_password'] = "examplepassword"
    
  2. 암호화된 비밀을 편집합니다:

    sudo gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=vim
    
  3. 서비스 데스크 이메일 비밀의 비암호화된 내용을 입력합니다:

    user: 'service-desk-email@mail.example.com'
    password: 'examplepassword'
    
  4. /etc/gitlab/gitlab.rb를 편집하고 emailpassword에 대한 service_desk 설정을 제거합니다.

  5. 파일을 저장하고 GitLab을 재구성합니다:

    sudo gitlab-ctl reconfigure
    
Helm 차트 (Kubernetes)

Kubernetes 비밀을 사용하여 서비스 데스크 이메일 암호를 저장합니다. 더 많은 정보는 Helm IMAP 비밀을 참조하세요.

Docker
  1. 처음에 docker-compose.yml의 서비스 데스크 구성은 다음과 같았습니다:

    version: "3.6"
    services:
      gitlab:
        image: 'gitlab/gitlab-ee:latest'
        restart: always
        hostname: 'gitlab.example.com'
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com"
            gitlab_rails['service_desk_email_password'] = "examplepassword"
    
  2. 컨테이너에 들어가서 암호화된 비밀을 편집합니다:

    sudo docker exec -t <container_name> bash
    gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=editor
    
  3. 서비스 데스크 비밀의 비암호화된 내용을 입력합니다:

    user: 'service-desk-email@mail.example.com'
    password: 'examplepassword'
    
  4. docker-compose.yml을 편집하고 emailpassword에 대한 service_desk 설정을 제거합니다.

  5. 파일을 저장하고 GitLab을 재시작합니다:

    docker compose up -d
    
소스에서 직접 컴파일된 (Self-compiled)
  1. 처음에 /home/git/gitlab/config/gitlab.yml의 서비스 데스크 구성은 다음과 같았습니다:

    production:
      service_desk_email:
        user: 'service-desk-email@mail.example.com'
        password: 'examplepassword'
    
  2. 암호화된 비밀을 편집합니다:

    bundle exec rake gitlab:service_desk_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production
    
  3. 서비스 데스크 비밀의 비암호화된 내용을 입력합니다:

    user: 'service-desk-email@mail.example.com'
    password: 'examplepassword'
    
  4. /home/git/gitlab/config/gitlab.yml을 편집하고 userpassword에 대한 service_desk_email: 설정을 제거합니다.

  5. 파일을 저장하고 GitLab 및 Mailroom을 재시작합니다:

    # systemd를 사용하는 시스템의 경우
    sudo systemctl restart gitlab.target
    
    # SysV init을 사용하는 시스템의 경우
    sudo service gitlab restart
    

Microsoft Graph

  • GitLab 15.11에서 자체 컴파일(소스) 설치를 위해 도입됨 링크.

service_desk_email은 IMAP 대신 Microsoft Graph API를 사용하여 Microsoft Exchange Online 메일함을 읽도록 구성할 수 있습니다. Microsoft Graph를 위한 OAuth 2.0 애플리케이션을 설정하세요 수신 이메일과 동일한 방법으로.

Linux package (Omnibus)
  1. /etc/gitlab/gitlab.rb를 편집하고 다음 줄을 추가하세요. 원하는 값으로 대체하세요:
  gitlab_rails['service_desk_email_enabled'] = true
  gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com"
  gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com"
  gitlab_rails['service_desk_email_mailbox_name'] = "inbox"
  gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log"
  gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph'
  gitlab_rails['service_desk_email_inbox_options'] = {
    'tenant_id': '<YOUR-TENANT-ID>',
    'client_id': '<YOUR-CLIENT-ID>',
    'client_secret': '<YOUR-CLIENT-SECRET>',
    'poll_interval': 60  # 선택 사항
  }

미국 정부를 위한 Microsoft Cloud 또는 다른 Azure 배포를 위해 azure_ad_endpointgraph_endpoint 설정을 구성하세요. 예를 들면:

  gitlab_rails['service_desk_email_inbox_options'] = {
    'azure_ad_endpoint': 'https://login.microsoftonline.us',
    'graph_endpoint': 'https://graph.microsoft.us',
    'tenant_id': '<YOUR-TENANT-ID>',
    'client_id': '<YOUR-CLIENT-ID>',
    'client_secret': '<YOUR-CLIENT-SECRET>',
    'poll_interval': 60  # 선택 사항
  }
Helm chart (Kubernetes)
  1. Kubernetes Secret 생성하여 OAuth 2.0 애플리케이션 클라이언트 비밀 포함:

    kubectl create secret generic service-desk-email-client-secret --from-literal=secret=<YOUR-CLIENT_SECRET>
    
  2. GitLab Service Desk 이메일 인증 토큰을 위한 Kubernetes Secret 생성. <name>을 GitLab 설치를 위한 Helm 릴리즈 이름으로 대체하세요:

    kubectl create secret generic <name>-service-desk-email-auth-token --from-literal=authToken=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64)
    
  3. Helm 값을 내보내기:

    helm get values gitlab > gitlab_values.yaml
    
  4. gitlab_values.yaml을 편집하세요:

    global:
      appConfig:
      serviceDeskEmail:
        enabled: true
        address: "project_contact+%{key}@example.onmicrosoft.com"
        user: "project_contact@example.onmicrosoft.com"
        mailbox: inbox
        inboxMethod: microsoft_graph
        azureAdEndpoint: https://login.microsoftonline.com
        graphEndpoint: https://graph.microsoft.com
        tenantId: "YOUR-TENANT-ID"
        clientId: "YOUR-CLIENT-ID"
        clientSecret:
          secret: service-desk-email-client-secret
          key: secret
        deliveryMethod: webhook
        authToken:
          secret: <name>-service-desk-email-auth-token
          key: authToken
    

    미국 정부를 위한 Microsoft Cloud 또는 다른 Azure 배포를 위해 azureAdEndpointgraphEndpoint 설정을 구성하세요. 이 필드는 대소문자를 구분합니다:

    global:
      appConfig:
      serviceDeskEmail:
        [..]
        azureAdEndpoint: https://login.microsoftonline.us
        graphEndpoint: https://graph.microsoft.us
        [..]
    
  5. 파일을 저장하고 새 값을 적용하세요:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. docker-compose.yml을 편집하세요:

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['service_desk_email_enabled'] = true
            gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com"
            gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com"
            gitlab_rails['service_desk_email_mailbox_name'] = "inbox"
            gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log"
            gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph'
            gitlab_rails['service_desk_email_inbox_options'] = {
              'tenant_id': '<YOUR-TENANT-ID>',
              'client_id': '<YOUR-CLIENT-ID>',
              'client_secret': '<YOUR-CLIENT-SECRET>',
              'poll_interval': 60  # 선택 사항
            }
    
  2. 파일을 저장하고 GitLab을 재시작하세요:

    docker compose up -d
    

미국 정부를 위한 Microsoft Cloud 또는 다른 Azure 배포를 위해 azure_ad_endpointgraph_endpoint 설정을 구성하세요:

  1. docker-compose.yml을 편집하세요:

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['service_desk_email_enabled'] = true
            gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com"
            gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com"
            gitlab_rails['service_desk_email_mailbox_name'] = "inbox"
            gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log"
            gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph'
            gitlab_rails['service_desk_email_inbox_options'] = {
              'azure_ad_endpoint': 'https://login.microsoftonline.us',
              'graph_endpoint': 'https://graph.microsoft.us',
              'tenant_id': '<YOUR-TENANT-ID>',
              'client_id': '<YOUR-CLIENT-ID>',
              'client_secret': '<YOUR-CLIENT-SECRET>',
              'poll_interval': 60  # 선택 사항
            }
    
  2. 파일을 저장하고 GitLab을 재시작하세요:

    docker compose up -d
    
Self-compiled (source)
  1. /home/git/gitlab/config/gitlab.yml을 편집하세요:

      service_desk_email:
        enabled: true
        address: "project_contact+%{key}@example.onmicrosoft.com"
        user: "project_contact@example.onmicrosoft.com"
        mailbox: "inbox"
        delivery_method: webhook
        log_path: "log/mailroom.log"
        secret_file: .gitlab-mailroom-secret
        inbox_method: "microsoft_graph"
        inbox_options:
          tenant_id: "<YOUR-TENANT-ID>"
          client_id: "<YOUR-CLIENT-ID>"
          client_secret: "<YOUR-CLIENT-SECRET>"
          poll_interval: 60  # 선택 사항
    

미국 정부를 위한 Microsoft Cloud 또는 다른 Azure 배포를 위해 azure_ad_endpointgraph_endpoint 설정을 구성하세요. 예를 들면:

     service_desk_email:
       enabled: true
       address: "project_contact+%{key}@example.onmicrosoft.com"
       user: "project_contact@example.onmicrosoft.com"
       mailbox: "inbox"
       delivery_method: webhook
       log_path: "log/mailroom.log"
       secret_file: .gitlab-mailroom-secret
       inbox_method: "microsoft_graph"
       inbox_options:
         azure_ad_endpoint: "https://login.microsoftonline.us"
         graph_endpoint: "https://graph.microsoft.us"
         tenant_id: "<YOUR-TENANT-ID>"
         client_id: "<YOUR-CLIENT-ID>"
         client_secret: "<YOUR-CLIENT-SECRET>"
         poll_interval: 60  # 선택 사항

서비스 데스크 별칭 이메일에 대한 접미사를 구성하십시오

프로젝트의 서비스 데스크 설정에서 사용자 정의 접미사를 설정할 수 있습니다.

접미사는 소문자 (a-z), 숫자 (0-9), 또는 밑줄 (_)만 포함할 수 있습니다.

구성된 경우, 사용자 정의 접미사는 새로운 서비스 데스크 이메일 주소를 생성하며, 이는 다음과 같은 형식의 service_desk_email_address 설정과 키로 구성됩니다: <project_full_path>-<custom_suffix>

전제 조건:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.

  2. 설정 > 일반을 선택합니다.

  3. 서비스 데스크를 확장합니다.

  4. 이메일 주소 접미사 아래에 사용할 접미사를 입력합니다.

  5. 변경 사항 저장을 선택합니다.

예를 들어, mygroup/myproject 프로젝트 서비스 데스크 설정이 다음과 같이 구성되어 있다고 가정합니다:

  • 이메일 주소 접미사가 support로 설정되어 있습니다.
  • 서비스 데스크 이메일 주소가 contact+%{key}@example.com으로 구성되어 있습니다.

이 프로젝트의 서비스 데스크 이메일 주소는: contact+mygroup-myproject-support@example.com입니다.

수신 이메일 주소는 여전히 작동합니다.

사용자 정의 접미사를 구성하지 않으면 프로젝트 식별을 위해 기본 프로젝트 식별자가 사용됩니다.

다중 노드 환경에서 이메일 수집 구성

다중 노드 환경은 GitLab이 확장성, 내결함성 및 성능 이유로 여러 서버에서 실행되는 설정입니다.

GitLab은 incoming_emailservice_desk_email 메일함에서 읽지 않은 새로운 이메일을 수집하기 위해 mail_room이라는 별도의 프로세스를 사용합니다.

Helm 차트 (Kubernetes)

GitLab Helm 차트는 여러 개의 서브차트로 구성되어 있으며, 그 중 하나는 Mailroom 서브차트입니다. 수신 이메일에 대한 일반 설정서비스 데스크 이메일에 대한 일반 설정을 구성합니다.

리눅스 패키지 (Omnibus)

다중 노드 리눅스 패키지 설치 환경에서, mail_room은 단일 노드에서만 실행합니다. 단일 rails 노드(예: application_role)에서 실행하거나 완전히 분리된 상태로 실행할 수 있습니다.

모든 노드 설정

  1. 모든 노드에서 웹 UI 및 생성된 이메일에서 이메일 주소를 렌더링하기 위해 incoming_emailservice_desk_email에 대한 기본 구성을 추가합니다.

    /etc/gitlab/gitlab.rb에서 incoming_email 또는 service_desk_email 섹션을 찾습니다:

    incoming_email
    gitlab_rails['incoming_email_enabled'] = true
    gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.com"
    
    service_desk_email
    gitlab_rails['service_desk_email_enabled'] = true
    gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.com"
    
  2. GitLab은 mail_room에서 GitLab 애플리케이션으로 이메일을 전송하는 두 가지 방법을 제공합니다. 각 이메일 설정에 대해 delivery_method를 개별적으로 구성할 수 있습니다:

    1. 추천: webhook(GitLab 15.3 이후 기본값)은 이메일 페이로드를 API POST 요청을 통해 GitLab 애플리케이션으로 보냅니다. 공유 토큰을 사용하여 인증합니다. 이 방법을 선택하는 경우, mail_room 프로세스가 API 엔드포인트에 접근할 수 있고 모든 애플리케이션 노드 간에 공유 토큰을 배포할 수 있는지 확인하십시오.

      incoming_email
      gitlab_rails['incoming_email_delivery_method'] = "webhook"
      
      # mail_room이 연락할 수 있는 URL. 내부 URL이나 IP도 사용할 수 있으며,
      # mail_room이 해당 주소를 통해 GitLab API에 접근할 수 있도록 하세요.
      # "/"로 끝나지 않도록 하세요.
      gitlab_rails['incoming_email_gitlab_url'] = "https://gitlab.example.com"
      
      # 무작위 토큰을 포함해야 하는 공유 비밀 파일. 모든 노드에서 동일해야 합니다.
      gitlab_rails['incoming_email_secret_file'] = ".gitlab_mailroom_secret"
      
      service_desk_email
      gitlab_rails['service_desk_email_delivery_method'] = "webhook"
      
      # mail_room이 연락할 수 있는 URL. 내부 URL이나 IP도 사용할 수 있으며,
      # mail_room이 해당 주소를 통해 GitLab API에 접근할 수 있도록 하세요.
      # "/"로 끝나지 않도록 하세요.
      
      gitlab_rails['service_desk_email_gitlab_url'] = "https://gitlab.example.com"
      
      # 무작위 토큰을 포함해야 하는 공유 비밀 파일. 모든 노드에서 동일해야 합니다.
      gitlab_rails['service_desk_email_secret_file'] = ".gitlab_mailroom_secret"
      
    2. GitLab 16.0에서 폐지 예정이며 17.0에서 제거될 계획입니다: webhook 설정에 문제가 발생하는 경우, Redis를 사용하여 이메일 페이로드를 GitLab Sidekiq에 직접 전달하기 위해 sidekiq를 사용하십시오.

      incoming_email
      # Redis 구성을 사용하여 Sidekiq 작업을 직접 추가합니다.
      gitlab_rails['incoming_email_delivery_method'] = "sidekiq"
      
      service_desk_email
      # Redis 구성을 사용하여 Sidekiq 작업을 직접 추가합니다.
      gitlab_rails['service_desk_email_delivery_method'] = "sidekiq"
      
  3. 이메일 수집을 실행하지 않아야 하는 모든 노드에서 mail_room을 비활성화합니다. 예를 들어, /etc/gitlab/gitlab.rb에서:

    mailroom['enable'] = false
    
  4. 변경 사항이 적용되도록 GitLab 재구성을 수행합니다.

단일 이메일 수집 노드 설정

모든 노드를 설정하고 mail_room 프로세스를 비활성화한 후, 단일 노드에서 mail_room을 활성화합니다.

이 노드는 정기적으로 incoming_emailservice_desk_email의 메일함을 폴링하며, 새로운 읽지 않은 이메일을 GitLab으로 이동합니다.

  1. 이메일 수집을 추가로 처리하는 기존 노드를 선택합니다.

  2. incoming_emailservice_desk_email에 대한 전체 구성 및 자격 증명을 추가합니다.

  3. 이 노드에서 mail_room을 활성화합니다. 예를 들어, /etc/gitlab/gitlab.rb에서:

    mailroom['enable'] = true
    
  4. 이 노드에서 GitLab 재구성을 수행하여 변경 사항이 적용되도록 합니다.