수신 이메일

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

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

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

요구 사항

GitLab 인스턴스를 위해 목적지가 되는 메시지만을 수신하는 이메일 주소를 권장합니다. GitLab에게 의도되지 않은 수신 이메일 메시지는 거부 응답을 받습니다.

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

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

각 옵션에 대해 살펴봅시다.

이메일 서브 주소

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

참고: 제공업체나 서버에서 이메일 서브 주소를 지원하는 경우 권장합니다. 전용 이메일 주소는 회신 이메일 기능만 지원하며, 전체 메일함은 서브 주소와 동일한 기능을 지원하지만 서브 주소 사용이 우선되므로 단일 이메일 주소만 사용하고 전체 메일함을 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” 필드에는 주 이메일 주소가 포함됩니다. 그러나 “BCC” 필드에 주소가 있는 경우나 이메일이 전달된 경우에는 구성된 GitLab 이메일 주소가 포함되지 않을 수 있습니다.

“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에서 공개적인 GitLab 인스턴스를 호스팅하고 수신 이메일 도메인을 hooli.com으로 설정한다면, 공격자는 사적 Slack에 가입하려는 시도 중에 프로젝트의 고유 이메일 주소를 사용하여 Slack에 가입함으로써 “이메일로 새 이슈 생성”이나 “이메일로 새 병합 요청 생성” 기능을 남용할 수 있습니다. 이는 확인 이메일을 보내어 공격자가 당신의 회사의 사적 Slack 인스턴스에 대한 계정을 검증하게 함으로써, 공격자가 자신의 프로젝트에 새 이슈나 병합 요청을 만들도록 하며, 그 후 그 계정을 승인합니다.

따라서 수신 이메일을 incoming.hooli.com과 같은 하위 도메인으로 설정하고 *.hooli.com.와 같은 이메일 도메인에 접근 권한이 있는 서비스를 사용하지 않도록 확인하는 것을 권장합니다. 또는 hooli-gitlab.com과 같은 GitLab 이메일 통신 전용 도메인을 사용하세요.

이러한 악용 예를 보려면 GitLab 이슈 #30366을 참조하세요.

경고: 스팸을 줄이기 위해 구성된 메일 서버를 사용하는 것에 주의하여야 합니다. 예를 들어 기본 설정으로 실행 중인 Postfix 메일 서버는 부정한 사용을 초래할 수 있습니다. 설정된 메일함에 수신된 모든 메시지가 처리되고, GitLab 인스턴스를 위해 의도되지 않은 메시지는 거부 응답을 받습니다. 보내는 주소가 위조된 경우 거부 응답이 위조된 FROM 주소로 전달되어 이 때문에 메일 서버의 IP나 도메인이 차단 목록에 표시됩니다.

경고: 사용자는 자체의 이중 인증(2FA)을 강화했더라도, 수신 이메일 기능을 사용할 수 있습니다. 예를 들어, 여러분의 인스턴스에 대해 이중 인증을 강제화했더라도 이에 부합하지 않습니다. 

### Linux 패키지 설치

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

1. 변경 내용이 적용되려면 GitLab을 재구성하세요:

   ```shell
   sudo gitlab-ctl reconfigure

   # 처음으로 활성화 또는 비활성화하는 경우에 필요하지만 비밀번호 변경 시에는 필요하지 않습니다.
   # https://gitlab.com/gitlab-org/gitlab-foss/-/issues/23560#note_61966788 참조
   sudo gitlab-ctl restart
   ```

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

    sudo gitlab-rake gitlab:incoming_email:check

이메일로 응답을 보낼 수 있어야 합니다.

자체 컴파일 설치

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

    cd /home/git/gitlab

  2. gitlab-mail_room gem을 수동으로 설치하세요: 

    gem install gitlab-mail_room

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

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

시스템디 단위를 사용하여 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의 초기화 스크립트에서 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

# 이메일 주소 및 %{key} 플레이스홀더를 포함하여 참조하기 위해 대체될 주소. 이 %{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

# IMAP에서만 적용됩니다. 삭제된 메시지가 전달 후 자동 삭제되기 때문에 이 값을 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.
  # 플레이스홀더는 주소의 "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

  # IMAP에서만 적용됩니다. 삭제된 메시지가 전달 후 자동 삭제되기 때문에 이 값을 false로 설정하여 받은 메시지를 계속해서 유지하세요.
  delete_after_delivery: true

  # 메시지가 삭제된 후 메일함에서 영구적으로 제거(청소)되도록 하는지 여부
  # IMAP에만 적용됩니다. Microsoft Graph는 삭제된 메시지를 자동으로 청소합니다.
  expunge_deleted: true

#### Gmail

Gmail/Google Workspace를 위한 예시 구성입니다. `gitlab-incoming@gmail.com` 메일박스를 가정합니다.

참고:
`incoming_email_email`은 Gmail 별칭 계정이 될 수 없습니다.

Linux 패키지 설치 예시:

```ruby
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

# 수신 메일이 도착할 메일함. 일반적으로 "받은편지함"(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}를 포함하여야 합니다.
  # 이 %{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
  # 수신 메일이 도착할 메일함. 일반적으로 "받은편지함"(inbox)입니다.
  mailbox: "inbox"
  # IDLE 명령 대기 시간
  idle_timeout: 60

  # IMAP 대신 Microsoft Graph를 사용하는 경우, 삭제된 메시지가 일정 시간 후 자동으로 영구적으로 제거되는 것을 원치 않는다면 이 값을 false로 설정하세요.
  delete_after_delivery: true

  # 메시지가 삭제된 후 메일함에서 영구적으로(삭제됨) 삭제되는지 여부
  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는 삭제된 메시지를 자동으로 영구적으로 삭제합니다.
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 Graph를 사용하는 경우, 삭제된 메시지가 일정 시간 후 자동으로 영구적으로 제거되는 것을 원치 않는다면 이 값을 false로 설정하세요.
  delete_after_delivery: true

  # 해당 메시지가 삭제된 후 메일함에서 영구적으로(삭제됨) 삭제되는지 여부
  expunge_deleted: true
전용 이메일 주소

참고: 이메일 답장만 지원됩니다. 서비스 데스크는 지원할 수 없습니다.

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

리눅스 패키지 설치 예시: 

gitlab_rails['incoming_email_enabled'] = true

# Exchange는 서브 주소 지원을 하지 않으며, 캐치 올 메일함을 사용하지 않기 때문에 %{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는 서브 주소를 지원하지 않으며,
  # 캐치 올 메일함을 사용하지 않기 때문에 %{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

  # IMAP 대신 Microsoft Graph를 사용하는 경우 삭제된 메시지가 일정 시간 이후에 자동으로 expunge되므로 이것을 유지할지 여부
  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"

# 이메일 계정 사용자 이름
# 일반적으로 이것은 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
캐치 올 메일함

리눅스 패키지 설치 예시는 캐치 올 메일함 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.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
전용 이메일 주소

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

리눅스 패키지 설치 예제에서 전용 이메일 주소 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

# 배달 후 삭제된 메시지를 메일함에서 영구적으로 삭제할지 여부
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_deleted: true

Microsoft Graph

GitLab은 IMAP 대신 Microsoft Graph API를 사용하여 수신 이메일을 읽을 수 있습니다. Microsoft가 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 설명서를 참조하세요.

리눅스 패키지 설치 예제에서 다음 메일함을 사용한다고 가정합니다: incoming@example.onmicrosoft.com

Microsoft Graph 구성 
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 배포의 예:

  • 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는 자체 컴파일 설치에서 아직 지원되지 않습니다. 자세한 내용은 이 이슈를 참조하세요.

암호화된 자격 증명 사용

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

전제 조건:

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

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

  • 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를 편집하고 email 및 password에 대한 incoming_email 설정을 제거합니다.

  5. 파일을 저장하고 GitLab을 재구성합니다: 

    sudo gitlab-ctl reconfigure
Helm 차트 (Kubernetes)

수신 이메일 암호를 저장하기 위해 쿠버네티스 시크릿을 사용하세요. 자세한 내용은 Helm IMAP Secrets를 참조하세요.

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을 편집하고 email 및 password에 대한 incoming_email 설정을 제거합니다.

  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을 편집하고 incoming_email:에 대한 user 및 password 설정을 제거합니다.

  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

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

일부 이메일 제공업체는 이메일 주소의 로컬 부분(‘@’ 이전)에 64자 제한을 부과하여 GitLab 인스턴스가 수신 이메일을 받지 못할 수 있습니다. 이 제한을 초과하는 주소에서 온 이메일은 거부됩니다.

해결 방법으로는 더 짧은 경로를 유지하세요:

  • incoming_email_address에서 %{key} 이전에 구성된 로컬 부분이 가능한 한 짧고, 31자를 초과하지 않도록 합니다.
  • 특정 프로젝트를 더 높은 그룹 계층에 배치합니다.
  • 그룹 및 프로젝트의 이름을 더 짧게 변경합니다.

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