{{< details >}}

  • Tier: 基础版，专业版，旗舰版
  • Offering: 私有化部署

{{< /details >}}

极狐GitLab 有几个功能基于接收邮件消息：

  1. 通过邮件回复：允许极狐GitLab 用户通过回复通知邮件来评论议题和合并请求。
  2. 通过邮件创建新议题：允许极狐GitLab 用户通过向用户特定的电子邮件地址发送邮件来创建新的议题。
  3. 通过邮件创建新合并请求：允许极狐GitLab 用户通过向用户特定的电子邮件地址发送邮件来创建新的合并请求。
  4. 服务台：通过极狐GitLab 向您的客户提供邮件支持。

要求

我们建议使用一个仅接收极狐GitLab 实例邮件的电子邮件地址。任何不适用于极狐GitLab 的邮件消息都会收到拒绝通知。

处理邮件消息需要一个 IMAP 启用的电子邮件账户。极狐GitLab 需要以下三种策略之一：

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

我们来逐一介绍这些选项。

邮件子地址

子地址是一个邮件服务器功能，任何发到user+arbitrary_tag@example.com的邮件都会进入user@example.com的邮箱。它由 Gmail，Google Apps，Yahoo! Mail，Outlook.com 和 iCloud 等提供商支持，以及您可以在本地运行的 Postfix 邮件服务器。Microsoft Exchange Server 不支持子地址，并且 Microsoft Office 365默认不支持子地址。

{{< alert type=”note” >}}

如果您的提供商或服务器支持邮件子地址，我们建议使用它。专用邮箱地址仅支持通过邮件回复功能。全域邮箱支持与子地址相同的功能，但仍然首选子地址，因为仅使用一个邮箱地址，使全域邮箱可以用于极狐GitLab 以外的其他目的。

{{< /alert >}}

全域邮箱

一个全域邮箱会接收所有发到域的邮件消息，而这些消息并不匹配邮件服务器上的任何地址。

全域邮箱支持与邮件子地址相同的功能，但我们还是推荐使用邮件子地址，以便您可以将全域邮箱用于其他目的。

专用邮箱地址

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

接受的头

{{< history >}}

  • 接受 Cc 头在极狐GitLab 16.5 中引入。
  • 接受 X-Original-To 头在极狐GitLab 17.0 中引入。
  • 接受 X-Forwarded-To 头在极狐GitLab 17.6 中引入。
  • 接受 X-Delivered-To 头在极狐GitLab 17.6 中引入。

{{< /history >}}

当配置的邮箱地址出现在以下头之一（按检查顺序排序）时，邮件会被正确处理：

  • To
  • Delivered-To
  • X-Delivered-To
  • Envelope-To 或 X-Envelope-To
  • Received
  • X-Original-To
  • X-Forwarded-To
  • Cc

References 头也被接受，但它专门用于将邮件回复与现有讨论线程关联。它不用于通过邮件创建议题。

在极狐GitLab 14.6 及更高版本中，服务台也会检查接受的头。

通常，To 字段包含主要接收者的邮箱地址。然而，如果：

  • 地址在 BCC 字段中。
  • 邮件已被转发。

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

拒绝的头

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

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

设置

要在 Ubuntu 上设置具有 IMAP 访问的基本 Postfix 邮件服务器，请遵循Postfix 设置文档。

安全问题

{{< alert type=”warning” >}}

选择用于接收邮件的域时要小心。

{{< /alert >}}

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

如果您在 hooli.com 上托管一个面向公众的极狐GitLab 实例，并将您的邮件域设置为 hooli.com，攻击者可以通过使用项目的唯一地址作为注册 Slack 时的邮箱来滥用通过邮件创建新议题或通过邮件创建新合并请求功能。这会发送确认邮件，创建一个攻击者拥有的项目上的新议题或合并请求，允许他们选择确认链接并验证账户在您公司的私有 Slack 实例上。

我们建议在子域上接收邮件，例如 incoming.hooli.com，并确保您不使用任何服务仅基于访问邮箱域进行身份验证，例如 *.hooli.com.。或者，使用专用域进行极狐GitLab 邮件通信，例如 hooli-gitlab.com。

{{< alert type=”warning” >}}

使用配置为减少垃圾邮件的邮件服务器。运行默认配置的 Postfix 邮件服务器，例如，可能导致滥用。配置邮箱上接收的所有邮件都会被处理，而不适用于极狐GitLab 的邮件会收到拒绝通知。如果发件人的地址被伪造，拒绝通知会发送到伪造的 FROM 地址，这可能导致邮件服务器的 IP 或域出现在阻止列表中。

{{< /alert >}}

{{< alert type=”warning” >}}

用户可以使用邮件功能而无需首先使用双重身份验证（2FA）进行身份验证。即使您已为实例强制执行双重身份验证，这也适用。

{{< /alert >}}

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：

    gem install gitlab-mail_room

    {{< alert type=”note” >}}

    这一步是为了避免线程死锁并支持最新的 MailRoom 功能。有关更多详细信息，请参阅此解释。

    {{< /alert >}}

  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

# 包含 %{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。

{{< alert type=”note” >}}

incoming_email_email 不能是 Gmail 别名账户。

{{< /alert >}}

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

Microsoft Exchange Server 的 IMAP 启用配置示例。由于 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

    # 删除邮件后是否从邮箱中删除（永久删除）邮件
    expunge_deleted: true

专用邮箱地址

{{< alert type=”note” >}}

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

{{< /alert >}}

假设专用邮箱地址 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

    # 删除邮件后是否从邮箱中删除（永久删除）邮件
    expunge_deleted: true

Microsoft Office 365

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

子地址邮箱

此系列 PowerShell 命令在 Office 365 中组织级别启用子地址。这允许组织中的所有邮箱接收子地址邮件。

要启用子地址：

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

  2. 在 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.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

全域邮箱

此 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

    # 删除邮件后是否从邮箱中删除（永久删除）邮件
    expunge_deleted: true

专用邮箱地址

{{< alert type=”note” >}}

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

{{< /alert >}}

此 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

    # 删除邮件后是否从邮箱中删除（永久删除）邮件
    expunge_deleted: true

Microsoft Graph

极狐GitLab 可以使用 Microsoft Graph API 读取邮件，而不是 IMAP。因为 Microsoft 正在废弃使用基本身份验证的 IMAP ，Microsoft Graph API 将成为新 Microsoft Exchange Online 邮箱的必需项。

要为 Microsoft Graph 配置极狐GitLab，您需要在 Azure Active Directory 中注册一个 OAuth 2.0 应用程序，该应用程序具有所有邮箱的 Mail.ReadWrite 权限。

在配置 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：

配置 Microsoft Graph

{{< history >}}

  • 替代 Azure 部署在极狐GitLab 14.9 中引入。

{{< /history >}}

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  # 可选项
}

使用加密凭证

{{< history >}}

  • 在极狐GitLab 15.9 中引入。

{{< /history >}}

与在配置文件中以明文存储邮件凭证相比，您可以选择使用加密文件来存储邮件凭证。

先决条件：

  • 要使用加密凭证，您必须首先启用加密配置。

加密文件支持的配置项为：

  • user
  • password

{{< tabs >}}

{{< tab title=”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 并删除 incoming_email 设置中的 email 和 password。

  5. 保存文件并重新配置极狐GitLab：

    sudo gitlab-ctl reconfigure

{{< /tab >}}

{{< tab title=”Helm chart (Kubernetes)” >}}

使用 Kubernetes secret 存储邮件密码。有关更多信息，请阅读Helm IMAP secrets。

{{< /tab >}}

{{< tab title=”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 并删除 incoming_email 设置中的 email 和 password。

  5. 保存文件并重启极狐GitLab：

    docker compose up -d

{{< /tab >}}

{{< tab title=”自编译 (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

{{< /tab >}}

{{< /tabs >}}

故障排除

邮件接收在 16.6.0 中不起作用

在极狐GitLab 16.6 中，回归阻止 mail_room（邮件接收）启动。服务台和其他通过邮件回复的功能不起作用。此问题已在 16.6.1 中修复。

解决方法是在您的极狐GitLab 安装中运行以下命令，以修补受影响的文件：

{{< tabs >}}

{{< tab title=”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

{{< /tab >}}

{{< tab title=”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

{{< /tab >}}

{{< /tabs >}}

收件邮件被具有邮箱地址限制的提供商拒绝

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

作为解决方法，保持较短的路径：

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