기본적으로 Service Desk는 새 프로젝트에서 활성화되어 있습니다. 활성화되어 있지 않으면 프로젝트 설정에서 활성화할 수 있습니다.

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.
• GitLab Self-Managed에서는 GitLab 인스턴스에 수신 이메일을 설정해야 합니다. 이메일 서브 주소 지정을 사용하는 편이 좋지만, 캐치올 사서함을 사용할 수도 있습니다. 이 작업에는 관리자 액세스 권한이 필요합니다. 이메일 서브 주소 지정이나 캐치올 사서함을 지원하는 수신 이메일이 없으면 프로젝트 설정에 Service Desk 섹션이 표시되지 않습니다.
• 프로젝트의 이슈 트래커를 켜 두어야 합니다.

프로젝트에서 Service Desk를 켜려면 다음을 수행합니다:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Service Desk를 확장합니다.
4. Activate Service Desk 토글을 켭니다.
5. 선택 사항. 필드를 입력합니다.
   • Service Desk 이메일 주소에 접미사를 추가합니다.
   • Template to append to all Service Desk issues 아래 목록이 비어 있으면 리포지터리에 설명 템플릿을 생성합니다.
6. Save changes를 선택합니다.

이제 이 프로젝트에서 Service Desk가 켜졌습니다. Email address to use for Service Desk 아래에 표시된 주소로 누군가 이메일을 보내면, GitLab이 해당 이메일 내용으로 비공개 티켓을 생성합니다.

Service Desk 용어집#

이 용어집은 Service Desk와 관련된 용어의 정의를 제공합니다.

프로젝트 보안 개선#

Service Desk 프로젝트의 보안을 개선하려면 다음을 수행하는 편이 좋습니다:

• 나중에 변경할 수 있도록 Service Desk 이메일 주소를 이메일 시스템의 별칭 뒤에 둡니다.
• 이 서비스에 스팸 검사를 추가하도록 GitLab 인스턴스에서 Akismet을 켭니다. 차단되지 않은 이메일 스팸은 다수의 스팸 이슈가 생성되는 결과로 이어질 수 있습니다.

외부 참여자에게 전송되는 이메일 커스터마이징#

다음 경우에 외부 참여자에게 이메일이 전송됩니다:

• 요청자가 Service Desk로 이메일을 보내 새 티켓을 제출한 경우.
• 외부 참여자가 Service Desk 티켓에 추가된 경우.
• Service Desk 티켓에 새 공개 댓글이 추가된 경우.
  • 댓글을 편집해도 새 이메일이 전송되지는 않습니다.

Service Desk 이메일 템플릿으로 이러한 이메일 메시지의 본문을 사용자 정의할 수 있습니다. 템플릿에는 GitLab Flavored Markdown과 일부 HTML 태그를 넣을 수 있습니다. 예를 들어 조직의 브랜드 가이드라인에 맞춰 머리글과 바닥글을 포함하도록 이메일 형식을 구성할 수 있습니다. 또한 다음 플레이스홀더를 넣어 Service Desk 티켓이나 GitLab 인스턴스에 맞는 동적 콘텐츠를 표시할 수 있습니다.

감사 이메일#

요청자가 Service Desk를 통해 이슈를 제출하면 GitLab이 감사 이메일을 보냅니다. 추가 구성이 없으면 GitLab은 기본 감사 이메일을 보냅니다.

사용자 정의 감사 이메일 템플릿을 만들려면 다음을 수행합니다:

1. 리포지터리의 .gitlab/service_desk_templates/ 디렉터리에 thank_you.md 파일을 생성합니다.
2. Service Desk 요청자에게 보낼 회신을 사용자 정의하도록 Markdown 파일에 텍스트, GitLab Flavored Markdown, 선택된 일부 HTML 태그, 플레이스홀더를 채웁니다.

새 참여자 이메일#

외부 참여자가 티켓에 추가되면, GitLab은 대화에 참여하게 되었음을 알리는 새 참여자 이메일을 보냅니다. 추가 구성이 없으면 GitLab은 기본 새 참여자 이메일을 보냅니다.

사용자 정의 새 참여자 이메일 템플릿을 만들려면 다음을 수행합니다:

1. 리포지터리의 .gitlab/service_desk_templates/ 디렉터리에 new_participant.md 파일을 생성합니다.
2. Service Desk 요청자에게 보낼 회신을 사용자 정의하도록 Markdown 파일에 텍스트, GitLab Flavored Markdown, 선택된 일부 HTML 태그, 플레이스홀더를 채웁니다.

새 노트 이메일#

Service Desk 티켓에 새 공개 댓글이 달리면 GitLab이 새 노트 이메일을 보냅니다. 추가 구성이 없으면 GitLab은 댓글 내용을 그대로 보냅니다.

이메일을 브랜드에 맞게 유지하려면 사용자 정의 새 노트 이메일 템플릿을 만들 수 있습니다. 방법은 다음과 같습니다:

1. 리포지터리의 .gitlab/service_desk_templates/ 디렉터리에 new_note.md 파일을 생성합니다.
2. 새 노트 이메일을 사용자 정의하도록 Markdown 파일에 텍스트, GitLab Flavored Markdown, 선택된 일부 HTML 태그, 플레이스홀더를 채웁니다. 이메일 수신자가 댓글 내용을 읽을 수 있도록 템플릿에 %{NOTE_TEXT}를 반드시 포함합니다.

인스턴스 전체 이메일 머리글, 바닥글, 추가 텍스트#

인스턴스 관리자는 GitLab 인스턴스에 머리글, 바닥글, 추가 텍스트를 넣고 GitLab에서 보내는 모든 이메일에 적용할 수 있습니다. 사용자 정의 thank_you.md, new_participant.md, new_note.md를 사용하면서 이 내용을 포함하려면 템플릿에 %{SYSTEM_HEADER}, %{SYSTEM_FOOTER}, %{ADDITIONAL_TEXT}를 추가합니다.

자세한 내용은 시스템 머리글 및 바닥글 메시지와 사용자 정의 추가 텍스트를 참고합니다.

Service Desk 티켓에 사용자 정의 템플릿 사용#

새 Service Desk 티켓 설명마다 덧붙일 설명 템플릿을 프로젝트당 하나씩 선택할 수 있습니다.

설명 템플릿은 여러 수준에서 설정할 수 있습니다:

• 인스턴스 전체.
• 특정 그룹 또는 하위 그룹.
• 특정 프로젝트.

템플릿은 상속됩니다. 예를 들어 프로젝트에서는 인스턴스나 상위 그룹에 설정된 템플릿도 사용할 수 있습니다.

사전 요구 사항:

• 설명 템플릿을 생성해 두어야 합니다.

Service Desk에서 사용자 정의 설명 템플릿을 사용하려면 다음을 수행합니다:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Service Desk를 확장합니다.
4. Template to append to all Service Desk issues 드롭다운 목록에서 템플릿을 검색하거나 선택합니다.

Support Bot 사용자#

내부적으로 Service Desk는 특수 사용자인 Support Bot이 티켓을 생성하는 방식으로 동작합니다. 이 사용자는 청구 대상 사용자가 아니므로 라이선스 한도에 포함되지 않습니다.

Service Desk 이메일에서 생성된 댓글에는 이메일을 보낸 사용자의 이메일이 표시됩니다.

Support Bot의 표시 이름 변경#

Support Bot 사용자의 표시 이름을 변경할 수 있습니다. Service Desk 티켓에서 보내는 이메일은 From 헤더에 이 이름을 사용합니다. 기본 표시 이름은 GitLab Support Bot입니다.

사용자 정의 이메일 표시 이름을 편집하려면 다음을 수행합니다:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Service Desk를 확장합니다.
4. Email display name 아래에 새 이름을 입력합니다.
5. Save changes를 선택합니다.

기본 티켓 가시성#

새 티켓은 기본적으로 비공개이므로, Planner, Reporter, Developer, Maintainer, Owner 권한을 가진 프로젝트 멤버만 볼 수 있습니다.

비공개 및 내부 프로젝트에서는 새 티켓이 기본적으로 비공개가 되지 않도록 구성해, 모든 프로젝트 멤버가 볼 수 있게 할 수 있습니다.

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

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

이 설정을 끄려면 다음을 수행합니다:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Service Desk를 확장합니다.
4. New tickets are confidential by default 체크박스를 선택 해제합니다.
5. Save changes를 선택합니다.

외부 참여자가 댓글을 달면 티켓 재개#

외부 참여자가 이메일로 티켓에 새 댓글을 달면 닫힌 티켓을 다시 열도록 GitLab을 구성할 수 있습니다. 이때 티켓의 담당자를 멘션하는 내부 댓글도 추가되고, 담당자에게 할 일 항목이 생성됩니다.

전체 과정은 짧은 소개 영상을 참고합니다.

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

이 설정을 켜려면 다음을 수행합니다:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Service Desk를 확장합니다.
4. Reopen issues on a new note from an external participant 체크박스를 선택합니다.
5. Save changes를 선택합니다.

사용자 정의 이메일 주소#

지원 커뮤니케이션의 발신자로 표시할 사용자 정의 이메일 주소를 구성합니다. 지원 요청자가 알아보는 도메인을 사용해 브랜드 정체성을 유지하고 신뢰를 줄 수 있습니다.

개요는 짧은 소개 영상을 참고합니다.

이 기능은 베타 단계입니다. 베타 기능은 프로덕션에 바로 쓸 수 있는 상태는 아니지만, 정식 릴리스 전에 크게 바뀔 가능성은 낮습니다. 베타 기능을 사용해 보고 피드백 이슈로 의견을 보낼 수 있습니다.

사전 요구 사항#

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

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

• 이메일 전달을 설정할 수 있어야 합니다.

• 전달된 이메일이 원래 From 헤더를 유지해야 합니다.

• 서비스 공급자가 서브 주소 지정을 지원해야 합니다. 이메일 주소는 로컬 파트(@ 앞의 전체)와 도메인 파트로 구성됩니다.

  이메일 서브 주소 지정을 사용하면 로컬 파트에 + 기호와 임의의 텍스트를 붙여 이메일 주소의 고유한 변형을 만들 수 있습니다. 이메일 주소가 support@example.com이라면 support+1@example.com으로 이메일을 보내 서브 주소 지정 지원 여부를 확인합니다. 이 이메일이 사서함에 도착해야 합니다.

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

• SMTP host는 GitLab 인스턴스의 네트워크(GitLab Self-Managed)나 공용 인터넷(GitLab.com)에서 확인할 수 있어야 합니다.

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

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

사용자 정의 이메일 주소 구성#

자체 이메일 주소로 Service Desk 이메일을 보내려면 사용자 정의 이메일 주소를 구성하고 검증합니다.

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Service Desk를 확장하고 Configure a custom email address 섹션을 찾습니다.
4. Service Desk email address to forward emails to에서 이메일 주소를 복사합니다. 이 주소가 전달 대상으로 사용해야 하는 incoming+... 주소입니다.
5. 이메일 공급자(예: Gmail 또는 Microsoft 365)에서 사용자 정의 이메일 주소로부터 앞 단계에서 복사한 주소로 이메일 전달을 설정합니다.
6. 다시 GitLab으로 돌아와 나머지 필드를 입력합니다.
7. Save & test connection을 선택합니다.

구성이 저장되고 사용자 정의 이메일 주소의 검증이 시작됩니다.

검증#

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

보통 이 과정은 몇 분이면 끝납니다.

검증을 언제든 취소하거나 검증이 실패한 경우에는 Reset custom email을 선택합니다. 설정 페이지가 그에 맞게 갱신되어 현재 검증 상태를 보여 줍니다. SMTP 자격 증명이 삭제되고, 구성을 처음부터 다시 시작할 수 있습니다.

실패와 성공 모두, 모든 프로젝트 소유자와 검증 절차를 시작한 사용자에게 검증 결과가 담긴 알림 이메일이 전송됩니다. 검증이 실패하면 이메일에 실패 사유도 함께 담깁니다.

검증에 성공하면 사용자 정의 이메일 주소를 사용할 준비가 된 것입니다. 이제 사용자 정의 이메일 주소로 Service Desk 이메일을 보내는 기능을 켤 수 있습니다.

구성 문제 해결#

사용자 정의 이메일을 구성할 때 다음과 같은 문제가 발생할 수 있습니다.

유효하지 않은 자격 증명#

다음과 같은 오류가 발생할 수 있습니다:

The given credentials (username and password) were rejected by the SMTP server,
or you need to explicitly set an authentication method.

이 문제는 SMTP 서버가 인증 자격 증명을 거부할 때 발생합니다.

이 문제를 해결하려면 다음을 수행합니다:

1. 사용자 이름과 비밀번호가 올바른지 확인합니다.

2. GitLab이 지원되는 인증 방식을 자동으로 선택하지 못하면 다음 중 하나를 수행합니다:

   • 사용할 수 있는 인증 방식인 Plain, Login, CRAM-MD5를 시험해 봅니다.

   • GitLab 서버에서 다음 명령을 실행해 SMTP 서버가 지원하는 인증 방식을 확인합니다:

          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
     

     출력에서 250-AUTH로 시작하는 줄을 찾은 다음, 사용자 정의 이메일 설정 양식에서 지원되는 인증 방식 중 하나를 선택합니다.

3. Microsoft 365를 사용 중이고 오류가 계속되면 조건부 액세스를 끄고 앞 단계를 다시 수행합니다.

잘못된 전달 대상#

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

이 문제는 검증 이메일이 사용자 정의 이메일 구성 양식에 표시된 프로젝트별 Service Desk 주소가 아닌 다른 이메일 주소로 전달되었을 때 발생합니다.

incoming_email에서 생성된 Service Desk 주소를 사용해야 합니다. service_desk_email에서 생성된 추가 Service Desk 별칭 주소로 전달하는 방식은 이메일 회신 기능을 모두 지원하지 않으므로 지원되지 않습니다.

이 문제를 해결하려면 다음을 수행합니다:

1. 이메일을 전달할 올바른 이메일 주소를 확인합니다. 방법은 다음 중 하나입니다:
   • 모든 프로젝트 소유자와 검증 절차를 시작한 사용자가 받는 검증 결과 이메일에서 주소를 확인합니다.
   • 사용자 정의 이메일 설정 양식의 Service Desk email address to forward emails to 입력란에서 주소를 복사합니다.
2. 사용자 정의 이메일 주소로 오는 모든 이메일을 올바른 대상 이메일 주소로 전달합니다.

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

사용자 정의 이메일 주소가 검증되면 관리자는 사용자 정의 이메일 주소로 Service Desk 이메일을 보내는 기능을 켜거나 끌 수 있습니다.

사용자 정의 이메일 주소를 켜려면 다음을 수행합니다:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Service Desk를 확장합니다.
4. Enable custom email address 토글을 켭니다. 외부 참여자에게 보내는 Service Desk 이메일이 SMTP 자격 증명으로 전송됩니다.

사용자 정의 이메일 주소를 끄려면 다음을 수행합니다:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. 왼쪽 사이드바에서 Settings > General을 선택합니다.

3. Service Desk를 확장합니다.

4. Enable custom email address 토글을 끕니다. 이메일 전달을 설정해 두었으므로, 사용자 정의 이메일 주소로 오는 이메일은 계속 처리되어 프로젝트에 Service Desk 티켓으로 표시됩니다.

   이제 외부 참여자에게 보내는 Service Desk 이메일은 GitLab 인스턴스의 기본 발신 이메일 구성을 사용해 전송됩니다.

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

사용자 정의 이메일 구성을 변경하려면 먼저 초기화해 제거한 다음 사용자 정의 이메일을 다시 구성해야 합니다.

절차 중 어느 단계에서든 구성을 초기화하려면 Reset custom email을 선택합니다. 그러면 자격 증명이 데이터베이스에서 제거됩니다.

사용자 정의 이메일 답장 주소#

외부 참여자는 Service Desk 티켓에 이메일로 답장할 수 있습니다. GitLab은 티켓에 대응하는 32자 답장 키가 포함된 이메일 답장 주소를 사용합니다. 사용자 정의 이메일이 구성되어 있으면 GitLab은 그 이메일에서 답장 주소를 생성합니다.

자체 도메인으로 Google Workspace 사용#

자체 도메인으로 Google Workspace를 사용할 때 Service Desk용 사용자 정의 이메일 주소를 설정합니다.

사전 요구 사항:

• Google Workspace 계정이 이미 있어야 합니다.
• 테넌트에 새 계정을 생성할 수 있어야 합니다.

Google Workspace로 사용자 정의 Service Desk 이메일 주소를 구성하려면 다음을 수행합니다:

1. Google Workspace 계정을 구성합니다.
2. Google Workspace에서 이메일 전달을 구성합니다.
3. Google Workspace 계정으로 사용자 정의 이메일 주소를 구성합니다.

Google Workspace 계정 구성#

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

Google Workspace에서 다음을 수행합니다:

1. 사용하려는 사용자 정의 이메일 주소(예: support@example.com)로 새 계정을 생성합니다.
2. 해당 계정으로 로그인하고 2단계 인증을 활성화합니다: https://myaccount.google.com/u/3/signinoptions/two-step-verification
3. SMTP 비밀번호로 사용할 앱 비밀번호를 생성합니다: https://myaccount.google.com/u/3/apppasswords 안전한 곳에 저장하고 문자 사이의 공백은 제거합니다.

다음으로 Google Workspace에서 이메일 전달을 구성해야 합니다.

Google Workspace에서 이메일 전달 구성#

다음 단계는 GitLab과 Google Workspace를 오가며 수행합니다.

GitLab에서 다음을 수행합니다:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다
3. Service Desk를 확장합니다.
4. Service Desk email address to forward emails to 아래의 이메일 주소를 기록해 둡니다.

Google Workspace에서 다음을 수행합니다:

1. 사용자 정의 이메일 계정으로 로그인하고 Forwarding and POP/IMAP 설정을 엽니다.
2. Add a forwarding address를 선택합니다.
3. 사용자 정의 이메일 양식의 Service Desk 주소를 입력합니다.
4. Next를 선택합니다.
5. 입력 내용을 확인하고 Proceed를 선택합니다. Google이 Service Desk 주소로 이메일을 보내고 확인 코드를 요구합니다.

GitLab에서 다음을 수행합니다:

1. Plan > Work items를 선택한 다음 Type = Issue로 필터링합니다. Google의 확인 이메일로 새 이슈가 생성될 때까지 기다립니다.
2. 이슈를 선택하고 확인 코드를 기록해 둡니다.
3. 선택 사항. 이슈를 삭제합니다.

Google Workspace에서 다음을 수행합니다:

1. 확인 코드를 입력하고 Verify를 선택합니다.
2. Forward a copy of incoming mail to를 선택하고 드롭다운 목록에서 Service Desk 주소가 선택되어 있는지 확인합니다.
3. 페이지 하단에서 Save Changes를 선택합니다.

다음으로 Google Workspace 계정으로 사용자 정의 이메일 주소를 구성해 Service Desk에서 사용합니다.

Google Workspace 계정으로 사용자 정의 이메일 주소 구성#

GitLab에서 다음을 수행합니다:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Service Desk를 확장하고 사용자 정의 이메일 설정을 찾습니다.
4. 다음 필드를 입력합니다:
   • Custom email address: 사용자 정의 이메일 주소.
   • SMTP host: smtp.gmail.com.
   • SMTP port: 587.
   • SMTP username: 사용자 정의 이메일 주소가 미리 입력되어 있습니다.
   • SMTP password: 앞서 사용자 정의 이메일 계정용으로 생성한 앱 비밀번호.
   • SMTP authentication method: GitLab이 서버가 지원하는 방식을 선택하도록 둡니다(권장).
5. Save and test connection을 선택합니다.
6. 검증 절차가 끝나면 사용자 정의 이메일 주소를 켤 수 있습니다.

자체 도메인으로 Microsoft 365(Exchange online) 사용#

자체 도메인으로 Microsoft 365(Exchange)를 사용할 때 Service Desk용 사용자 정의 이메일 주소를 설정합니다.

사전 요구 사항:

• Microsoft 365 계정이 이미 있어야 합니다.
• 테넌트에 새 계정을 생성할 수 있어야 합니다.

Microsoft 365로 사용자 정의 Service Desk 이메일 주소를 구성하려면 다음을 수행합니다:

1. Microsoft 365 계정을 구성합니다.
2. Microsoft 365에서 이메일 전달을 구성합니다.
3. Microsoft 365 계정으로 사용자 정의 이메일 주소를 구성합니다.

Microsoft 365 계정 구성#

먼저 Microsoft 365 계정을 생성하고 구성해야 합니다. 이 안내에서는 사용자 정의 이메일 사서함에 라이선스가 있는 사용자를 사용합니다. 다른 구성 옵션을 시험해 볼 수도 있습니다.

Microsoft 365 관리 센터에서 다음을 수행합니다:

1. 사용하려는 사용자 정의 이메일 주소(예: support@example.com)로 새 계정을 생성합니다.
   1. Users를 확장하고 메뉴에서 Active users를 선택합니다.
   2. Add a user를 선택하고 화면의 안내를 따릅니다.
2. Microsoft Entra(이전 이름 Active Directory)에서 해당 계정의 2단계 인증을 켭니다.
3. 사용자가 앱 비밀번호를 만들 수 있도록 허용합니다.
4. 해당 계정에 Authenticated SMTP를 켭니다.
   1. 목록에서 계정을 선택합니다.
   2. 드로어에서 Mail을 선택합니다.
   3. Email apps 아래에서 Manage email apps를 선택합니다.
   4. Authenticated SMTP를 선택하고 Save changes를 선택합니다.
5. 전체 Exchange online 구성에 따라 다음 설정이 필요할 수 있습니다:

   1. Azure Cloud Shell로 SMTP 클라이언트 인증을 허용합니다:

      Set-TransportConfig -SmtpClientAuthenticationDisabled $false
      

   2. Azure Cloud Shell로 SMTP AUTH를 사용하는 레거시 TLS 클라이언트를 허용합니다:

      Set-TransportConfig -AllowLegacyTLSClients $true
      

   3. 외부 수신자에게 전달하려면 외부 이메일 전달을 켜는 방법을 다룬 안내를 참고합니다. 필요한 사용자에게만 외부 수신자 전달을 허용하도록 아웃바운드 스팸 방지 정책을 생성할 수도 있습니다.

6. 해당 계정으로 로그인하고 2단계 인증을 활성화합니다.
   1. 오른쪽 위 모서리의 메뉴에서 View account를 선택하고 Security Info로 이동합니다.
   1. Add sign-in method를 선택하고 사용할 수 있는 방식(인증 앱, 전화, 이메일)을 선택합니다.
   2. 화면의 안내를 따릅니다.

1. Security Info 페이지에서 SMTP 비밀번호로 사용할 앱 비밀번호를 생성합니다.

1. Add sign-in method를 선택하고 드롭다운 목록에서 App password를 선택합니다.

2. GitLab SD처럼 앱 비밀번호를 설명하는 이름을 지정합니다.

3. Next를 선택합니다.

4. 표시된 비밀번호를 복사해 안전한 곳에 저장합니다.

5. 선택 사항. swaks 명령줄 도구로 SMTP를 사용해 이메일을 보낼 수 있는지 확인합니다.

6. 자격 증명을 넣어 다음 명령을 실행하고, auth-password에는 앱 비밀번호를 사용합니다:

   swaks --to your-email@example.com \
         --from custom-email@example.com \
         --auth-user custom-email@example.com \
         --server smtp.office365.com:587 \
         -tls-optional \
         --auth-password <your_app_password>
   

다음으로 Microsoft 365에서 이메일 전달을 구성해야 합니다.

Microsoft 365에서 이메일 전달 구성#

다음 단계는 GitLab과 Microsoft 365 관리 센터를 오가며 수행합니다.

GitLab에서 다음을 수행합니다:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. 왼쪽 사이드바에서 Settings > General을 선택합니다

3. Service Desk를 확장합니다.

4. Service Desk email address to forward emails to 아래의 이메일 주소를 서브 주소 부분 없이 기록해 둡니다.

   수신자 주소에 서브 주소가 포함되어 있고(예: GitLab이 생성한 답장 주소) 전달 이메일 주소에도 서브 주소가 포함되어 있으면(Service Desk email address to forward emails to) 이메일이 전달되지 않습니다.

   예를 들어 incoming+group-project-12346426-issue-@incoming.gitlab.com은 incoming@incoming.gitlab.com이 됩니다. Exchange online이 전달 후에도 To 헤더에 사용자 정의 이메일 주소를 유지하고, GitLab은 그 사용자 정의 이메일 주소로 올바른 프로젝트를 지정할 수 있으므로 문제가 없습니다.

Microsoft 365 관리 센터에서 다음을 수행합니다:

1. Users를 확장하고 메뉴에서 Active users를 선택합니다.

1. 목록에서 사용자 정의 이메일에 사용할 계정을 선택합니다.
2. 드로어에서 Mail을 선택합니다.
3. Email forwarding 아래에서 Manage email forwarding을 선택합니다.
4. Forward all emails sent to this mailbox를 선택합니다.
5. Forwarding email address에 사용자 정의 이메일 양식의 Service Desk 주소를 서브 주소 부분 없이 입력합니다.
6. Save changes를 선택합니다.

다음으로 Microsoft 365 계정으로 사용자 정의 이메일 주소를 구성해 Service Desk에서 사용합니다.

Microsoft 365 계정으로 사용자 정의 이메일 주소 구성#

GitLab에서 다음을 수행합니다:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다
3. Service Desk를 확장하고 사용자 정의 이메일 설정을 찾습니다.
4. 다음 필드를 입력합니다:
   • Custom email address: 사용자 정의 이메일 주소.
   • SMTP host: smtp.office365.com.
   • SMTP port: 587.
   • SMTP username: 사용자 정의 이메일 주소가 미리 입력되어 있습니다.
   • SMTP password: 앞서 사용자 정의 이메일 계정용으로 생성한 앱 비밀번호.
   • SMTP authentication method: Login.
5. Save and test connection을 선택합니다.
6. 검증 절차가 끝나면 사용자 정의 이메일 주소를 켤 수 있습니다.

알려진 문제#

• 일부 서비스 공급자는 더 이상 SMTP 연결을 허용하지 않습니다. 사용자별로 연결을 켜고 앱 비밀번호를 생성할 수 있는 경우가 많습니다.

추가 Service Desk 별칭 이메일 사용#

인스턴스의 Service Desk에 추가 별칭 이메일 주소를 사용할 수 있습니다.

이렇게 하려면 인스턴스 구성에서 service_desk_email을 구성해야 합니다. 서브 주소 지정 부분의 기본 -issue- 자리를 대체하는 사용자 정의 접미사도 구성할 수 있습니다.

Service Desk 별칭 이메일 구성#

Service Desk는 기본적으로 수신 이메일 구성을 사용합니다. Service Desk에 별도의 이메일 주소를 두려면 프로젝트 설정에서 사용자 정의 접미사와 함께 service_desk_email을 구성합니다.

사전 요구 사항:

• address에는 주소의 user 부분, 즉 @ 앞에 +%{key} 플레이스홀더가 포함되어야 합니다. 이 플레이스홀더는 이슈를 생성할 프로젝트를 식별하는 데 사용됩니다.
• Service Desk 이메일이 올바르게 처리되도록 service_desk_email과 incoming_email 구성은 항상 별도의 사서함을 사용해야 합니다.

IMAP으로 Service Desk용 사용자 정의 사서함을 구성하려면 구성 파일에 다음 스니펫 전체를 추가합니다:

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

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

암호화된 자격 증명 사용#

Service Desk 이메일 자격 증명을 구성 파일에 평문으로 저장하는 대신, 수신 이메일 자격 증명에 암호화된 파일을 사용할 수도 있습니다.

사전 요구 사항:

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

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

• user
• password

Microsoft Graph#

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

Service Desk 별칭 이메일의 접미사 구성#

프로젝트의 Service Desk 설정에서 사용자 정의 접미사를 지정할 수 있습니다.

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

사용자 정의 접미사를 구성하면 service_desk_email_address 설정과 <project_full_path>-<custom_suffix> 형식의 키로 이루어진 새 Service Desk 이메일 주소가 생성됩니다

사전 요구 사항:

• Service Desk 별칭 이메일을 구성해 두어야 합니다.

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Service Desk를 확장합니다.
4. Email address suffix 아래에 사용할 접미사를 입력합니다.
5. Save changes를 선택합니다.

예를 들어 mygroup/myproject 프로젝트의 Service Desk 설정이 다음과 같다고 가정합니다:

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

이 프로젝트의 Service Desk 이메일 주소는 contact+mygroup-myproject-support@example.com입니다. 수신 이메일 주소도 그대로 동작합니다.

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

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

다중 노드 환경은 확장성, 내결함성, 성능을 위해 여러 서버에 걸쳐 GitLab을 실행하는 구성입니다.

GitLab은 incoming_email과 service_desk_email 사서함에서 읽지 않은 새 이메일을 가져오기 위해 mail_room이라는 별도의 프로세스를 사용합니다.

Helm 차트(Kubernetes)#

GitLab Helm 차트는 여러 하위 차트로 구성되며, 그중 하나가 Mailroom 하위 차트입니다. incoming_email 공통 설정과 service_desk_email 공통 설정을 구성합니다.

Linux 패키지(Omnibus)#

다중 노드 Linux 패키지 설치 환경에서는 mail_room을 한 노드에서만 실행합니다. 단일 rails 노드(예: application_role)에서 실행하거나 완전히 분리해 실행합니다.

모든 노드 설정#

1. 웹 UI와 생성되는 이메일에 이메일 주소가 표시되도록 모든 노드에 incoming_email과 service_desk_email의 기본 구성을 추가합니다.

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

   @@K163@@@@K164@@

   gitlab_rails['incoming_email_enabled'] = true
   gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.com"