| GitLab Docs

Help us learn about your current experience with the documentation. Take the survey.

---
stage: Plan
group: Project Management
info: 要确定分配给此页面的 Stage/Group 的技术文档作者，请参阅 https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
gitlab_dedicated: no
title: 接收邮件
---

版本：Free, Premium, Ultimate
类型：GitLab 自托管版



GitLab 提供了多个基于接收邮件消息的功能：

- [通过邮件回复](reply_by_email.md)：允许 GitLab 用户通过回复通知邮件来评论问题和合并请求。
- [通过邮件创建问题](../user/project/issues/create_issues.md#by-sending-an-email)：允许 GitLab 用户向用户专属邮箱发送邮件来创建新问题。
- [通过邮件创建合并请求](../user/project/merge_requests/creating_merge_requests.md#by-sending-an-email)：允许 GitLab 用户向用户专属邮箱发送邮件来创建新合并请求。
- [服务台](../user/project/service_desk/_index.md)：通过 GitLab 为客户提供邮件支持。

## 要求

建议使用一个**仅**接收 GitLab 实例所需邮件的邮箱地址。任何非发给 GitLab 的邮件都会收到拒绝通知。

处理接收邮件需要启用 [IMAP](https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol) 的邮箱账户。GitLab 支持以下三种策略之一：

- 邮件子地址（推荐）
- 全域邮箱
- 专用邮箱地址（仅支持通过邮件回复）

下面我们逐一介绍这些选项。

### 邮件子地址

[子地址](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) 是邮件服务器的一项功能，发送到 `user+arbitrary_tag@example.com` 的邮件会自动进入 `user@example.com` 的收件箱。Gmail、Google Apps、Yahoo! Mail、Outlook.com、iCloud 等服务提供商支持此功能，您也可以在本地运行的 [Postfix 邮件服务器](reply_by_email_postfix_setup.md) 中使用。Microsoft Exchange Server [不支持子地址](#microsoft-exchange-server)，Microsoft Office 365 [默认不支持子地址](#microsoft-office-365)。


  
  
    如果您的服务提供商或服务器支持邮件子地址，建议使用它。专用邮箱地址仅支持通过邮件回复功能。全域邮箱支持与子地址相同的功能，但子地址仍是首选，因为它只使用一个邮箱地址，可将全域邮箱保留给 GitLab 以外的其他用途。




### 全域邮箱

域名的[全域邮箱](https://www.wikipedia.org/wiki/Catch-all)会接收所有发送到该域名但未匹配邮件服务器上任何现有地址的邮件。

全域邮箱支持与邮件子地址相同的功能，但我们仍推荐使用子地址，以便将全域邮箱保留给其他用途。

### 专用邮箱地址

要设置此方案，您必须创建一个专用邮箱地址来接收用户对 GitLab 通知的回复。但此方法仅支持回复功能，不支持其他接收邮件功能。

## 接受的邮件头


    
    
    
在 GitLab 16.5 中引入 对 Cc 邮件头的支持。
在 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` 邮件头也被接受，但专门用于将邮件回复关联到现有讨论线程。不用于通过邮件创建问题。

在 GitLab 14.6 及更高版本中，[服务台](../user/project/service_desk/_index.md) 也会检查接受的邮件头。

通常 `To` 字段包含主要接收者的邮箱地址。但如果出现以下情况，它可能不包含配置的 GitLab 邮箱地址：

- 地址在 `BCC` 字段中。
- 邮件被转发。

`Received` 邮件头可能包含多个邮箱地址，这些地址按出现顺序检查，使用第一个匹配项。

## 拒绝的邮件头

为防止自动邮件系统创建不必要的问题，GitLab 会忽略包含以下邮件头的所有邮件：

- `Auto-Submitted` 值不为 `no`
- `X-Autoreply` 值为 `yes`

## 设置

如果使用 Gmail / Google Apps 接收邮件，请确保已[启用 IMAP 访问](https://support.google.com/mail/answer/7126229) 并[允许非安全应用访问账户](https://support.google.com/accounts/answer/6010255)，或[开启两步验证](https://support.google.com/accounts/answer/185839) 并使用[应用密码](https://support.google.com/mail/answer/185833)。

如果使用 Office 365 且启用了双因素认证，请确保使用[应用密码](https://support.microsoft.com/en-us/account-billing/app-passwords-for-a-work-or-school-account-d6dc8c6d-4bf7-4851-ad95-6d07799387e9) 而非常规邮箱密码。

要在 Ubuntu 上设置支持 IMAP 的基本 Postfix 邮件服务器，请遵循 [Postfix 设置文档](reply_by_email_postfix_setup.md)。

### 安全注意事项


  
  
    选择接收邮件的域名时需谨慎。




例如，假设您的顶级公司域是 `hooli.com`。公司所有员工通过 Google Workspace 拥有该域名的邮箱，且公司内部 Slack 实例要求使用有效的 `@hooli.com` 邮箱地址注册。

如果您也在 `hooli.com` 上托管公开的 GitLab 实例，并将接收邮件域名设为 `hooli.com`，攻击者可能通过使用项目唯一地址作为注册 Slack 时的邮箱，滥用“通过邮件创建问题”或[“通过邮件创建合并请求”](../user/project/merge_requests/creating_merge_requests.md#by-sending-an-email)功能。这将发送确认邮件，在攻击者拥有的项目上创建新问题或合并请求，使其能够点击确认链接并在公司内部 Slack 实例中验证账户。

我们建议在子域（如 `incoming.hooli.com`）上接收邮件，并确保不使用仅基于访问 `*.hooli.com` 邮箱域进行认证的服务。或者，为 GitLab 邮件通信使用专用域名，如 `hooli-gitlab.com`。

有关此漏洞的实际案例，请参阅 GitLab 问题 [#30366](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/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

验证配置是否正确：

sudo gitlab-rake gitlab:incoming_email:check

通过邮件回复功能现在应该可以正常工作。

自编译安装

进入 GitLab 安装目录：
```
cd /home/git/gitlab
```
手动安装 gitlab-mail_room gem：
```
gem install gitlab-mail_room
```
此步骤是避免线程死锁并支持最新 MailRoom 功能所必需的。
在 config/gitlab.yml 中找到 incoming_email 部分，启用功能并填写您的 IMAP 服务器和邮箱账户详情（参见下文配置示例）。

如果您使用 systemd 单元管理 GitLab：

将 gitlab-mailroom.service 添加为 gitlab.target 的依赖项：
```
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 init 脚本管理 GitLab：

在 /etc/default/gitlab 的 init 脚本中启用 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

通过邮件回复功能现在应该可以正常工作。

配置示例

Postfix

Postfix 邮件服务器配置示例。假设邮箱为 incoming@gitlab.example.com。

Linux 包安装示例：

gitlab_rails['incoming_email_enabled'] = true

# 包含 %{key} 占位符的邮箱地址，用于引用被回复的项目。此 %{key} 应完整包含在邮箱地址中，
# 不被其他值替换。例如：emailaddress+%{key}@gitlab.example.com。
# 占位符必须出现在地址的“用户”部分（@ 符号之前）。
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

# 如果使用 Microsoft Graph 而非 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。
    # 占位符必须出现在地址的“用户”部分（@ 符号之前）。
    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

    # 如果使用 Microsoft Graph 而非 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 包安装示例：

gitlab_rails['incoming_email_enabled'] = true

# 包含 %{key} 占位符的邮箱地址，用于引用被回复的项目。此 %{key} 应完整包含在邮箱地址中，
# 不被其他值替换。例如：emailaddress+%{key}@gmail.com。
# 占位符必须出现在地址的“用户”部分（@ 符号之前）。
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

# 如果使用 Microsoft Graph 而非 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}@gmail.com。
    # 占位符必须出现在地址的“用户”部分（@ 符号之前）。
    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

    # 如果使用 Microsoft Graph 而非 IMAP，设为 false 以保留邮件，
    # 因为删除的邮件会在一段时间后自动清除。
    delete_after_delivery: true

    # 是否在邮件标记为删除后从邮箱中永久删除（清除）
    # 仅适用于 IMAP。Microsoft Graph 会自动清除任何已删除邮件。
    expunge_deleted: true

Microsoft Exchange Server

启用 IMAP 的 Microsoft Exchange Server 配置示例。由于 Exchange 不支持子地址，只有两个选项：

全域邮箱（仅 Exchange 推荐）
专用邮箱地址（仅支持通过邮件回复）

全域邮箱

假设全域邮箱为 incoming@exchange.example.com。

Linux 包安装示例：

gitlab_rails['incoming_email_enabled'] = true

# 包含 %{key} 占位符的邮箱地址，用于引用被回复的项目。此 %{key} 应完整包含在邮箱地址中，
# 不被其他值替换。例如：emailaddress-%{key}@exchange.example.com。
# 占位符必须出现在地址的“用户”部分（@ 符号之前）。
# Exchange 不支持子地址，必须使用全域邮箱。
gitlab_rails['incoming_email_address'] = "incoming-%{key}@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

# 是否在邮件标记为删除后从邮箱中永久删除（清除）
# 仅适用于 IMAP。Microsoft Graph 会自动清除任何已删除邮件。
gitlab_rails['incoming_email_expunge_deleted'] = true

自编译安装示例：

incoming_email:
    enabled: true

    # 包含 %{key} 占位符的邮箱地址，用于引用被回复的项目。此 %{key} 应完整包含在邮箱地址中，
    # 不被其他值替换。例如：emailaddress-%{key}@exchange.example.com。
    # 占位符必须出现在地址的“用户”部分（@ 符号之前）。
    # Exchange 不支持子地址，必须使用全域邮箱。
    address: "incoming-%{key}@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

    # 如果使用 Microsoft Graph 而非 IMAP，设为 false 以保留邮件，
    # 因为删除的邮件会在一段时间后自动清除。
    delete_after_delivery: true

    # 是否在邮件标记为删除后从邮箱中永久删除（清除）
    # 仅适用于 IMAP。Microsoft Graph 会自动清除任何已删除邮件。
    expunge_deleted: true

专用邮箱地址

仅支持通过邮件回复。不支持服务台。

假设专用邮箱地址为 incoming@exchange.example.com。

Linux 包安装示例：

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

    # 如果使用 Microsoft Graph 而非 IMAP，设为 false 以保留邮件，
    # 因为删除的邮件会在一段时间后自动清除。
    delete_after_delivery: true

    # 是否在邮件标记为删除后从邮箱中永久删除（清除）
    # 仅适用于 IMAP。Microsoft Graph 会自动清除任何已删除邮件。
    expunge_deleted: true

Microsoft Office 365

启用 IMAP 的 Microsoft Office 365 配置示例。

子地址邮箱

截至 2020 年 9 月，Office 365 已添加子地址支持。此功能默认未启用，必须通过 PowerShell 启用。

以下 PowerShell 命令在 Office 365 组织级别启用子地址，使组织中的所有邮箱都能接收子地址邮件。

启用子地址：

从 PowerShell 库下载并安装 ExchangeOnlineManagement 模块。

在 PowerShell 中运行以下命令：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline
Set-OrganizationConfig -DisablePlusAddressInRecipients $false
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"

# 邮箱账户用户名
# 通常是 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@office365.example.com"
    # 邮箱账户密码
    password: "[REDACTED]"

    # IMAP 服务器主机
    host: "outlook.office365.com"
    # IMAP 服务器端口
    port: 993
    # IMAP 服务器是否使用 SSL
    ssl: true

    # 是否在邮件标记为删除后从邮箱中永久删除（清除）
    # 仅适用于 IMAP。Microsoft Graph 会自动清除任何已删除邮件。
    expunge_deleted: true

全域邮箱

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"

# 邮箱账户用户名
# 通常是 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

    # 是否在邮件标记为删除后从邮箱中永久删除（清除）
    # 仅适用于 IMAP。Microsoft Graph 会自动清除任何已删除邮件。
    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

# 是否在邮件标记为删除后从邮箱中永久删除（清除）
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

    # 是否在邮件标记为删除后从邮箱中永久删除（清除）
    # 仅适用于 IMAP。Microsoft Graph 会自动清除任何已删除邮件。
    expunge_deleted: true

Microsoft Graph

GitLab 可以使用 Microsoft Graph API 而非 IMAP 读取接收邮件。由于Microsoft 正在弃用使用基本身份验证的 IMAP，Microsoft Graph API 将成为新的 Microsoft Exchange Online 邮箱的必需配置。

要为 GitLab 配置 Microsoft Graph，需要在 Azure Active Directory 中注册一个 OAuth 2.0 应用程序，该应用程序对所有邮箱具有 Mail.ReadWrite 权限。更多详情请参阅 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

# 包含 %{key} 占位符的邮箱地址，用于引用被回复的项目。此 %{key} 应完整包含在邮箱地址中，
# 不被其他值替换。例如：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_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': '<YOUR-TENANT-ID>',
   'client_id': '<YOUR-CLIENT-ID>',
   'client_secret': '<YOUR-CLIENT-SECRET>',
   'poll_interval': 60  # 可选
}

Microsoft Graph API 尚不支持自编译安装。更多详情请参阅此问题。

使用加密凭据

您可以选择使用加密文件存储接收邮件凭据，而非在配置文件中以明文存储。

先决条件：

要使用加密凭据，必须先启用加密配置。

加密文件支持以下配置项：

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 并移除 incoming_email 的 email 和 password 设置。
保存文件并重新配置 GitLab：
```
sudo gitlab-ctl reconfigure
```

使用 Kubernetes secret 存储接收邮件密码。更多信息，请参阅 Helm IMAP secrets。

如果您最初在 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 并移除 incoming_email 的 email 和 password 设置。
保存文件并重启 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 并移除 incoming_email: 的 user 和 password 设置。

保存文件并重启 GitLab 和 Mailroom

# 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

故障排除

16.6.0 版本中邮件处理功能不工作

在 GitLab 16.6 中，回归问题导致 mail_room（邮件处理）无法启动。服务台和其他通过邮件回复功能无法工作。此问题已在 16.6.1 中修复。详情请参阅 issue 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

邮件被带地址限制的提供商拒绝

您的 GitLab 实例可能无法接收邮件，因为某些邮件提供商对邮箱地址的本地部分（@ 符号之前）施加了 64 字符限制。所有超过此限制的邮件都会被拒绝。

解决方法是保持路径较短：

确保 incoming_email_address 中 %{key} 前配置的本地部分尽可能短，不超过 31 个字符。
将指定项目放在更高的组层级。
将组和项目重命名为更短的名称。

跟踪此功能在 issue 460206 中的进展。