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

• 이메일로 답글: GitLab 사용자가 알림 이메일에 답장해 이슈와 머지 리퀘스트에 댓글을 달 수 있습니다.
• 이메일로 새 이슈 생성: GitLab 사용자가 사용자별 이메일 주소로 이메일을 보내 새 이슈를 생성할 수 있습니다.
• 이메일로 새 머지 리퀘스트 생성: GitLab 사용자가 사용자별 이메일 주소로 이메일을 보내 새 머지 리퀘스트를 생성할 수 있습니다.
• Service Desk: GitLab을 통해 고객에게 이메일 지원을 제공합니다.

요구 사항#

GitLab 인스턴스를 대상으로 하는 메시지만 수신하는 이메일 주소를 사용해야 합니다. GitLab을 위한 것이 아닌 수신 이메일 메시지는 거부 알림을 받습니다.

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

• 이메일 서브 주소 지정(권장)
• Catch-all 메일박스
• 전용 이메일 주소(이메일로 답글만 지원)

각 옵션을 살펴봅니다.

이메일 서브 주소 지정#

서브 주소 지정은 user+arbitrary_tag@example.com으로 보낸 이메일이 user@example.com의 메일박스로 전달되는 메일 서버 기능입니다. Gmail, Google Apps, Yahoo! Mail, Outlook.com, iCloud와 같은 공급자, 그리고 온프레미스로 운영할 수 있는 Postfix 메일 서버에서 지원됩니다. Microsoft Exchange Server는 서브 주소 지정을 지원하지 않으며, Microsoft Office 365는 기본적으로 서브 주소 지정을 지원하지 않습니다.

Catch-all 메일박스#

도메인의 Catch-all 메일박스는 메일 서버에 존재하는 어떤 주소와도 일치하지 않는, 해당 도메인으로 주소가 지정된 모든 이메일 메시지를 수신합니다.

Catch-all 메일박스는 이메일 서브 주소 지정과 동일한 기능을 지원하지만, Catch-all 메일박스를 다른 목적으로 남겨둘 수 있도록 이메일 서브 주소 지정을 여전히 사용해야 합니다.

전용 이메일 주소#

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

허용되는 헤더#

히스토리

• GitLab 17.0에서 X-Original-To 헤더 허용이 도입됨.
• GitLab 17.6에서 X-Forwarded-To 헤더 허용이 도입됨.
• GitLab 17.6에서 X-Delivered-To 헤더 허용이 도입됨.

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

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

References 헤더도 허용되지만, 기존 토론 스레드에 이메일 응답을 연결하는 데 특별히 사용되며 이메일로 이슈를 생성하는 데는 사용되지 않습니다.

Service Desk도 허용되는 헤더를 확인합니다.

일반적으로 To 필드에는 기본 수신자의 이메일 주소가 포함됩니다. 다만 다음의 경우에는 구성된 GitLab 이메일 주소가 포함되지 않을 수 있습니다:

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

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

거부되는 헤더#

자동 이메일 시스템으로 인한 원치 않는 이슈 생성을 방지하기 위해, GitLab은 다음 헤더가 포함된 모든 수신 이메일을 무시합니다:

• no가 아닌 값을 가진 Auto-Submitted
• yes 값을 가진 X-Autoreply

설정하기#

수신 이메일에 Gmail / Google Apps를 사용하려면 IMAP 접근이 활성화되어 있고 보안 수준이 낮은 앱의 계정 접근이 허용되어 있는지, 또는 2단계 인증을 켜고 앱 비밀번호를 사용하고 있는지 확인합니다.

Office 365를 사용하고 2단계 인증이 켜져 있는 경우, 메일박스의 일반 비밀번호 대신 앱 비밀번호를 사용하고 있는지 확인합니다.

Ubuntu에서 IMAP 접근이 가능한 기본 Postfix 메일 서버를 설정하려면 Postfix 설정 문서를 참조합니다.

보안 문제#

예를 들어, 최상위 회사 도메인이 hooli.com이라고 가정합니다. 회사의 모든 직원이 Google Workspace를 통해 해당 도메인의 이메일 주소를 가지고 있고, 회사의 프라이빗 Slack 인스턴스는 사용자 계정을 만들 때 유효한 @hooli.com 이메일 주소를 요구합니다.

hooli.com에서 공개용 GitLab 인스턴스도 호스팅하면서 수신 이메일 도메인을 hooli.com으로 설정하면, 공격자가 이메일로 새 이슈 생성 또는 이메일로 새 머지 리퀘스트 생성 기능을 악용하여, 공격자가 소유한 프로젝트의 고유 주소를 Slack 가입 시 이메일 주소로 사용할 수 있습니다. 이렇게 하면 확인 이메일이 전송되어 해당 프로젝트에 새 이슈나 머지 리퀘스트가 생성됩니다. 공격자는 확인 링크를 선택해 회사의 프라이빗 Slack 인스턴스에서 계정을 검증할 수 있게 됩니다.

incoming.hooli.com과 같이 서브도메인에서 수신 이메일을 받아야 하며, *.hooli.com과 같은 이메일 도메인 접근만으로 인증하는 서비스는 사용하지 않아야 합니다. 또는 hooli-gitlab.com과 같이 GitLab 이메일 통신 전용 도메인을 사용합니다.

이 취약점의 실제 사례는 GitLab 이슈 #30366을 참조합니다.

사용자는 먼저 2단계 인증(2FA)으로 본인 인증을 하지 않고도 수신 이메일 기능을 사용할 수 있습니다. 인스턴스에서 2단계 인증을 강제하고 있어도 마찬가지입니다.

Linux 패키지 설치#

1. /etc/gitlab/gitlab.rb에서 incoming_email 섹션을 찾아 기능을 켜고 특정 IMAP 서버와 이메일 계정에 대한 세부 정보를 입력합니다(아래 예제 참조).

2. 변경 사항을 적용하려면 GitLab을 재구성합니다:

   sudo gitlab-ctl reconfigure
   
   # Needed when enabling or disabling for the first time but not for password changes.
   # See 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을 수동으로 설치합니다:

   gem install gitlab-mail_room
   

   [!note] 이 단계는 스레드 교착 상태를 방지하고 최신 MailRoom 기능을 지원하기 위해 필요합니다.

3. config/gitlab.yml에서 incoming_email 섹션을 찾아 기능을 켜고 특정 IMAP 서버와 이메일 계정에 대한 세부 정보를 입력합니다(아래 예제 참조).

systemd 유닛으로 GitLab을 관리하는 경우:

1. gitlab-mailroom.service를 gitlab.target의 의존성으로 추가합니다:

   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
   

이제 이메일로 답글이 작동해야 합니다.

구성 예제#

Postfix#

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

Linux 패키지 설치 예제:

gitlab_rails['incoming_email_enabled'] = true

# The email address including the %{key} placeholder that will be replaced to reference the
# item being replied to. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress+%{key}@gitlab.example.com.
# The placeholder must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "incoming+%{key}@gitlab.example.com"

# Email account username
# With third party providers, this is usually the full email address.
# With self-hosted email servers, this is usually the user part of the email address.
gitlab_rails['incoming_email_email'] = "incoming"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "gitlab.example.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 143
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = false
# Whether the IMAP server uses StartTLS
gitlab_rails['incoming_email_start_tls'] = false

# The mailbox where incoming mail will end up. Usually "inbox".
gitlab_rails['incoming_email_mailbox_name'] = "inbox"
# The IDLE command timeout.
gitlab_rails['incoming_email_idle_timeout'] = 60

# If you are using Microsoft Graph instead of IMAP, set this to false to retain
# messages in the inbox because deleted messages are auto-expunged after some time.
gitlab_rails['incoming_email_delete_after_delivery'] = true

# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
# Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages.
gitlab_rails['incoming_email_expunge_deleted'] = true

소스 컴파일 설치 예제:

incoming_email:
    enabled: true

    # The email address including the %{key} placeholder that will be replaced to reference the
    # item being replied to. This %{key} should be included in its entirety within the email
    # address and not replaced by another value.
    # For example: emailaddress+%{key}@gitlab.example.com.
    # The placeholder must appear in the "user" part of the address (before the `@`).
    address: "incoming+%{key}@gitlab.example.com"

    # Email account username
    # With third party providers, this is usually the full email address.
    # With self-hosted email servers, this is usually the user part of the email address.
    user: "incoming"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "gitlab.example.com"
    # IMAP server port
    port: 143
    # Whether the IMAP server uses SSL
    ssl: false
    # Whether the IMAP server uses StartTLS
    start_tls: false

    # The mailbox where incoming mail will end up. Usually "inbox".
    mailbox: "inbox"
    # The IDLE command timeout.
    idle_timeout: 60

    # If you are using Microsoft Graph instead of IMAP, set this to false to retain
    # messages in the inbox because deleted messages are auto-expunged after some time.
    delete_after_delivery: true

    # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
    # Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages.
    expunge_deleted: true

Gmail#

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

Linux 패키지 설치 예제:

gitlab_rails['incoming_email_enabled'] = true

# The email address including the %{key} placeholder that will be replaced to reference the
# item being replied to. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress+%{key}@gmail.com.
# The placeholder must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@gmail.com"

# Email account username
# With third party providers, this is usually the full email address.
# With self-hosted email servers, this is usually the user part of the email address.
gitlab_rails['incoming_email_email'] = "gitlab-incoming@gmail.com"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "imap.gmail.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true
# Whether the IMAP server uses StartTLS
gitlab_rails['incoming_email_start_tls'] = false

# The mailbox where incoming mail will end up. Usually "inbox".
gitlab_rails['incoming_email_mailbox_name'] = "inbox"
# The IDLE command timeout.
gitlab_rails['incoming_email_idle_timeout'] = 60

# If you are using Microsoft Graph instead of IMAP, set this to false if you want to retain
# messages in the inbox because deleted messages are auto-expunged after some time.
gitlab_rails['incoming_email_delete_after_delivery'] = true

# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
# Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages.
gitlab_rails['incoming_email_expunge_deleted'] = true

소스 컴파일 설치 예제:

incoming_email:
    enabled: true

    # The email address including the %{key} placeholder that will be replaced to reference the
    # item being replied to. This %{key} should be included in its entirety within the email
    # address and not replaced by another value.
    # For example: emailaddress+%{key}@gmail.com.
    # The placeholder must appear in the "user" part of the address (before the `@`).
    address: "gitlab-incoming+%{key}@gmail.com"

    # Email account username
    # With third party providers, this is usually the full email address.
    # With self-hosted email servers, this is usually the user part of the email address.
    user: "gitlab-incoming@gmail.com"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "imap.gmail.com"
    # IMAP server port
    port: 993
    # Whether the IMAP server uses SSL
    ssl: true
    # Whether the IMAP server uses StartTLS
    start_tls: false

    # The mailbox where incoming mail will end up. Usually "inbox".
    mailbox: "inbox"
    # The IDLE command timeout.
    idle_timeout: 60

    # If you are using Microsoft Graph instead of IMAP, set this to falseto retain
    # messages in the inbox because deleted messages are auto-expunged after some time.
    delete_after_delivery: true

    # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
    # Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages.
    expunge_deleted: true

Microsoft Exchange Server#

IMAP이 켜진 Microsoft Exchange Server 구성 예제입니다. Exchange는 서브 주소 지정을 지원하지 않으므로, 다음 두 가지 옵션만 있습니다:

• Catch-all 메일박스 (Exchange 전용에 권장)
• 전용 이메일 주소 (이메일로 답글만 지원)

Catch-all 메일박스#

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

Linux 패키지 설치 예제:

gitlab_rails['incoming_email_enabled'] = true

# The email address including the %{key} placeholder that will be replaced to reference the
# item being replied to. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress-%{key}@exchange.example.com.
# The placeholder must appear in the "user" part of the address (before the `@`).
# Exchange does not support sub-addressing, so a catch-all mailbox must be used.
gitlab_rails['incoming_email_address'] = "incoming-%{key}@exchange.example.com"

# Email account username
# Typically this is the userPrincipalName (UPN)
gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "exchange.example.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true

# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
# Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages.
gitlab_rails['incoming_email_expunge_deleted'] = true

소스 컴파일 설치 예제:

incoming_email:
    enabled: true

    # The email address including the %{key} placeholder that will be replaced to reference the
    # item being replied to. This %{key} should be included in its entirety within the email
    # address and not replaced by another value.
    # For example: emailaddress-%{key}@exchange.example.com.
    # The placeholder must appear in the "user" part of the address (before the `@`).
    # Exchange does not support sub-addressing, so a catch-all mailbox must be used.
    address: "incoming-%{key}@exchange.example.com"

    # Email account username
    # Typically this is the userPrincipalName (UPN)
    user: "incoming@ad-domain.example.com"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "exchange.example.com"
    # IMAP server port
    port: 993
    # Whether the IMAP server uses SSL
    ssl: true

    # If you are using Microsoft Graph instead of IMAP, set this to false to retain
    # messages in the inbox because deleted messages are auto-expunged after some time.
    delete_after_delivery: true

    # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
    expunge_deleted: true

전용 이메일 주소#

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

Linux 패키지 설치 예제:

gitlab_rails['incoming_email_enabled'] = true

# Exchange does not support sub-addressing, and we're not using a catch-all mailbox so %{key} is not used here
gitlab_rails['incoming_email_address'] = "incoming@exchange.example.com"

# Email account username
# Typically this is the userPrincipalName (UPN)
gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "exchange.example.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true

# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
gitlab_rails['incoming_email_expunge_deleted'] = true

소스 컴파일 설치 예제:

incoming_email:
    enabled: true

    # Exchange does not support sub-addressing,
    # and we're not using a catch-all mailbox so %{key} is not used here
    address: "incoming@exchange.example.com"

    # Email account username
    # Typically this is the userPrincipalName (UPN)
    user: "incoming@ad-domain.example.com"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "exchange.example.com"
    # IMAP server port
    port: 993
    # Whether the IMAP server uses SSL
    ssl: true

    # If you are using Microsoft Graph instead of IMAP, set this to false to retain
    # messages in the inbox because deleted messages are auto-expunged after some time.
    delete_after_delivery: true

    # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
    expunge_deleted: true

Microsoft Office 365#

IMAP이 켜진 Microsoft Office 365 구성 예제입니다.

서브 주소 메일박스#

이 PowerShell 명령 시리즈는 Office 365 조직 수준에서 서브 주소 지정을 켭니다. 이렇게 하면 조직 내 모든 메일박스가 서브 주소가 지정된 메일을 받을 수 있습니다.

서브 주소 지정을 켜려면:

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

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

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
   Import-Module ExchangeOnlineManagement
   Connect-ExchangeOnline
   Set-OrganizationConfig -DisablePlusAddressInRecipients $false
   Disconnect-ExchangeOnline
   

메일박스 incoming@office365.example.com을 가정하는 Linux 패키지 설치 예제:

gitlab_rails['incoming_email_enabled'] = true

# The email address including the %{key} placeholder that will be replaced to reference the
# item being replied to. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress+%{key}@office365.example.com.
# The placeholder must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "incoming+%{key}@office365.example.com"

# Email account username
# Typically this is the userPrincipalName (UPN)
gitlab_rails['incoming_email_email'] = "incoming@office365.example.com"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "outlook.office365.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true

# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
gitlab_rails['incoming_email_expunge_deleted'] = true

메일박스 incoming@office365.example.com을 가정하는 소스 컴파일 설치 예제:

incoming_email:
    enabled: true

    # The email address including the %{key} placeholder that will be replaced to reference the
    # item being replied to. This %{key} should be included in its entirety within the email
    # address and not replaced by another value.
    # For example: emailaddress+%{key}@office365.example.com.
    # The placeholder must appear in the "user" part of the address (before the `@`).
    address: "incoming+%{key}@office365.example.comm"

    # Email account username
    # Typically this is the userPrincipalName (UPN)
    user: "incoming@office365.example.comm"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "outlook.office365.com"
    # IMAP server port
    port: 993
    # Whether the IMAP server uses SSL
    ssl: true

    # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
    expunge_deleted: true

Catch-all 메일박스#

Catch-all 메일박스 incoming@office365.example.com을 가정하는 Linux 패키지 설치 예제:

gitlab_rails['incoming_email_enabled'] = true

# The email address including the %{key} placeholder that will be replaced to reference the
# item being replied to. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress-%{key}@office365.example.com.
# The placeholder must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "incoming-%{key}@office365.example.com"

# Email account username
# Typically this is the userPrincipalName (UPN)
gitlab_rails['incoming_email_email'] = "incoming@office365.example.com"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "outlook.office365.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true

# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
gitlab_rails['incoming_email_expunge_deleted'] = true

Catch-all 메일박스 incoming@office365.example.com을 가정하는 소스 컴파일 설치 예제:

incoming_email:
    enabled: true

    # The email address including the %{key} placeholder that will be replaced to reference the
    # item being replied to. This %{key} should be included in its entirety within the email
    # address and not replaced by another value.
    # For example: emailaddress+%{key}@office365.example.com.
    # The placeholder must appear in the "user" part of the address (before the `@`).
    address: "incoming-%{key}@office365.example.com"

    # Email account username
    # Typically this is the userPrincipalName (UPN)
    user: "incoming@ad-domain.example.com"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "outlook.office365.com"
    # IMAP server port
    port: 993
    # Whether the IMAP server uses SSL
    ssl: true

    # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
    expunge_deleted: true

전용 이메일 주소#

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

gitlab_rails['incoming_email_enabled'] = true

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

# Email account username
# Typically this is the userPrincipalName (UPN)
gitlab_rails['incoming_email_email'] = "incoming@office365.example.com"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "outlook.office365.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true

# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
gitlab_rails['incoming_email_expunge_deleted'] = true

전용 이메일 주소 incoming@office365.example.com을 가정하는 소스 컴파일 설치 예제:

incoming_email:
    enabled: true

    address: "incoming@office365.example.com"

    # Email account username
    # Typically this is the userPrincipalName (UPN)
    user: "incoming@office365.example.com"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "outlook.office365.com"
    # IMAP server port
    port: 993
    # Whether the IMAP server uses SSL
    ssl: true

    # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
    expunge_deleted: true

Microsoft Graph#

GitLab은 IMAP 대신 Microsoft Graph API를 사용해 수신 이메일을 읽을 수 있습니다. Microsoft가 기본 인증을 사용하는 IMAP을 지원 종료하므로, 새 Microsoft Exchange Online 메일박스에는 Microsoft Graph API가 필요합니다.

Microsoft Graph용으로 GitLab을 구성하려면, 모든 메일박스에 대해 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 문서에 설명된 대로 모든 계정의 메일박스 접근을 제한하는 애플리케이션 접근 정책을 구성해야 합니다.

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

Microsoft Graph 구성#

gitlab_rails['incoming_email_enabled'] = true

# The email address including the %{key} placeholder that will be replaced to reference the
# item being replied to. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress+%{key}@example.onmicrosoft.com.
# The placeholder must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.onmicrosoft.com"

# Email account username
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': '',
   'client_id': '',
   'client_secret': '',
   'poll_interval': 60  # Optional
}

Microsoft Cloud for US Government 또는 다른 Azure 배포의 경우, azure_ad_endpoint 및 graph_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': '',
   'client_id': '',
   'client_secret': '',
   'poll_interval': 60  # Optional
}

Microsoft Graph API는 소스 컴파일 설치에서 아직 지원되지 않습니다. 자세한 내용은 이슈 326169를 참조합니다.

암호화된 자격 증명 사용#

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

사전 요구 사항:

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

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

• user
• password

문제 해결#

이메일 주소 제한이 있는 공급자에 의해 수신 이메일이 거부됨#

일부 이메일 공급자가 이메일 주소의 로컬 파트(@ 앞부분)에 64자 제한을 두기 때문에 GitLab 인스턴스가 수신 이메일을 받지 못할 수 있습니다. 이 제한을 초과하는 주소에서 온 이메일은 모두 거부됩니다.

해결 방법으로, 더 짧은 경로를 유지합니다:

• incoming_email_address에서 %{key} 앞에 구성되는 로컬 파트를 가능한 짧게, 31자를 넘지 않도록 유지합니다.
• 지정된 프로젝트를 상위 그룹 계층으로 옮깁니다.
• 그룹 및 프로젝트의 이름을 더 짧게 변경합니다.

이 기능은 이슈 460206에서 추적합니다.