수신 이메일

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

GitLab에는 수신 이메일 메시지를 기반으로 하는 여러 기능이 있습니다:

  • 이메일로 회신: GitLab 사용자가 알림 이메일에 회신하여 이슈 및 Merge Request에 댓글을 남길 수 있습니다.
  • 이메일로 새 이슈 생성: GitLab 사용자가 사용자별 이메일 주소로 이메일을 보내어 새 이슈를 생성할 수 있습니다.
  • 이메일로 새 Merge Request 생성: GitLab 사용자가 사용자별 이메일 주소로 이메일을 보내어 새 Merge Request을 생성할 수 있습니다.
  • 서비스 데스크: GitLab을 통해 고객에게 이메일 지원을 제공합니다.

요구 사항

GitLab 인스턴스를 위한 의도된 메시지만 받는 이메일 주소를 사용하는 것을 권장합니다. GitLab을 위해 의도되지 않은 수신 이메일 메시지는 거부 알림을 받게 됩니다.

수신 이메일 메시지 처리에는 IMAP를 사용할 수 있는 이메일 계정이 필요합니다. GitLab에서는 다음 세 가지 전략 중 하나가 필요합니다:

  • 이메일 서브-주소(권장)
  • 전체 메일함
  • 전용 이메일 주소(회신 전용 지원)

각 옵션에 대해 알아보겠습니다.

이메일 서브-주소

서브-주소user+arbitrary_tag@example.com로 보낸 이메일이 user@example.com의 메일함으로 전달되는 메일 서버 기능입니다. Gmail, Google Apps, Yahoo! Mail, Outlook.com 및 Postfix 메일 서버와 같은 제공업체에서 지원되고 있으며 온프레미스에서 실행할 수 있는 Microsoft Exchange Server에서는 서브-주소를 지원하지 않습니다. Microsoft Office 365는 기본적으로 서브-주소를 지원하지 않습니다.

note
제공업체나 서버에서 이메일 서브-주소를 지원하는 경우 사용하는 것을 권장합니다. 전용 이메일 주소는 회신 전용 기능만 지원합니다. 전체 메일함은 서브-주소와 동일한 기능을 지원하지만, 서브-주소를 사용하는 것이 여전히 선호됩니다. 왜냐하면 단 하나의 이메일 주소만 사용되기 때문에 전체 메일함은 GitLab 이외의 다른 용도로 남겨둘 수 있기 때문입니다.

전체 메일함

도메인에 대한 전체 메일함은 메일 서버에서 기존 주소와 일치하지 않는 해당 도메인으로 보낸 모든 이메일을 수신합니다.

전체 메일함은 이메일 서브-주소와 동일한 기능을 지원하지만, 이메일 서브-주소를 사용하여 전체 메일함을 다른 용도로 예약할 수 있도록 하는 것이 여전히 권장됩니다.

전용 이메일 주소

이 솔루션을 설정하려면 사용자의 회신에 대한 전용 이메일 주소를 생성해야 합니다. 그러나 이 방법은 회신 기능만 지원하며 수신 이메일의 다른 기능을 지원하지는 않습니다.

허용된 헤더

  • GitLab 16.5에서 도입된 Cc 헤더 수락
  • GitLab 17.0에서 도입된 X-Original-To 헤더 수락

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

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

References 헤더도 수락되지만, 기존 토론 스레드와의 관련을 위해 사용됩니다. 이메일에 의한 이슈 생성에는 사용되지 않습니다.

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

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

  • 주소가 BCC 필드에 있는 경우
  • 이메일이 전달된 경우

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

거부된 헤더

자동 이메일 시스템에서의 불필요한 이슈 생성을 방지하기 위해 GitLab은 다음 헤더를 포함하는 모든 수신 이메일 메시지를 무시합니다:

  • 값이 no가 아닌 Auto-Submitted 헤더
  • 값이 yesX-Autoreply 헤더

설정

Gmail/Google Apps에 대한 수신 이메일을 사용하려면 IMAP 액세스가 활성화되어 있고 보안 수준이 낮은 앱이 계정에 액세스하도록 허용되어 있는지 또는 2단계 인증을 사용하도록 변경하여 애플리케이션 암호를 사용하십시오.

Office 365를 사용하려면, 2단계 인증이 활성화된 경우 기존의 비밀번호 대신 앱 암호를 사용하십시오.

Ubuntu에서 IMAP 액세스가 활성화된 기본적인 Postfix 메일 서버를 설정하려면 Postfix 설정 문서를 확인하십시오.

보안에 대한 고려 사항

caution
수신 이메일을 받을 때 사용할 도메인을 선택할 때 주의하십시오.

예를 들어, 상위 회사 도메인이 hooli.com인 경우, 회사의 모든 직원이 Google Apps을 통해 해당 도메인의 이메일 주소를 갖고 있으며 회사의 사설 Slack 인스턴스에는 유효한 @hooli.com 이메일 주소가 필요합니다.

그리고 hooli.com에서 공개 GitLab 인스턴스를 호스팅하고 수신 이메일 도메인을 hooli.com으로 설정한 경우, 공격자는 사설 Slack에 가입할 때 프로젝트의 고유 주소를 이메일로 사용함으로써 “이메일로 새 이슈 생성” 또는 “이메일로 새 Merge Request 생성” 기능을 남용할 수 있습니다. 그러면 확인 이메일이 전송되어 공격자가 새 이슈나 Merge Request을 프로젝트에서 선택하고 회사의 사설 Slack 인스턴스에서 계정을 확인할 수 있습니다.

따라서 incoming.hooli.com과 같은 하위 도메인을 사용하여 수신 이메일을 받고, *.hooli.com과 같은 이메일 도메인 기반의 서비스를 사용하지 않도록 하는 것이 좋습니다. 또는 hooli-gitlab.com과 같이 GitLab 이메일 통신을 위해 전용 도메인을 사용하십시오.

이러한 악용 사례의 실제 예시는 GitLab 이슈 #30366에서 확인할 수 있습니다.

caution
스팸을 줄이기 위해 설정이 구성된 메일 서버를 사용하십시오. 예를 들어, 기본 구성에서 실행 중인 Postfix 메일 서버는 남용될 수 있습니다. 구성된 메일함에 수신된 모든 메시지가 처리되며, GitLab을 위해 의도되지 않은 메시지는 거부 알림을 받게 됩니다. 발신자 주소가 위조된 경우 거부 알림이 위조된 FROM 주소로 전송되어 해당 메일 서버의 IP나 도메인이 차단 디렉터리에 나타날 수 있습니다.
caution
사용자는 인스턴스에 대한 두 요소 인증을 강제했더라도 수신 이메일 기능을 사용할 수 있습니다.

Linux 패키지 설치

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

  2. 변경 사항이 적용되도록 GitLab을 다시 구성하세요:

    sudo gitlab-ctl reconfigure
       
    # 처음으로 활성화 또는 비활성화하는 경우에 필요하나 암호 변경 시에는 필요하지 않습니다. 자세한 내용은 https://gitlab.com/gitlab-org/gitlab-foss/-/issues/23560#note_61966788에서 확인하세요.
    sudo gitlab-ctl restart
    
  3. 모든 것이 올바르게 구성되었는지 확인하세요:

    sudo gitlab-rake gitlab:incoming_email:check
    

이제 이메일로 회신할 수 있어야 합니다.

직접 컴파일한 설치

  1. GitLab 설치 디렉터리로 이동하세요:

    cd /home/git/gitlab
    
  2. gitlab-mail_room 젬을 매뉴얼으로 설치하세요:

    gem install gitlab-mail_room
    

    참고: 이 단계는 스레드 데드락을 피하고 최신 MailRoom 기능을 지원하기 위해 필요합니다. 자세한 내용은 이 설명을 참조하세요.

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

시스템디 유닛을 사용하여 GitLab을 관리하는 경우:

  1. gitlab.targetgitlab-mailroom.service를 의존성으로 추가하세요:

    sudo systemctl edit gitlab.target
    

    열리는 편집기에서 다음을 추가하고 파일을 저장하세요:

    [Unit]
    Wants=gitlab-mailroom.service
    
  2. 만약 Redis와 PostgreSQL을 동일한 머신에서 실행 중이라면, Redis에 대한 의존성을 추가해야 합니다. 다음을 실행하세요:

    sudo systemctl edit gitlab-mailroom.service
    

    열리는 편집기에서 다음을 추가하고 파일을 저장하세요:

    [Unit]
    Wants=redis-server.service
    After=redis-server.service
    
  3. gitlab-mailroom.service를 시작하세요:

    sudo systemctl start gitlab-mailroom.service
    
  4. 모든 것이 올바르게 구성되었는지 확인하세요:

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

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

  1. 이닛 스크립트(/etc/default/gitlab에서)에서 mail_room을 활성화하세요:

    sudo mkdir -p /etc/default
    echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab
    
  2. GitLab을 다시 시작하세요:

    sudo service gitlab restart
    
  3. 모든 것이 올바르게 구성되었는지 확인하세요:

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

이제 이메일로 회신할 수 있어야 합니다.

구성 예시

포스트픽스

포스트픽스 메일 서버의 예시 구성. incoming@gitlab.example.com 메일함을 전제로합니다.

Linux 패키지 설치의 예시:

gitlab_rails['incoming_email_enabled'] = true

# %{key} 플레이스홀더를 참조하기 위해 대체될 이메일 주소(예: emailaddress+%{key}@gitlab.example.com). 플레이스홀더는 주소의 "user" 부분에 포함되어야 합니다.
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

# 삭제된 이메일이 일정 시간 후에 자동으로 제거되기 때문에 수신함에 메시지를 보관하려면 false로 설정하세요. (IMAP만 해당)
gitlab_rails['incoming_email_delete_after_delivery'] = true

# 수신된 이메일이 삭제 표시되고 제거될 때 메일함에서 메시지를 영구적으로 제거할지 여부 (IMAP에만 해당). Microsoft Graph는 삭제된 메시지를 자동으로 제거합니다.
gitlab_rails['incoming_email_expunge_deleted'] = true

직접 컴파일한 설치의 예시:

incoming_email:
    enabled: true
    
    # %{key} 플레이스홀더를 참조하기 위해 대체될 이메일 주소(예: emailaddress+%{key}@gitlab.example.com). 플레이스홀더는 주소의 "user" 부분에 포함되어야 합니다.
    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
    
    # 삭제된 이메일이 일정 시간 후에 자동으로 제거되기 때문에 수신함에 메시지를 보관하려면 false로 설정하세요. (IMAP만 해당)
    delete_after_delivery: true
    
    # 수신된 이메일이 삭제 표시되고 제거될 때 메일함에서 메시지를 영구적으로 제거할지 여부 (IMAP에만 해당). Microsoft Graph는 삭제된 메시지를 자동으로 제거합니다.
    expunge_deleted: true

Gmail

Gmail/Google Workspace의 예시 구성. gitlab-incoming@gmail.com 메일함을 전제로합니다.

note
incoming_email_email은 Gmail 별칭 계정일 수 없습니다.

Linux 패키지 설치의 예시:

gitlab_rails['incoming_email_enabled'] = true

# %{key} 플레이스홀더를 참조하기 위해 대체될 이메일 주소(예: emailaddress+%{key}@gmail.com). 플레이스홀더는 주소의 "user" 부분에 포함되어야 합니다.
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

# 삭제된 이메일이 일정 시간 후에 자동으로 제거되기 때문에 수신함에 메시지를 보관하려면 false로 설정하세요.
gitlab_rails['incoming_email_delete_after_delivery'] = true

# 수신된 이메일이 삭제 표시되고 제거될 때 메일함에서 메시지를 영구적으로 제거할지 여부 (IMAP에만 해당). Microsoft Graph는 삭제된 메시지를 자동으로 제거합니다.
gitlab_rails['incoming_email_expunge_deleted'] = true

직접 컴파일한 설치의 예시:

incoming_email:
    enabled: true
    
    # %{key} 플레이스홀더를 참조하기 위해 대체될 이메일 주소(예: emailaddress+%{key}@gmail.com). 플레이스홀더는 주소의 "user" 부분에 포함되어야 합니다.
    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
    
    # 삭제된 이메일이 일정 시간 후에 자동으로 제거되기 때문에 수신함에 메시지를 보관하려면 false로 설정하세요.
    delete_after_delivery: true
    
    # 수신된 이메일이 삭제 표시되고 제거될 때 메일함에서 메시지를 영구적으로 제거할지 여부 (IMAP에만 해당). Microsoft Graph는 삭제된 메시지를 자동으로 제거합니다.
    expunge_deleted: true

Microsoft Exchange Server

Microsoft Exchange Server를 사용한 IMAP 기능이 활성화된 예제 구성입니다. Exchange는 하위 주소 지원이 없기 때문에 두 가지 옵션만 사용할 수 있습니다.

Catch-all mailbox

Catch-all mailbox incoming@exchange.example.com을 가정합니다.

Linux 패키지 설치에 대한 예제:

gitlab_rails['incoming_email_enabled'] = true

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

# 이메일 계정 사용자 이름
# 일반적으로 이는 사용자 주체 이름(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.
    # 플레이스홀더는 주소의 "사용자" 부분( `@` 앞)에 나타나야 합니다.
    # Exchange는 하위 주소 지원이 없기 때문에 catch-all 메일박스를 사용해야 합니다.
    address: "incoming-%{key}@exchange.example.com"
    
    # 이메일 계정 사용자 이름
    # 일반적으로 이는 사용자 주체 이름(UPN)입니다.
    user: "incoming@ad-domain.example.com"
    # 이메일 계정 비밀번호
    password: "[REDACTED]"
    
    # IMAP 서버 호스트
    host: "exchange.example.com"
    # IMAP 서버 포트
    port: 993
    # IMAP 서버가 SSL을 사용하는지 여부
    ssl: true
    
    # Microsoft Graph를 사용하는 경우에는 삭제된 메시지를 일정 시간 후에 자동으로 영구적으로 제거하므로 false로 설정합니다.
    delete_after_delivery: true
    
    # 메일이 전달된 후 삭제된 메시지를 영구적으로 제거하는 여부
    expunge_deleted: true
Dedicated email address
note
답장 이메일만 지원합니다. 서비스 데스크를 지원할 수 없습니다.

Dedicated email address incoming@exchange.example.com을 가정합니다.

Linux 패키지 설치에 대한 예제:

gitlab_rails['incoming_email_enabled'] = true

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

# 이메일 계정 사용자 이름
# 일반적으로 이는 사용자 주체 이름(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"
    
    # 이메일 계정 사용자 이름
    # 일반적으로 이는 사용자 주체 이름(UPN)입니다.
    user: "incoming@ad-domain.example.com"
    # 이메일 계정 비밀번호
    password: "[REDACTED]"
    
    # IMAP 서버 호스트
    host: "exchange.example.com"
    # IMAP 서버 포트
    port: 993
    # IMAP 서버가 SSL을 사용하는지 여부
    ssl: true
    
    # Microsoft Graph를 사용하는 경우에는 삭제된 메시지를 일정 시간 후에 자동으로 영구적으로 제거하므로 false로 설정합니다.
    delete_after_delivery: true
    
    # 메일이 전달된 후 삭제된 메시지를 영구적으로 제거하는 여부
    expunge_deleted: true

Microsoft Office 365

Microsoft Office 365를 사용한 IMAP 기능이 활성화된 예제 구성입니다.

하위 주소 지원 메일박스
note
2020년 9월부로 하위 주소 지원 기능이 Office 365에 추가되었습니다. 이 기능은 기본적으로 활성화되어 있지 않으며 PowerShell을 통해 활성화해야 합니다.

Office 365의 조직 수준에서 하위 주소 지원을 활성화하는 일련의 PowerShell 명령입니다. 이를 통해 조직의 모든 메일박스가 하위 주소가 포함된 메일을 수신할 수 있습니다.

하위 주소를 활성화하려면:

  1. PowerShell 갤러리에서 ExchangeOnlineManagement 모듈을 다운로드하고 설치합니다.
  2. PowerShell에서 다음 명령을 실행합니다:

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

Linux 패키지 설치에 대한 이 예제는 메일박스를 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"

# 이메일 계정 사용자 이름
# 일반적으로 이는 사용자 주체 이름(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"
    
    # 이메일 계정 사용자 이름
    # 일반적으로 이는 사용자 주체 이름(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

# 메일이 전달된 후 삭제되었을 때 메일함에서 메시지를 완전히 제거(expunge)할지 여부
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)할지 여부
    expunge_deleted: true
전용 이메일 주소
note
이메일로 회신만 지원합니다. 서비스 데스크는 지원하지 않습니다.

이 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

# 메일이 전달된 후 삭제되었을 때 메일함에서 메시지를 완전히 제거(expunge)할지 여부
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)할지 여부
    expunge_deleted: true

Microsoft Graph

GitLab은 IMAP 대신 Microsoft Graph API를 사용하여 수신 이메일을 읽을 수 있습니다. Microsoft가 Basic Authentication으로의 IMAP 사용을 폐지하고 있기 때문에 새로운 Microsoft Exchange Online 메일함에 대해 Microsoft Graph API가 필요합니다.

Microsoft Graph를 위해 GitLab을 구성하려면, 모든 메일함에 대해 Mail.ReadWrite 권한을 갖는 Azure Active Directory에 OAuth 2.0 애플리케이션을 등록해야 합니다. 자세한 내용은 MailRoom 스텝별 가이드Microsoft 설명서를 참조하세요.

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

  • Azure Active Directory의 테넌트 ID
  • OAuth 2.0 애플리케이션의 클라이언트 ID
  • OAuth 2.0 애플리케이션의 클라이언트 비밀번호
메일함 접근 제한

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

보안 문제를 완화하기 위해, Microsoft 설명서에 설명된 대로 모든 계정의 메일함 접근을 제한하는 애플리케이션 액세스 정책을 구성하는 것이 좋습니다.

이 Linux 패키지 설치 예제는 다음 메일함을 사용한다고 가정합니다: incoming@example.onmicrosoft.com.

Microsoft Graph 구성
  • GitLab 14.9에서 도입된 대체 Azure 배포.
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': '<당신의 테넌트 ID>',
   'client_id': '<당신의 클라이언트 ID>',
   'client_secret': '<당신의 클라이언트 비밀번호>',
   'poll_interval': 60  # 선택 사항
}

미국 정부용 Microsoft Cloud나 다른 Azure 배포를 사용하는 경우, azure_ad_endpointgraph_endpoint 설정을 구성하세요.

  • Microsoft Cloud for US Government를 위한 예시:
gitlab_rails['incoming_email_inbox_options'] = {
   'azure_ad_endpoint': 'https://login.microsoftonline.us',
   'graph_endpoint': 'https://graph.microsoft.us',
   'tenant_id': '<당신의 테넌트 ID>',
   'client_id': '<당신의 클라이언트 ID>',
   'client_secret': '<당신의 클라이언트 비밀번호>',
   'poll_interval': 60  # 선택 사항
}

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

암호화된 자격 증명 사용

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

필수 컴포넌트:

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

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

  • user
  • password
Linux package (Omnibus)
  1. 초기에 /etc/gitlab/gitlab.rb에서 들어오는 이메일 구성이 다음과 같은 경우:

    gitlab_rails['incoming_email_email'] = "incoming-email@mail.example.com"
    gitlab_rails['incoming_email_password'] = "examplepassword"
    
  2. 암호화된 비밀 수정:

    sudo gitlab-rake gitlab:incoming_email:secret:edit EDITOR=vim
    
  3. 들어오는 이메일 비밀의 평문 내용 입력:

    user: 'incoming-email@mail.example.com'
    password: 'examplepassword'
    
  4. /etc/gitlab/gitlab.rb를 편집하고 이메일비밀번호에 대한 들어오는 이메일 설정 제거
  5. 파일 저장 및 GitLab 재구성:

    sudo gitlab-ctl reconfigure
    
Helm chart (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['incoming_email_email'] = "incoming-email@mail.example.com"
            gitlab_rails['incoming_email_password'] = "examplepassword"
    
  2. 컨테이너 내부로 이동하여 암호화된 비밀 수정:

    sudo docker exec -t <container_name> bash
    gitlab-rake gitlab:incoming_email:secret:edit EDITOR=editor
    
  3. 들어오는 이메일 비밀의 평문 내용 입력:

    user: 'incoming-email@mail.example.com'
    password: 'examplepassword'
    
  4. docker-compose.yml을 편집하고 들어오는 이메일 설정에서 이메일비밀번호 제거
  5. 파일 저장 및 GitLab 재시작:

    docker compose up -d
    
Self-compiled (source)
  1. 초기에 /home/git/gitlab/config/gitlab.yml에서 들어오는 이메일 구성이 다음과 같은 경우:

    production:
      incoming_email:
        user: 'incoming-email@mail.example.com'
        password: 'examplepassword'
    
  2. 암호화된 비밀 수정:

    bundle exec rake gitlab:incoming_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production
    
  3. 들어오는 이메일 비밀의 평문 내용 입력:

    user: 'incoming-email@mail.example.com'
    password: 'examplepassword'
    
  4. /home/git/gitlab/config/gitlab.yml을 편집하고 들어오는 이메일: 설정에서 userpassword 제거
  5. 파일 저장 및 GitLab 및 Mailroom 재시작

    # systemd를 실행 중인 시스템의 경우
    sudo systemctl restart gitlab.target
       
    # SysV init를 실행 중인 시스템의 경우
    sudo service gitlab restart
    

문제 해결

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

GitLab Self-Managed의 16.6.0에서 mail_room (이메일 수용) 시작을 방해하는 회귀가 도입되었습니다. 서비스 데스크 및 다른 이메일로 회신 기능이 작동하지 않습니다. 이 문제를 해결하기 위해 이슈 432257가 추적되고 있습니다.

해결책은 GitLab 설치에서 다음 명령을 실행하여 영향받는 파일을 패치하는 것입니다:

Linux package (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
Docker
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