수신 이메일

Tier: Free, Premium, Ultimate 제공: 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 및 온프레미스에서 실행할 수 있는 포스트픽스 메일 서버와 같은 제공업체에서 지원됩니다. Microsoft Exchange Server은 서브 주소를 지원하지 않습니다, 그리고 Microsoft Office 365는 기본적으로 서브 주소를 지원하지 않습니다.

note
제공 업체나 서버가 이메일 서브 주소를 지원하는 경우 해당 기능을 사용하는 것을 권장합니다. 전용 이메일 주소는 회신 이메일 기능만 지원하며, 모든 메일함은 GitLab 11.7 이후에 서브 주소와 동일한 기능을 지원하지만, 여전히 서브 주소가 더 좋습니다. 하나의 이메일 주소만 사용하기 때문에 모든 메일함이 GitLab 이외의 다른 목적을 위해 남아 있습니다.

모든 메일함

도메인을 위한 모든 메일함은 메일 서버에서 주소지와 일치하지 않는 도메인으로 보내지는 모든 이메일을 받습니다.

GitLab 11.7부터 모든 메일함은 이메일 서브 주소와 동일한 기능을 지원하지만, 이메일 서브 주소를 추천하는 이유는 모든 메일함을 GitLab 이외의 목적을 위해 예약할 수 있기 때문입니다.

전용 이메일 주소

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

허용된 헤더

  • GitLab 14.9에 도입된 Received 헤더 수용
  • GitLab 16.5에 도입된 Cc 헤더 수용

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

  • To
  • Delivered-To
  • Envelope-To 또는 X-Envelope-To
  • Received
  • 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에 기본 포스트픽스 메일 서버를 설정하려면 포스트픽스 설정 문서에 따릅니다.

보안 고려 사항

caution
수신 이메일을 받기 위해 사용되는 도메인 선택 시 주의가 필요합니다.

예를 들어, 상위 회사 도메인이 hooli.com이고 회사의 모든 직원이 Google Apps를 통해 해당 도메인의 이메일 주소를 갖고 있으며 회사의 비공개 Slack 인스턴스는 유효한 @hooli.com 이메일 주소로 가입해야 하는 경우를 가정해 봅시다.

만약 hooli.com에서 공개 GitLab 인스턴스를 호스팅하고 수신 이메일 도메인을 hooli.com으로 설정하면, 공격자는 Slack 가입 시 프로젝트의 고유 주소를 사용하여 Slack 가입용 이메일을 회신하는 것으로 “이메일로 새 이슈 생성” 또는 “이메일로 새 Merge Request 생성” 기능을 악용할 수 있습니다. 이는 새 이슈나 Merge Request을 공격자가 소유한 프로젝트에 생성하게 하여 공격자가 확인 링크를 클릭하고 회사의 비공개 Slack 인스턴스에서 계정을 확인할 수 있게 합니다.

보안상의 이유로 incoming.hooli.com과 같은 하위 도메인에서 수신 이메일을 받도록 하고 *.hooli.com과 같이 이메일 도메인만을 기반으로 인증하는 서비스를 사용하지 않도록 하거나, hooli-gitlab.com과 같이 GitLab 이메일 통신을 위한 전용 도메인을 사용하도록 하는 것이 좋습니다.

이와 관련된 실제 예제에 대한 GitLab 이슈 #30366을 참조하세요.

caution
스팸을 줄이기 위해 구성된 메일 서버를 사용할 때 주의하세요. 예를 들어 기본 설정에서 실행 중인 포스트픽스 메일 서버는 남용될 수 있습니다. 구성된 메일함으로 수신된 모든 메시지는 처리되며, 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 init 스크립트를 사용하여 GitLab을 관리하는 경우:

  1. /etc/default/gitlab의 init 스크립트에서 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"

# 이메일 계정 사용자 이름
# 제3자 제공업체의 경우 일반적으로 전체 이메일 주소입니다.
# 자체 호스트된 이메일 서버의 경우 주로 이메일 주소의 사용자 부분입니다.
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를 사용하는 경우 삭제된 메일이 전달 후 일정 시간이 지나면 자동으로 제거되기 때문에 true로 설정하세요.
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"
    
    # 이메일 계정 사용자 이름
    # 제3자 제공업체의 경우 일반적으로 전체 이메일 주소입니다.
    # 자체 호스트된 이메일 서버의 경우 주로 이메일 주소의 사용자 부분입니다.
    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를 사용하는 경우 삭제된 메일이 전달 후 일정 시간이 지나면 자동으로 제거되기 때문에 true로 설정하세요.
    delete_after_delivery: true
    
    # 삭제된 메일이 표시된 후 메일함에서 영구적으로 제거(소멸)되는지 여부
    # IMAP에만 적용됩니다. Microsoft Graph는 삭제된 메일을 자동으로 소멸합니다.
    expunge_deleted: true

Gmail

Gmail/Google Workspace의 예시 구성입니다. mailbox gitlab-incoming@gmail.com를 가정합니다.

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

Linux 패키지 설치 예시:

gitlab_rails['incoming_email_enabled'] = true

# %{key} 플레이스홀더를 포함한 전체 메일 주소는 변경된 항목을 참조하기 위해 치환될 것입니다. 
# 이 %{key}는 전자메일 주소 내에서 해당되는 (%{key} 앞에 `@`가 오기 전까지) 곳에 완전하게 포함되어야 합니다.
# 예를 들어: emailaddress+%{key}@gmail.com.
gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@gmail.com"

# 이메일 계정 사용자명
# 제3자 제공업체의 경우 전체 이메일 주소가 일반적입니다.
# 자체 호스트된 이메일 서버의 경우 이메일 주소의 사용자 부분이 일반적입니다.
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

# 수신 메일이 도착할 메일함. 대개 "수신함"입니다.
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

# 메시지를 삭제로 표시한 후 배달 후에 메일함에서 메시지를 완전히 삭제(expunge)할지 여부
# IMAP에만 적용됩니다. Microsoft Graph는 삭제된 메시지를 자동으로 삭제(expunge)합니다.
gitlab_rails['incoming_email_expunge_deleted'] = true

자체 컴파일 설치 예시:

incoming_email:
    enabled: true
    
    # %{key} 플레이스홀더를 포함한 전체 메일 주소는 변경된 항목을 참조하기 위해 치환될 것입니다. 
    # 이 %{key}는 전자메일 주소 내에서 해당되는 (%{key} 앞에 `@`가 오기 전까지) 곳에 완전하게 포함되어야 합니다.
    # 예를 들어: emailaddress+%{key}@gmail.com.
    address: "gitlab-incoming+%{key}@gmail.com"
    
    # 이메일 계정 사용자명
    # 제3자 제공업체의 경우 전체 이메일 주소가 일반적입니다.
    # 자체 호스트된 이메일 서버의 경우 이메일 주소의 사용자 부분이 일반적입니다.
    user: "gitlab-incoming@gmail.com"
    # 이메일 계정 비밀번호
    password: "[REDACTED]"
    
    # IMAP 서버 호스트
    host: "imap.gmail.com"
    # IMAP 서버 포트
    port: 993
    # IMAP 서버에서 SSL을 사용하는지 여부
    ssl: true
    # IMAP 서버에서 StartTLS를 사용하는지 여부
    start_tls: false
    
    # 수신 메일이 도착할 메일함. 대개 "수신함"입니다.
    mailbox: "inbox"
    # IDLE 명령 시간 초과
    idle_timeout: 60
    
    # IMAP 대신 Microsoft Graph를 사용하는 경우, 삭제된 메시지가 시간이 지난 후 자동으로 삭제되기 때문에
    # 휴지통에 메시지를 보관하려면 이 값을 false로 설정합니다.
    delete_after_delivery: true
    
    # 메시지를 삭제로 표시한 후 배달 후에 메일함에서 메시지를 완전히 삭제(expunge)할지 여부
    expunge_deleted: true

Microsoft Exchange Server

IMAP을 활성화한 Microsoft Exchange Server의 예시 구성입니다. Exchange는 서브 주소 지원이 없기 때문에 두 가지 옵션이 존재합니다:

Catch-all mailbox

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

Linux 패키지 설치 예시:

gitlab_rails['incoming_email_enabled'] = true

# %{key} 플레이스홀더를 포함한 전체 메일 주소는 변경된 항목을 참조하기 위해 치환될 것입니다. 
# 이 %{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는 삭제된 메시지를 자동으로 삭제(expunge)합니다.
gitlab_rails['incoming_email_expunge_deleted'] = true

자체 컴파일 설치 예시:

incoming_email:
    enabled: true
    
    # %{key} 플레이스홀더를 포함한 전체 메일 주소는 변경된 항목을 참조하기 위해 치환될 것입니다. 
    # 이 %{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

    # IMAP 대신 Microsoft 그래프를 사용하는 경우, 일정 시간이 경과한 후에 삭제된 메시지가 자동으로 삭제되므로
    # 메시지를 휴지통에 보관하려면 false로 설정합니다.
    delete_after_delivery: true

    # 메시지를 삭제로 표시한 후 배달 후에 메일함에서 메시지를 완전히 삭제(expunge)할지 여부
    expunge_deleted: true
전용 이메일 주소

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

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

리눅스 패키지 설치 예시:

gitlab_rails['incoming_email_enabled'] = true

# Exchange는 하위 주소 지원을 하지 않으며, 우리는 모든 메일함에서 메일을 수신하는 것이 아니므로 %{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는 하위 주소 지원을 하지 않으며, 우리는 모든 메일함에서 메일을 수신하는 것이 아니므로 %{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
    
    # IMAP 대신 Microsoft 그래프를 사용하는 경우, 삭제된 메시지가 일정 시간 후 자동으로 제거되므로
    # 이를 거부하려면 false로 설정합니다.
    delete_after_delivery: true
    
    # 메시지가 전달된 후 삭제되었을 때 메일함에서 영구적으로 메시지를 제거할지 여부
    expunge_deleted: true

Microsoft Office 365

IMAP가 활성화된 Microsoft Office 365의 예시 구성:

하위 주소 메일함

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

이 PowerShell 명령어 시리즈는 Office 365의 조직 수준에서 하위 주소 사용을 가능하게 합니다. 이를 통해 조직의 모든 메일함이 하위 주소 메일을 수신할 수 있습니다.

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

  1. PowerShell 갤러리에서 ExchangeOnlineManagement 모듈을 다운로드하고 설치합니다.
  2. 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"

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

리눅스 패키지 설치 예시는 모든 메일함이 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.com"
    
    # 이메일 계정 사용자 이름
    # 일반적으로 이는 사용자 주체 이름(UPN)입니다
    user: "incoming@ad-domain.example.com"
    # 이메일 계정 비밀번호
    password: "[REDACTED]"
    
    # IMAP 서버 호스트
    host: "outlook.office365.com"
    # IMAP 서버 포트
    port: 993
    # IMAP 서버가 SSL을 사용하는지 여부
    ssl: true
    
    # 메시지가 전달된 후 삭제되었을 때 메일함에서 영구적으로 메시지를 제거할지 여부
    expunge_deleted: true
전용 이메일 주소
note
이메일로 회신만 지원됩니다. 서비스 데스크는 지원할 수 없습니다.

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

gitlab_rails['incoming_email_enabled'] = true

gitlab_rails['incoming_email_address'] = "incoming@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

# 메시지가 전달된 후 삭제되었을 때 메일함에서 메시지를 영구적으로 제거(expunge)할지 여부
gitlab_rails['incoming_email_expunge_deleted'] = true

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

incoming_email:
    enabled: true
    
    address: "incoming@office365.example.com"
    
    # 이메일 계정 사용자명
    # 일반적으로 이는 사용자 주체 이름(UPN)입니다.
    user: "incoming@office365.example.com"
    # 이메일 계정 비밀번호
    password: "[REDACTED]"
    
    # IMAP 서버 호스트
    host: "outlook.office365.com"
    # IMAP 서버 포트
    port: 993
    # IMAP 서버에서 SSL을 사용하는지 여부
    ssl: true
    
    # 메시지가 전달된 후 삭제되었을 때 메일함에서 메시지를 영구적으로 제거(expunge)할지 여부
    expunge_deleted: true

마이크로소프트 그래프

GitLab은 마이크로소프트 그래프 API를 사용하여 IMAP 대신에 수신 이메일을 읽을 수 있습니다. 왜냐하면 마이크로소프트가 기본 인증과 함께 IMAP 사용을 폐기하고 있기 때문에, 새로운 마이크로소프트 Exchange Online 메일함에 대해서는 마이크로소프트 그래프 API가 필요합니다.

GitLab을 마이크로소프트 그래프에 구성하려면 모든 메일함에 대해 Mail.ReadWrite 권한을 갖는 Azure Active Directory의 OAuth 2.0 애플리케이션을 등록해야 합니다. 자세한 내용은 MailRoom 단계별 가이드마이크로소프트 지침을 참조하세요.

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

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

서비스 어카운트로서 MailRoom이 작동하려면 Azure Active Directory에서 생성하는 애플리케이션이 모든 메일함의 메일을 읽고 쓰는 Mail.ReadWrite 속성을 설정해야 합니다.

보안 관련 우려를 완화하기 위해 모든 계정에 대해 메일함 액세스를 제한하는 애플리케이션 액세스 정책을 구성하는 것을 권장합니다. 자세한 내용은 마이크로소프트 문서를 참조하세요.

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

마이크로소프트 그래프 구성
gitlab_rails['incoming_email_enabled'] = true

# '%{key}' 플레이스홀더를 참조하기 위해 대체될 이메일 주소, 전체적으로 이 %{key}는 다른 값으로 대체되지 않고 주소의 "user" 부분(이메일 주소의 `@` 앞)에 나타나야 합니다.
# 예시: emailaddress+%{key}@example.onmicrosoft.com.
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 for US Government 또는 다른 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': '<YOUR-TENANT-ID>',
   'client_id': '<YOUR-CLIENT-ID>',
   'client_secret': '<YOUR-CLIENT-SECRET>',
   'poll_interval': 60  # 선택 사항
}

마이크로소프트 그래프 API는 아직 자체 컴파일 설치에서 지원되지 않습니다. 자세한 내용은 이 이슈를 참조하세요.

암호화된 자격 증명 사용

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

전제 조건:

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

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

  • user
  • password
Linux 패키지 (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를 편집하고 emailpassword에 대한 incoming_email 설정을 제거합니다.
  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['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에서 emailpassword에 대한 incoming_email 설정을 제거합니다.
  5. 파일을 저장하고 GitLab을 다시 시작합니다:

    docker compose up -d
    
자체 컴파일 (소스)
  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에 대한 incoming_email: 설정을 제거합니다.
  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 (이메일 수신)을 시작하는 데 제약이 발생하는 리그레션이 소개되었습니다. 서비스 데스크 및 기타 이메일 응답 기능이 작동하지 않습니다. 이 문제를 해결하기 위해 Issue 432257가 추적되고 있습니다.

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

Linux 패키지 (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