수신 이메일
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는 기본적으로 서브-주소를 지원하지 않습니다.
전체 메일함
도메인에 대한 전체 메일함은 메일 서버에서 기존 주소와 일치하지 않는 해당 도메인으로 보낸 모든 이메일을 수신합니다.
전체 메일함은 이메일 서브-주소와 동일한 기능을 지원하지만, 이메일 서브-주소를 사용하여 전체 메일함을 다른 용도로 예약할 수 있도록 하는 것이 여전히 권장됩니다.
전용 이메일 주소
이 솔루션을 설정하려면 사용자의 회신에 대한 전용 이메일 주소를 생성해야 합니다. 그러나 이 방법은 회신 기능만 지원하며 수신 이메일의 다른 기능을 지원하지는 않습니다.
허용된 헤더
- 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
헤더 - 값이
yes
인X-Autoreply
헤더
설정
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에 가입할 때 프로젝트의 고유 주소를 이메일로 사용함으로써 “이메일로 새 이슈 생성” 또는
“이메일로 새 Merge Request 생성” 기능을 남용할 수 있습니다. 그러면 확인 이메일이 전송되어 공격자가 새 이슈나 Merge Request을 프로젝트에서 선택하고 회사의 사설 Slack 인스턴스에서 계정을 확인할 수 있습니다.
따라서 incoming.hooli.com
과 같은 하위 도메인을 사용하여 수신 이메일을 받고, *.hooli.com
과 같은 이메일 도메인 기반의 서비스를 사용하지 않도록 하는 것이 좋습니다. 또는 hooli-gitlab.com
과 같이 GitLab 이메일 통신을 위해 전용 도메인을 사용하십시오.
이러한 악용 사례의 실제 예시는 GitLab 이슈 #30366에서 확인할 수 있습니다.
FROM
주소로 전송되어 해당 메일 서버의 IP나 도메인이 차단 디렉터리에 나타날 수 있습니다.Linux 패키지 설치
-
/etc/gitlab/gitlab.rb
에서incoming_email
섹션을 찾아 기능을 활성화하고, 특정 IMAP 서버 및 이메일 계정에 대한 세부 정보를 입력하세요(아래의 예시를 참조하세요). -
변경 사항이 적용되도록 GitLab을 다시 구성하세요:
sudo gitlab-ctl reconfigure # 처음으로 활성화 또는 비활성화하는 경우에 필요하나 암호 변경 시에는 필요하지 않습니다. 자세한 내용은 https://gitlab.com/gitlab-org/gitlab-foss/-/issues/23560#note_61966788에서 확인하세요. sudo gitlab-ctl restart
-
모든 것이 올바르게 구성되었는지 확인하세요:
sudo gitlab-rake gitlab:incoming_email:check
이제 이메일로 회신할 수 있어야 합니다.
직접 컴파일한 설치
-
GitLab 설치 디렉터리로 이동하세요:
cd /home/git/gitlab
-
gitlab-mail_room
젬을 매뉴얼으로 설치하세요:gem install gitlab-mail_room
참고: 이 단계는 스레드 데드락을 피하고 최신 MailRoom 기능을 지원하기 위해 필요합니다. 자세한 내용은 이 설명을 참조하세요.
-
config/gitlab.yml
에서incoming_email
섹션을 찾아 기능을 활성화하고, 특정 IMAP 서버 및 이메일 계정에 대한 세부 정보를 입력하세요(아래의 예시를 참조하세요).
시스템디 유닛을 사용하여 GitLab을 관리하는 경우:
-
gitlab.target
에gitlab-mailroom.service
를 의존성으로 추가하세요:sudo systemctl edit gitlab.target
열리는 편집기에서 다음을 추가하고 파일을 저장하세요:
[Unit] Wants=gitlab-mailroom.service
-
만약 Redis와 PostgreSQL을 동일한 머신에서 실행 중이라면, Redis에 대한 의존성을 추가해야 합니다. 다음을 실행하세요:
sudo systemctl edit gitlab-mailroom.service
열리는 편집기에서 다음을 추가하고 파일을 저장하세요:
[Unit] Wants=redis-server.service After=redis-server.service
-
gitlab-mailroom.service
를 시작하세요:sudo systemctl start gitlab-mailroom.service
-
모든 것이 올바르게 구성되었는지 확인하세요:
sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
SysV 이닛 스크립트를 사용하여 GitLab을 관리하는 경우:
-
이닛 스크립트(
/etc/default/gitlab
에서)에서mail_room
을 활성화하세요:sudo mkdir -p /etc/default echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab
-
GitLab을 다시 시작하세요:
sudo service gitlab restart
-
모든 것이 올바르게 구성되었는지 확인하세요:
sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
이제 이메일로 회신할 수 있어야 합니다.
구성 예시
포스트픽스
포스트픽스 메일 서버의 예시 구성. 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
메일함을 전제로합니다.
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 (Exchange 전용 권장)
- Dedicated email address (답장 이메일만 지원)
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
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 기능이 활성화된 예제 구성입니다.
하위 주소 지원 메일박스
Office 365의 조직 수준에서 하위 주소 지원을 활성화하는 일련의 PowerShell 명령입니다. 이를 통해 조직의 모든 메일박스가 하위 주소가 포함된 메일을 수신할 수 있습니다.
하위 주소를 활성화하려면:
-
PowerShell 갤러리에서
ExchangeOnlineManagement
모듈을 다운로드하고 설치합니다. -
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
전용 이메일 주소
이 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_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': '<당신의 테넌트 ID>',
'client_id': '<당신의 클라이언트 ID>',
'client_secret': '<당신의 클라이언트 비밀번호>',
'poll_interval': 60 # 선택 사항
}
셀프 컴파일 설치에서는 아직 Microsoft Graph API가 지원되지 않습니다. 자세한 내용은 이 이슈를 참조하세요.
암호화된 자격 증명 사용
- GitLab 15.9에서 도입되었습니다.
들어오는 이메일 자격 증명을 평문으로 구성 파일에 저장하는 대신, 들어오는 이메일 자격 증명을 위해 선택적으로 암호화 파일을 사용할 수 있습니다.
필수 컴포넌트:
- 암호화된 자격 증명을 사용하려면 먼저 암호화된 구성을 활성화해야 합니다.
암호화된 파일에 대한 지원되는 구성 항목은 다음과 같습니다:
user
password
-
초기에
/etc/gitlab/gitlab.rb
에서 들어오는 이메일 구성이 다음과 같은 경우:gitlab_rails['incoming_email_email'] = "incoming-email@mail.example.com" gitlab_rails['incoming_email_password'] = "examplepassword"
-
암호화된 비밀 수정:
sudo gitlab-rake gitlab:incoming_email:secret:edit EDITOR=vim
-
들어오는 이메일 비밀의 평문 내용 입력:
user: 'incoming-email@mail.example.com' password: 'examplepassword'
-
/etc/gitlab/gitlab.rb
를 편집하고이메일
및비밀번호
에 대한들어오는 이메일
설정 제거 -
파일 저장 및 GitLab 재구성:
sudo gitlab-ctl reconfigure
들어오는 이메일 비밀번호를 저장하기 위해 Kubernetes 시크릿을 사용합니다. 자세한 정보는 Helm IMAP 시크릿을 참조하세요.
-
초기에
docker-compose.yml
에서 들어오는 이메일 구성이 다음과 같은 경우:version: "3.6" services: gitlab: image: 'gitlab/gitlab-ee:latest' restart: always hostname: 'gitlab.example.com' environment: GITLAB_OMNIBUS_CONFIG: | gitlab_rails['incoming_email_email'] = "incoming-email@mail.example.com" gitlab_rails['incoming_email_password'] = "examplepassword"
-
컨테이너 내부로 이동하여 암호화된 비밀 수정:
sudo docker exec -t <container_name> bash gitlab-rake gitlab:incoming_email:secret:edit EDITOR=editor
-
들어오는 이메일 비밀의 평문 내용 입력:
user: 'incoming-email@mail.example.com' password: 'examplepassword'
-
docker-compose.yml
을 편집하고들어오는 이메일
설정에서이메일
및비밀번호
제거 -
파일 저장 및 GitLab 재시작:
docker compose up -d
-
초기에
/home/git/gitlab/config/gitlab.yml
에서 들어오는 이메일 구성이 다음과 같은 경우:production: incoming_email: user: 'incoming-email@mail.example.com' password: 'examplepassword'
-
암호화된 비밀 수정:
bundle exec rake gitlab:incoming_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production
-
들어오는 이메일 비밀의 평문 내용 입력:
user: 'incoming-email@mail.example.com' password: 'examplepassword'
-
/home/git/gitlab/config/gitlab.yml
을 편집하고들어오는 이메일:
설정에서user
및password
제거 -
파일 저장 및 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 설치에서 다음 명령을 실행하여 영향받는 파일을 패치하는 것입니다:
curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff"
patch -p1 -d /opt/gitlab/embedded/service/gitlab-rails < /tmp/mailroom.patch
gitlab-ctl restart mailroom
curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff"
cd /opt/gitlab/embedded/service/gitlab-rails
patch -p1 < /tmp/mailroom.patch
gitlab-ctl restart mailroom