요구 사항
수락된 헤더
거부된 헤더
설정하기
문제 해결
- 16.6.0에서 이메일 수집이 작동하지 않음
- 이메일 주소 한도로 인해 제공업체에서 수신 이메일이 거부됨

수신 이메일

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

GitLab은 수신 이메일 메시지를 기반으로 여러 가지 기능을 제공합니다:

이메일로 답글: GitLab 사용자가 알림 이메일에 답장하여 문제 및 병합 요청에 댓글을 달 수 있습니다.
이메일로 새 문제 작성: GitLab 사용자가 사용자 전용 이메일 주소로 이메일을 보내 새 문제를 생성할 수 있습니다.
이메일로 새 병합 요청 작성: GitLab 사용자가 사용자 전용 이메일 주소로 이메일을 보내 새 병합 요청을 생성할 수 있습니다.
서비스 데스크: GitLab을 통해 고객에게 이메일 지원을 제공합니다.

요구 사항

GitLab 인스턴스를 위해 의도된 메시지만 수신하는 이메일 주소를 사용하는 것을 권장합니다.
GitLab을 위한 것이 아닌 수신 이메일 메시지는 거부 통지를 받습니다.

수신 이메일 메시지를 처리하려면 IMAP 기능이 활성화된 이메일 계정이 필요합니다.
GitLab은 다음 세 가지 전략 중 하나를 요구합니다:

이메일 서브 주소 지정(권장)
모든 이메일 수신함
전용 이메일 주소(이메일로 답글만 지원)

각 옵션을 살펴보겠습니다.

이메일 서브 주소 지정

서브 주소 지정은 이메일 서버 기능으로, user+arbitrary_tag@example.com으로 발송된 모든 이메일이 user@example.com의 메일박스에 도착하는 기능입니다.
Gmail, Google Apps, Yahoo! Mail, Outlook.com, iCloud와 같은 제공업체와 함께, Postfix 메일 서버에서도 지원됩니다.
Microsoft Exchange Server는 서브 주소 지정을 지원하지 않습니다,
Microsoft Office 365는 기본적으로 서브 주소 지정을 지원하지 않습니다.

제공업체나 서버가 이메일 서브 주소 지정을 지원하는 경우, 사용을 권장합니다.
전용 이메일 주소는 이메일로 답글 기능만 지원합니다.
모든 이메일 수신함은 서브 주소 지정과 동일한 기능을 지원하지만, 서브 주소 지정을 사용하는 것이 더 바람직합니다.
하나의 이메일 주소를 사용하므로 모든 이메일 수신함은 GitLab 외의 다른 용도로 남겨둘 수 있습니다.

모든 이메일 수신함

도메인을 위한 모든 이메일 수신함은 메일 서버에 존재하지 않는 도메인으로 주소가 지정된 모든 이메일 메시지를 수신합니다.

모든 이메일 수신함은 이메일 서브 주소 지정과 동일한 기능을 지원하지만, 서브 주소 지정을 권장합니다.
이렇게 하면 모든 이메일 수신함을 다른 용도로 보존할 수 있습니다.

전용 이메일 주소

이 솔루션을 설정하려면, GitLab 알림에 대한 사용자 답변을 받기 위해 전용 이메일 주소를 만들어야 합니다.
그러나 이 방법은 답변만 지원하며, 수신 이메일의 다른 기능은 지원하지 않습니다.

수락된 헤더

GitLab 16.5에서 도입된 Cc 헤더 수락.

GitLab 17.0에서 도입된 X-Original-To 헤더 수락.

GitLab 17.6에서 도입된 X-Forwarded-To 헤더 수락.

구성된 이메일 주소가 다음 헤더 중 하나에 존재할 때 이메일이 올바르게 처리됩니다(확인하는 순서로 정렬됨):

To
Delivered-To
Envelope-To 또는 X-Envelope-To
Received
X-Original-To
X-Forwarded-To
Cc

References 헤더도 수락되지만, 이는 이메일 응답을 기존 토론 스레드와 관련시키기 위해 사용됩니다.
이메일로 문제를 생성하는 데는 사용되지 않습니다.

GitLab 14.6 및 이후 버전에서는 서비스 데스크에서도 수락된 헤더를 확인합니다.

일반적으로 “To” 필드에는 주 수신자의 이메일 주소가 포함됩니다.
그러나 다음과 같은 경우에는 구성된 GitLab 이메일 주소가 포함되지 않을 수 있습니다:

주소가 BCC 필드에 있습니다.
이메일이 포워딩되었습니다.

Received 헤더에는 여러 이메일 주소가 포함될 수 있습니다.
이들은 나타나는 순서대로 확인됩니다.
첫 번째 일치 항목이 사용됩니다.

거부된 헤더

원치 않는 이슈 생성을 방지하기 위해 GitLab은 다음 헤더를 포함하는 모든 수신 이메일을 무시합니다:

Auto-Submitted의 값이 no가 아닌 경우
X-Autoreply의 값이 yes인 경우

설정하기

Gmail/Google Apps를 수신 이메일로 사용하려면, IMAP 접근을 활성화하고 보안 수준이 낮은 앱이 계정에 접근할 수 있도록 허용하거나 2단계 인증을 활성화하고 애플리케이션 비밀번호를 사용하세요.

Office 365를 사용하려고 하고 2단계 인증이 활성화되어 있다면, 일반 비밀번호 대신에 애플리케이션 비밀번호를 사용하고 있는지 확인하세요.

Ubuntu에서 IMAP 접근이 가능한 기본 Postfix 메일 서버를 설정하려면, Postfix 설정 문서를 따르세요.

보안 우려

경고: 수신 이메일에 사용할 도메인을 선택할 때 주의하세요.

예를 들어, 귀사의 최상위 회사 도메인이 hooli.com이라고 가정해 보겠습니다.

귀사 내 모든 직원은 Google Apps를 통해 해당 도메인에서 이메일 주소를 가지고 있으며, 귀사의 개인 Slack 인스턴스는 등록을 위해 유효한 @hooli.com 이메일 주소를 요구합니다.

또한 귀사가 hooli.com에서 공개-facing GitLab 인스턴스를 호스트하고 있고 수신 이메일 도메인을 hooli.com으로 설정한 경우, 공격자는 Slack에 가입할 때 이메일로 프로젝트의 고유 주소를 사용할 수 있습니다. 이를 통해 “이메일로 새 이슈 만들기” 또는 “이메일로 새 Merge Request 만들기” 기능을 악용할 수 있습니다.

이는 확인 이메일을 전송하고, 공격자가 소유한 프로젝트에 새로운 이슈 또는 Merge Request를 생성하여 확인 링크를 선택하고 귀사의 개인 Slack 인스턴스에서 계정을 검증할 수 있도록 합니다.

수신 이메일을 서브도메인에서 받는 것을 권장합니다. 예를 들어, incoming.hooli.com과 같은 형태입니다. 또한 *.hooli.com과 같은 이메일 도메인에 대한 접근만으로 인증하는 서비스를 사용하지 않도록 해야 합니다.

대신 GitLab 이메일 커뮤니케이션을 위해 hooli-gitlab.com과 같은 전용 도메인을 사용하는 것이 좋습니다.

이러한 악용의 실제 사례에 대한 GitLab 이슈 #30366를 참조하세요.

경고: 스팸을 줄이도록 구성된 메일 서버를 사용하세요.

예를 들어, 기본 구성으로 실행 중인 Postfix 메일 서버는 악용을 초래할 수 있습니다.

구성된 메일박스에서 수신되는 모든 메시지가 처리되고, GitLab 인스턴스를 위한 것이 아닌 메시지는 거부 통지를 받게 됩니다. 발신자의 주소가 스푸핑 된 경우, 거부 통지는 스푸핑된 FROM 주소로 발송되어 메일 서버의 IP나 도메인이 블록 리스트에 나타날 수 있습니다.

경고: 사용자는 먼저 본인 인증을 위해 2단계 인증(2FA)을 사용할 필요 없이 수신 이메일 기능을 사용할 수 있습니다. 이는 인스턴스에 대해 2단계 인증을 시행하더라도 적용됩니다.

Linux 패키지 설치

/etc/gitlab/gitlab.rb에서 incoming_email 섹션을 찾아 기능을 활성화하고 특정 IMAP 서버 및 이메일 계정에 대한 세부정보를 입력하세요 (아래 예시를 참조하세요).

변경 사항이 적용되도록 GitLab을 재구성합니다:

sudo gitlab-ctl reconfigure

# 첫 번째로 활성화하거나 비활성화할 때 필요하지만 비밀번호 변경 시에는 필요하지 않습니다.
# 자세한 내용은 https://gitlab.com/gitlab-org/gitlab-foss/-/issues/23560#note_61966788을 참조하세요.
sudo gitlab-ctl restart

모든 것이 올바르게 구성되었는지 확인하세요:
```
sudo gitlab-rake gitlab:incoming_email:check
```

이제 이메일로 회신이 작동해야 합니다.

자체 컴파일 설치

GitLab 설치 디렉토리로 이동합니다:
```
cd /home/git/gitlab
```
gitlab-mail_room gem을 수동으로 설치합니다:
```
gem install gitlab-mail_room
```
주의: 이 단계는 스레드 교착 상태를 피하고 최신 MailRoom 기능을 지원하기 위해 필요합니다. 자세한 내용은 이 설명을 참조하세요.
config/gitlab.yml에서 incoming_email 섹션을 찾아 기능을 활성화하고 특정 IMAP 서버 및 이메일 계정에 대한 세부정보를 입력하세요 (아래 예시를 참조하세요).

systemd 유닛을 사용하여 GitLab을 관리하는 경우:

gitlab-mailroom.service를 gitlab.target의 종속성으로 추가합니다:
```
sudo systemctl edit gitlab.target
```
열리는 편집기에서 다음을 추가하고 파일을 저장합니다:
```
[Unit]
Wants=gitlab-mailroom.service
```
Redis와 PostgreSQL을 동일한 머신에서 실행하는 경우 Redis에 대한 종속성을 추가해야 합니다. 실행하세요:
```
sudo systemctl edit gitlab-mailroom.service
```
열리는 편집기에서 다음을 추가하고 파일을 저장합니다:
```
[Unit]
Wants=redis-server.service
After=redis-server.service
```

gitlab-mailroom.service를 시작합니다:

sudo systemctl start gitlab-mailroom.service

모든 것이 올바르게 구성되었는지 확인하세요:

sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production

SysV init 스크립트를 사용하여 GitLab을 관리하는 경우:

/etc/default/gitlab의 init 스크립트에서 mail_room을 활성화합니다:

sudo mkdir -p /etc/default
echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab

GitLab을 재시작합니다:
```
sudo service gitlab restart
```

모든 것이 올바르게 구성되었는지 확인하세요:

sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production

이제 이메일로 회신이 작동해야 합니다.

구성 예제

Postfix

Postfix 메일 서버를 위한 구성 예제입니다. incoming@gitlab.example.com 메일박스를 가정합니다.

Linux 패키지 설치를 위한 예제:

gitlab_rails['incoming_email_enabled'] = true

# 회신할 항목을 참조하도록 %{key} 자리 표시자가 포함된 이메일 주소입니다. 
# 이 %{key}는 이메일 주소 내에서 전체적으로 포함되어야 하며 다른 값으로 대체되어서는 안 됩니다.
# 예: emailaddress+%{key}@gitlab.example.com.
# 자리 표시자는 주소의 "사용자" 부분(이메일 주소의 `@` 앞)에 나타나야 합니다.
gitlab_rails['incoming_email_address'] = "incoming+%{key}@gitlab.example.com"

# 이메일 계정 사용자 이름
# 서드파티 제공자의 경우, 일반적으로 전체 이메일 주소입니다.
# 자체 호스팅 이메일 서버의 경우, 일반적으로 이메일 주소의 사용자 부분입니다.
gitlab_rails['incoming_email_email'] = "incoming"
# 이메일 계정 비밀번호
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP 서버 호스트
gitlab_rails['incoming_email_host'] = "gitlab.example.com"
# IMAP 서버 포트
gitlab_rails['incoming_email_port'] = 143
# IMAP 서버가 SSL을 사용하는지 여부
gitlab_rails['incoming_email_ssl'] = false
# IMAP 서버가 StartTLS를 사용하는지 여부
gitlab_rails['incoming_email_start_tls'] = false

# 수신 메일이 최종에 도착할 메일박스입니다. 일반적으로 "inbox"입니다.
gitlab_rails['incoming_email_mailbox_name'] = "inbox"
# IDLE 명령 타임아웃.
gitlab_rails['incoming_email_idle_timeout'] = 60

# IMAP 대신 Microsoft Graph를 사용하는 경우, 삭제된 메시지가 시간이 지난 후 자동으로 삭제되므로 
# 받은 편지함의 메시지를 유지하기 위해 false로 설정합니다.
gitlab_rails['incoming_email_delete_after_delivery'] = true

# 배달 후 삭제로 표시된 메시지를 메일박스에서 제거(영구 삭제)할지 여부입니다
# IMAP에만 적용됩니다. Microsoft Graph는 삭제된 메시지를 자동으로 삭제합니다.
gitlab_rails['incoming_email_expunge_deleted'] = true

자체 컴파일 설치를 위한 예제:

incoming_email:
    enabled: true

    # 회신할 항목을 참조하도록 %{key} 자리 표시자가 포함된 이메일 주소입니다. 
    # 이 %{key}는 이메일 주소 내에서 전체적으로 포함되어야 하며 다른 값으로 대체되어서는 안 됩니다.
    # 예: emailaddress+%{key}@gitlab.example.com.
    # 자리 표시자는 주소의 "사용자" 부분(이메일 주소의 `@` 앞)에 나타나야 합니다.
    address: "incoming+%{key}@gitlab.example.com"

    # 이메일 계정 사용자 이름
    # 서드파티 제공자의 경우, 일반적으로 전체 이메일 주소입니다.
    # 자체 호스팅 이메일 서버의 경우, 일반적으로 이메일 주소의 사용자 부분입니다.
    user: "incoming"
    # 이메일 계정 비밀번호
    password: "[REDACTED]"

    # IMAP 서버 호스트
    host: "gitlab.example.com"
    # IMAP 서버 포트
    port: 143
    # IMAP 서버가 SSL을 사용하는지 여부
    ssl: false
    # IMAP 서버가 StartTLS를 사용하는지 여부
    start_tls: false

    # 받은 편지함의 끝에 도착할 수신 메일의 메일박스입니다. 일반적으로 "inbox"입니다.
    mailbox: "inbox"
    # IDLE 명령 타임아웃입니다.
    idle_timeout: 60

    # IMAP 대신 Microsoft Graph를 사용하는 경우, 삭제된 메시지가 시간이 지난 후 자동으로 삭제되므로 
    # 받은 편지함의 메시지를 유지하기 위해 false로 설정합니다.
    delete_after_delivery: true

    # 배달 후 삭제로 표시된 메시지를 메일박스에서 제거(영구 삭제)할지 여부입니다
    # IMAP에만 적용됩니다. Microsoft Graph는 삭제된 메시지를 자동으로 삭제합니다.
    expunge_deleted: true

Gmail

Gmail/Google Workspace에 대한 예제 구성입니다. 메일박스 gitlab-incoming@gmail.com을 가정합니다.

노트:
incoming_email_email은 Gmail 별칭 계정일 수 없습니다.

Linux 패키지 설치의 예:

gitlab_rails['incoming_email_enabled'] = true

# 회신되는 항목을 참조하기 위해 대체될 %{key} 플레이스홀더를 포함한 이메일 주소입니다.
# 이 %{key}는 이메일 주소 내에서 전체적으로 포함되어야 하며 다른 값으로 대체되지 않아야 합니다.
# 예: emailaddress+%{key}@gmail.com.
# 플레이스홀더는 주소의 "사용자" 부분에 나타나야 합니다( `@` 이전).
gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@gmail.com"

# 이메일 계정 사용자 이름
# 서드파티 제공자의 경우, 일반적으로 전체 이메일 주소입니다.
# 자체 호스팅 이메일 서버의 경우, 일반적으로 이메일 주소의 사용자 부분입니다.
gitlab_rails['incoming_email_email'] = "gitlab-incoming@gmail.com"
# 이메일 계정 비밀번호
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP 서버 호스트
gitlab_rails['incoming_email_host'] = "imap.gmail.com"
# IMAP 서버 포트
gitlab_rails['incoming_email_port'] = 993
# IMAP 서버가 SSL을 사용하는지 여부
gitlab_rails['incoming_email_ssl'] = true
# IMAP 서버가 StartTLS를 사용하는지 여부
gitlab_rails['incoming_email_start_tls'] = false

# 수신 메일이 끝나는 메일박스입니다. 보통 "inbox"입니다.
gitlab_rails['incoming_email_mailbox_name'] = "inbox"
# IDLE 명령 타임아웃.
gitlab_rails['incoming_email_idle_timeout'] = 60

# IMAP 대신 Microsoft Graph를 사용하는 경우, 삭제된 메시지가 일정 시간 후 자동 삭제되므로
# 받은 편지함에서 메시지를 유지하려면 이를 false로 설정하세요.
gitlab_rails['incoming_email_delete_after_delivery'] = true

# 배달 후 삭제된 것으로 표기된 메시지를 메일박스에서 삭제(영구 제거)할지 여부
# IMAP에만 적용됩니다. Microsoft Graph는 삭제된 메시지를 자동으로 삭제합니다.
gitlab_rails['incoming_email_expunge_deleted'] = true

자체 컴파일된 설치의 예:

incoming_email:
    enabled: true

    # 회신되는 항목을 참조하기 위해 대체될 %{key} 플레이스홀더를 포함한 이메일 주소입니다.
    # 이 %{key}는 이메일 주소 내에서 전체적으로 포함되어야 하며 다른 값으로 대체되지 않아야 합니다.
    # 예: emailaddress+%{key}@gmail.com.
    # 플레이스홀더는 주소의 "사용자" 부분에 나타나야 합니다( `@` 이전).
    address: "gitlab-incoming+%{key}@gmail.com"

    # 이메일 계정 사용자 이름
    # 서드파티 제공자의 경우, 일반적으로 전체 이메일 주소입니다.
    # 자체 호스팅 이메일 서버의 경우, 일반적으로 이메일 주소의 사용자 부분입니다.
    user: "gitlab-incoming@gmail.com"
    # 이메일 계정 비밀번호
    password: "[REDACTED]"

    # IMAP 서버 호스트
    host: "imap.gmail.com"
    # IMAP 서버 포트
    port: 993
    # IMAP 서버가 SSL을 사용하는지 여부
    ssl: true
    # IMAP 서버가 StartTLS를 사용하는지 여부
    start_tls: false

    # 수신 메일이 끝나는 메일박스입니다. 보통 "inbox"입니다.
    mailbox: "inbox"
    # IDLE 명령 타임아웃.
    idle_timeout: 60

    # IMAP 대신 Microsoft Graph를 사용하는 경우, 삭제된 메시지가 일정 시간 후 자동 삭제되므로
    # 받은 편지함에서 메시지를 유지하려면 이를 false로 설정하세요.
    delete_after_delivery: true

    # 배달 후 삭제된 것으로 표기된 메시지를 메일박스에서 삭제(영구 제거)할지 여부
    # IMAP에만 적용됩니다. Microsoft Graph는 삭제된 메시지를 자동으로 삭제합니다.
    expunge_deleted: true

Microsoft Exchange Server

IMAP이 활성화된 Microsoft Exchange Server의 예제 구성입니다.

Exchange는 서브 주소를 지원하지 않으므로 선택할 수 있는 두 가지 옵션만 있습니다:

Catch-all mailbox (Exchange 전용으로 추천됨)
Dedicated email address (이메일로 답장하기만 지원)

Catch-all mailbox

catch-all 메일박스 incoming@exchange.example.com을 가정합니다.

Linux 패키지 설치 예제:

gitlab_rails['incoming_email_enabled'] = true

# 답장 대상 항목을 참조하기 위해 대체될 %{key} 플레이스홀더를 포함하는 이메일 주소입니다.
# 이 %{key}는 이메일 주소 내에서 전체로 포함되어야 하며 다른 값으로 대체되어서는 안 됩니다.
# 예: emailaddress-%{key}@exchange.example.com.
# 플레이스홀더는 주소의 "user" 부분( `@` 이전)에 나타나야 합니다.
# Exchange는 서브 주소를 지원하지 않으므로 catch-all 메일박스를 사용해야 합니다.
gitlab_rails['incoming_email_address'] = "incoming-%{key}@exchange.example.com"

# 이메일 계정 사용자 이름
# 일반적으로 이는 userPrincipalName (UPN)입니다.
gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com"
# 이메일 계정 비밀번호
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP 서버 호스트
gitlab_rails['incoming_email_host'] = "exchange.example.com"
# IMAP 서버 포트
gitlab_rails['incoming_email_port'] = 993
# IMAP 서버가 SSL을 사용하는지 여부
gitlab_rails['incoming_email_ssl'] = true

# 이메일이 전달 후 삭제로 표시될 때 메일박스에서 메시지를 완전히 제거할지 여부
# IMAP에만 적용됩니다. Microsoft Graph는 삭제된 메시지를 자동으로 삭제합니다.
gitlab_rails['incoming_email_expunge_deleted'] = true

자체 컴파일한 설치 예제:

incoming_email:
    enabled: true

    # 답장 대상 항목을 참조하기 위해 대체될 %{key} 플레이스홀더를 포함하는 이메일 주소입니다.
    # 이 %{key}는 이메일 주소 내에서 전체로 포함되어야 하며 다른 값으로 대체되어서는 안 됩니다.
    # 예: emailaddress-%{key}@exchange.example.com.
    # 플레이스홀더는 주소의 "user" 부분( `@` 이전)에 나타나야 합니다.
    # Exchange는 서브 주소를 지원하지 않으므로 catch-all 메일박스를 사용해야 합니다.
    address: "incoming-%{key}@exchange.example.com"

    # 이메일 계정 사용자 이름
    # 일반적으로 이는 userPrincipalName (UPN)입니다.
    user: "incoming@ad-domain.example.com"
    # 이메일 계정 비밀번호
    password: "[REDACTED]"

    # IMAP 서버 호스트
    host: "exchange.example.com"
    # IMAP 서버 포트
    port: 993
    # IMAP 서버가 SSL을 사용하는지 여부
    ssl: true

    # Microsoft Graph를 IMAP 대신 사용하는 경우, 삭제된 메시지가 일정 시간이 지나면 자동으로 삭제되므로
    # 받은 편지함의 메시지를 보존하려면 false로 설정합니다.
    delete_after_delivery: true

    # 이메일이 전달 후 삭제로 표시될 때 메일박스에서 메시지를 완전히 제거할지 여부
    expunge_deleted: true

Dedicated email address

참고:

이메일로 답장하기만 지원합니다.

Service Desk를 지원하지 않습니다.

전용 이메일 주소 incoming@exchange.example.com을 가정합니다.

Linux 패키지 설치 예제:

gitlab_rails['incoming_email_enabled'] = true

# Exchange는 서브 주소를 지원하지 않으며, catch-all 메일박스를 사용하지 않으므로 %{key}는 여기서 사용되지 않습니다.
gitlab_rails['incoming_email_address'] = "incoming@exchange.example.com"

# 이메일 계정 사용자 이름
# 일반적으로 이는 userPrincipalName (UPN)입니다.
gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com"
# 이메일 계정 비밀번호
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP 서버 호스트
gitlab_rails['incoming_email_host'] = "exchange.example.com"
# IMAP 서버 포트
gitlab_rails['incoming_email_port'] = 993
# IMAP 서버가 SSL을 사용하는지 여부
gitlab_rails['incoming_email_ssl'] = true

# 이메일이 전달 후 삭제로 표시될 때 메일박스에서 메시지를 완전히 제거할지 여부
gitlab_rails['incoming_email_expunge_deleted'] = true

자체 컴파일한 설치 예제:

incoming_email:
    enabled: true

    # Exchange는 서브 주소를 지원하지 않으며,
    # catch-all 메일박스를 사용하지 않으므로 %{key}는 여기서 사용되지 않습니다.
    address: "incoming@exchange.example.com"

    # 이메일 계정 사용자 이름
    # 일반적으로 이는 userPrincipalName (UPN)입니다.
    user: "incoming@ad-domain.example.com"
    # 이메일 계정 비밀번호
    password: "[REDACTED]"

    # IMAP 서버 호스트
    host: "exchange.example.com"
    # IMAP 서버 포트
    port: 993
    # IMAP 서버가 SSL을 사용하는지 여부
    ssl: true

    # Microsoft Graph를 IMAP 대신 사용하는 경우, 삭제된 메시지가 일정 시간이 지나면 자동으로 삭제되므로
    # 받은 편지함의 메시지를 보존하려면 false로 설정합니다.
    delete_after_delivery: true

    # 이메일이 전달 후 삭제로 표시될 때 메일박스에서 메시지를 완전히 제거할지 여부
    expunge_deleted: true

Microsoft Office 365

Microsoft Office 365의 IMAP이 활성화된 예제 구성입니다.

서브 주소 메일박스

참고: 2020년 9월 현재 서브 주소 지원이 Office 365에 추가되었습니다. 이 기능은 기본적으로 활성화되어 있지 않으며 PowerShell을 통해 활성화해야 합니다.

이 PowerShell 명령 시리즈는 Office 365의 조직 수준에서 서브 주소를 활성화합니다. 이를 통해 조직 내 모든 메일박스가 서브 주소가 지정된 메일을 받을 수 있습니다.

서브 주소를 활성화하려면:

PowerShell 갤러리에서 ExchangeOnlineManagement 모듈을 다운로드하여 설치합니다.

PowerShell에서 다음 명령을 실행합니다:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline
Set-OrganizationConfig -AllowPlusAddressInRecipients $true
Disconnect-ExchangeOnline

이 예는 메일박스 incoming@office365.example.com에 대한 리눅스 패키지 설치를 가정합니다:

gitlab_rails['incoming_email_enabled'] = true

# 대답하려는 항목을 참조하기 위해 대체될 %{key} 자리 표시자가 포함된 이메일 주소.
# 이 %{key}는 이메일 주소 내에 온전하게 포함되어야 하며 다른 값으로 대체되어서는 안 됩니다.
# 예: emailaddress+%{key}@office365.example.com.
# 자리 표시자는 주소의 "사용자" 부분(`@` 이전)에 나타나야 합니다.
gitlab_rails['incoming_email_address'] = "incoming+%{key}@office365.example.com"

# 이메일 계정 사용자 이름
# 일반적으로 userPrincipalName(UPN)입니다.
gitlab_rails['incoming_email_email'] = "incoming@office365.example.com"
# 이메일 계정 비밀번호
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP 서버 호스트
gitlab_rails['incoming_email_host'] = "outlook.office365.com"
# IMAP 서버 포트
gitlab_rails['incoming_email_port'] = 993
# IMAP 서버가 SSL을 사용하는지 여부
gitlab_rails['incoming_email_ssl'] = true

# 배달 후 삭제로 표시된 메시지를 메일박스에서 영구적으로 제거할 것인지 여부
gitlab_rails['incoming_email_expunge_deleted'] = true

이 예는 자가 컴파일된 설치를 위한 것으로, 메일박스 incoming@office365.example.com을 가정합니다:

incoming_email:
    enabled: true

    # 대답하려는 항목을 참조하기 위해 대체될 %{key} 자리 표시자가 포함된 이메일 주소.
    # 이 %{key}는 이메일 주소 내에 온전하게 포함되어야 하며 다른 값으로 대체되어서는 안 됩니다.
    # 예: emailaddress+%{key}@office365.example.com.
    # 자리 표시자는 주소의 "사용자" 부분(`@` 이전)에 나타나야 합니다.
    address: "incoming+%{key}@office365.example.comm"

    # 이메일 계정 사용자 이름
    # 일반적으로 userPrincipalName(UPN)입니다.
    user: "incoming@office365.example.comm"
    # 이메일 계정 비밀번호
    password: "[REDACTED]"

    # IMAP 서버 호스트
    host: "outlook.office365.com"
    # IMAP 서버 포트
    port: 993
    # IMAP 서버가 SSL을 사용하는지 여부
    ssl: true

    # 배달 후 삭제로 표시된 메시지를 메일박스에서 영구적으로 제거할 것인지 여부
    expunge_deleted: true

모든 메일박스

Linux 패키지 설치를 위한 이 예시는 incoming@office365.example.com 모든 메일박스를 가정합니다:

gitlab_rails['incoming_email_enabled'] = true

# 회신할 항목을 참조하기 위해 교체될 %{key} 플레이스홀더를 포함하는 이메일 주소입니다.
# 이 %{key}는 이메일 주소 내에서 전체적으로 포함되어야 하며 다른 값으로 대체되어서는 안 됩니다.
# 예: emailaddress-%{key}@office365.example.com.
# 플레이스홀더는 주소의 "user" 부분에 나타나야 합니다( `@` 이전에).
gitlab_rails['incoming_email_address'] = "incoming-%{key}@office365.example.com"

# 이메일 계정 사용자 이름
# 일반적으로 이는 userPrincipalName (UPN)입니다.
gitlab_rails['incoming_email_email'] = "incoming@office365.example.com"
# 이메일 계정 비밀번호
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP 서버 호스트
gitlab_rails['incoming_email_host'] = "outlook.office365.com"
# IMAP 서버 포트
gitlab_rails['incoming_email_port'] = 993
# IMAP 서버가 SSL을 사용하는 여부
gitlab_rails['incoming_email_ssl'] = true

# 배달 후 삭제로 표시된 메시지를 메일박스에서 완전히 제거할지 여부
gitlab_rails['incoming_email_expunge_deleted'] = true

자체 컴파일 설치를 위한 이 예시는 incoming@office365.example.com 모든 메일박스를 가정합니다:

incoming_email:
    enabled: true

    # 회신할 항목을 참조하기 위해 교체될 %{key} 플레이스홀더를 포함하는 이메일 주소입니다.
    # 이 %{key}는 이메일 주소 내에서 전체적으로 포함되어야 하며 다른 값으로 대체되어서는 안 됩니다.
    # 예: emailaddress+%{key}@office365.example.com.
    # 플레이스홀더는 주소의 "user" 부분에 나타나야 합니다( `@` 이전에).
    address: "incoming-%{key}@office365.example.com"

    # 이메일 계정 사용자 이름
    # 일반적으로 이는 userPrincipalName (UPN)입니다.
    user: "incoming@ad-domain.example.com"
    # 이메일 계정 비밀번호
    password: "[REDACTED]"

    # IMAP 서버 호스트
    host: "outlook.office365.com"
    # IMAP 서버 포트
    port: 993
    # IMAP 서버가 SSL을 사용하는 여부
    ssl: true

    # 배달 후 삭제로 표시된 메시지를 메일박스에서 완전히 제거할지 여부
    expunge_deleted: true

전용 이메일 주소

참고: 이메일로 회신하기만 지원합니다.
서비스 데스크는 지원할 수 없습니다.

Linux 패키지 설치를 위한 이 예시는 incoming@office365.example.com 전용 이메일 주소를 가정합니다:

gitlab_rails['incoming_email_enabled'] = true

gitlab_rails['incoming_email_address'] = "incoming@office365.example.com"

# 이메일 계정 사용자 이름
# 일반적으로 이는 userPrincipalName (UPN)입니다.
gitlab_rails['incoming_email_email'] = "incoming@office365.example.com"
# 이메일 계정 비밀번호
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP 서버 호스트
gitlab_rails['incoming_email_host'] = "outlook.office365.com"
# IMAP 서버 포트
gitlab_rails['incoming_email_port'] = 993
# IMAP 서버가 SSL을 사용하는 여부
gitlab_rails['incoming_email_ssl'] = true

# 배달 후 삭제로 표시된 메시지를 메일박스에서 완전히 제거할지 여부
gitlab_rails['incoming_email_expunge_deleted'] = true

자체 컴파일 설치를 위한 이 예시는 incoming@office365.example.com 전용 이메일 주소를 가정합니다:

incoming_email:
    enabled: true

    address: "incoming@office365.example.com"

    # 이메일 계정 사용자 이름
    # 일반적으로 이는 userPrincipalName (UPN)입니다.
    user: "incoming@office365.example.com"
    # 이메일 계정 비밀번호
    password: "[REDACTED]"

    # IMAP 서버 호스트
    host: "outlook.office365.com"
    # IMAP 서버 포트
    port: 993
    # IMAP 서버가 SSL을 사용하는 여부
    ssl: true

    # 배달 후 삭제로 표시된 메시지를 메일박스에서 완전히 제거할지 여부
    expunge_deleted: true

Microsoft Graph

GitLab은 IMAP 대신 Microsoft Graph API를 사용하여 수신 이메일을 읽을 수 있습니다.

Microsoft가 기본 인증을 사용한 IMAP 사용을 중단하고 있습니다,

따라서 새로운 Microsoft Exchange Online 사서함에는 Microsoft Graph API가 필요합니다.

GitLab을 Microsoft Graph에 구성하려면, 모든 사서함에 대해 Mail.ReadWrite 권한이 있는 OAuth 2.0 애플리케이션을 Azure Active Directory에 등록해야 합니다.

자세한 내용은 MailRoom 단계별 안내서와 Microsoft 지침을 참조하세요.

OAuth 2.0 애플리케이션을 구성할 때 다음을 기록하세요:

Azure Active Directory의 테넌트 ID
OAuth 2.0 애플리케이션의 클라이언트 ID
OAuth 2.0 애플리케이션의 클라이언트 비밀

사서함 액세스 제한

MailRoom이 서비스 계정으로 작동하려면, Azure Active Directory에서 생성한 애플리케이션에 대해 모든 사서함에서 이메일을 읽고 쓸 수 있도록 Mail.ReadWrite 속성을 설정해야 합니다.

보안 우려를 완화하기 위해, 모든 계정의 사서함 액세스를 제한하는 애플리케이션 액세스 정책을 구성하는 것이 좋습니다.

자세한 내용은 Microsoft 문서를 참조하세요.

다음은 사용 중인 사서함을 incoming@example.onmicrosoft.com으로 가정한 Linux 패키지 설치 예입니다:

Microsoft Graph 구성

대체 Azure 배포는 GitLab 14.9에 도입되었습니다.

gitlab_rails['incoming_email_enabled'] = true

# 회신하려는 항목을 참조하도록 교체될 %{key} 플레이스홀더를 포함한 이메일 주소. 
# 이 %{key}는 이메일 주소 내에서 전체적으로 포함되어야 하며 다른 값으로 대체되지 않아야 합니다. 
# 예: emailaddress+%{key}@example.onmicrosoft.com.
# 플레이스홀더는 주소의 "user" 부분( `@` 앞쪽)에 나타나야 합니다.
gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.onmicrosoft.com"

# 이메일 계정 사용자 이름
gitlab_rails['incoming_email_email'] = "incoming@example.onmicrosoft.com"
gitlab_rails['incoming_email_delete_after_delivery'] = false

gitlab_rails['incoming_email_inbox_method'] = 'microsoft_graph'
gitlab_rails['incoming_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_endpoint 및 graph_endpoint 설정을 구성합니다.

미국 정부를 위한 Microsoft Cloud 예시:

gitlab_rails['incoming_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  # 선택 사항
}

Microsoft Graph API는 아직 자체 컴파일 설치에서 지원되지 않습니다. 자세한 내용은 이 문제를 참조하세요.

암호화된 자격 증명 사용

소개됨 GitLab 15.9에서.

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

전제 조건:

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

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

user
password

::탭

:::탭 제목 리눅스 패키지 (Omnibus)

처음에 /etc/gitlab/gitlab.rb에서 들어오는 이메일 구성이 다음과 같았다면:

gitlab_rails['incoming_email_email'] = "incoming-email@mail.example.com"
gitlab_rails['incoming_email_password'] = "examplepassword"

암호화된 비밀을 편집합니다:

sudo gitlab-rake gitlab:incoming_email:secret:edit EDITOR=vim

들어오는 이메일 비밀의 암호화되지 않은 내용을 입력합니다:
```
user: 'incoming-email@mail.example.com'
password: 'examplepassword'
```
/etc/gitlab/gitlab.rb를 편집하고 email 및 password의 incoming_email 설정을 제거합니다.
파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

:::탭 제목 헬름 차트 (Kubernetes)

Kubernetes 비밀을 사용하여 들어오는 이메일 비밀번호를 저장합니다. 자세한 내용은, Helm IMAP 비밀에 대해 읽어보세요.

:::탭 제목 도커

처음에 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['incoming_email_email'] = "incoming-email@mail.example.com"
        gitlab_rails['incoming_email_password'] = "examplepassword"

컨테이너에 들어가서 암호화된 비밀을 편집합니다:

sudo docker exec -t <container_name> bash
gitlab-rake gitlab:incoming_email:secret:edit EDITOR=editor

들어오는 이메일 비밀의 암호화되지 않은 내용을 입력합니다:
```
user: 'incoming-email@mail.example.com'
password: 'examplepassword'
```
docker-compose.yml을 편집하고 email 및 password의 incoming_email 설정을 제거합니다.
파일을 저장하고 GitLab을 재시작합니다:
```
docker compose up -d
```

:::탭 제목 소스에서 컴파일된 것 (Self-compiled)

처음에 /home/git/gitlab/config/gitlab.yml에서 들어오는 이메일 구성이 다음과 같았다면:

production:
  incoming_email:
    user: 'incoming-email@mail.example.com'
    password: 'examplepassword'

암호화된 비밀을 편집합니다:

bundle exec rake gitlab:incoming_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production

들어오는 이메일 비밀의 암호화되지 않은 내용을 입력합니다:
```
user: 'incoming-email@mail.example.com'
password: 'examplepassword'
```
/home/git/gitlab/config/gitlab.yml을 편집하고 user 및 password에 대한 incoming_email: 설정을 제거합니다.

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

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

# SysV init을 사용하는 시스템의 경우
sudo service gitlab restart

::EndTabs

문제 해결

16.6.0에서 이메일 수집이 작동하지 않음

GitLab self-managed 16.6.0에서는 mail_room(이메일 수집)이 시작되지 않도록 방해하는 회귀가 도입되었습니다.

서비스 데스크 및 다른 이메일 회신 기능이 작동하지 않습니다.

문제 432257는 이 문제를 해결하는 과정을 추적합니다.

작업 우회 방법은 다음 명령을 GitLab 설치에서 실행하여 영향을 받은 파일을 패치하는 것입니다:

리눅스 패키지 (Omnibus)

curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff"
patch -p1 -d /opt/gitlab/embedded/service/gitlab-rails < /tmp/mailroom.patch
gitlab-ctl restart mailroom

도커

curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff"
cd /opt/gitlab/embedded/service/gitlab-rails
patch -p1 < /tmp/mailroom.patch
gitlab-ctl restart mailroom

이메일 주소 한도로 인해 제공업체에서 수신 이메일이 거부됨

GitLab 인스턴스가 수신 이메일을 받지 못할 수 있습니다. 이는 일부 이메일 제공업체가 이메일 주소의 로컬 부분(@ 이전)에 64자 한도를 부과하기 때문입니다.

이 한도를 초과하는 주소의 모든 이메일은 거부됩니다.

작업 우회 방법으로는 더 짧은 경로를 유지하는 것입니다:

incoming_email_address의 %{key} 이전에 구성된 로컬 부분을 가능한 짧게 설정하고 31자를 넘지 않도록 하세요.
지정된 프로젝트를 더 높은 그룹 계층에 배치하세요.
그룹 및 프로젝트의 이름을 더 짧게 바꾸세요.

이 기능은 문제 460206에서 추적할 수 있습니다.

수신 이메일

요구 사항

이메일 서브 주소 지정

모든 이메일 수신함

전용 이메일 주소

수락된 헤더

거부된 헤더

설정하기

보안 우려

Linux 패키지 설치

자체 컴파일 설치

구성 예제

Postfix

Gmail

Microsoft Exchange Server

Catch-all mailbox

Dedicated email address

Microsoft Office 365

서브 주소 메일박스

모든 메일박스

전용 이메일 주소

Microsoft Graph

사서함 액세스 제한

Microsoft Graph 구성

암호화된 자격 증명 사용

문제 해결

16.6.0에서 이메일 수집이 작동하지 않음

이메일 주소 한도로 인해 제공업체에서 수신 이메일이 거부됨

도움말

기능 사용 가능성과 제품 평가판

도움받기