Skip to content

G
gitlab-ce
Commit c6ddf425 authored by Cody West's avatar Cody West Committed by Evan Read
Browse files
Options

Reorganize incoming email doc 

Configuration examples were moved into their own section for the purpose
of organizing and being able to link directly.
parent 3b899d82
Show whitespace changes
Inline Side-by-side
Showing with 195 additions and 190 deletions
doc/administration/incoming_email.md
View file @ c6ddf425
......@@ -95,133 +95,97 @@ for a real-world example of this exploit.
### Omnibus package installations
1. Find the `incoming_email` section in `/etc/gitlab/gitlab.rb`, enable the
feature and fill in the details for your specific IMAP server and email account:
1. Find the `incoming_email` section in `/etc/gitlab/gitlab.rb`, enable the feature
and fill in the details for your specific IMAP server and email account (see [examples](#config-examples) below).
Configuration for Postfix mail server, assumes mailbox
incoming@gitlab.example.com
```ruby
gitlab_rails['incoming_email_enabled'] = true
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it 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
1. Reconfigure GitLab for the changes to take effect:
# 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
```sh
sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart
```
Configuration for Gmail / Google Apps, assumes mailbox
gitlab-incoming@gmail.com
1. Verify that everything is configured correctly:
```ruby
gitlab_rails['incoming_email_enabled'] = true
```sh
sudo gitlab-rake gitlab:incoming_email:check
```
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@gmail.com"
Reply by email should now be working.
# 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]"
### Installations from source
# 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
1. Go to the GitLab installation directory:
# 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
```sh
cd /home/git/gitlab
```
Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the
catch-all mailbox incoming@exchange.example.com
```ruby
gitlab_rails['incoming_email_enabled'] = true
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it 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"
1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature
and fill in the details for your specific IMAP server and email account (see [examples](#config-examples) below).
# 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]"
1. Enable `mail_room` in the init script at `/etc/default/gitlab`:
# 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
```sh
sudo mkdir -p /etc/default
echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab
```
1. Reconfigure GitLab for the changes to take effect:
1. Restart GitLab:
```sh
sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart
sudo service gitlab restart
```
1. Verify that everything is configured correctly:
```sh
sudo gitlab-rake gitlab:incoming_email:check
sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
```
1. Reply by email should now be working.
Reply by email should now be working.
### Installations from source
### Config examples
1. Go to the GitLab installation directory:
#### Postfix
```sh
cd /home/git/gitlab
```
Example configuration for Postfix mail server. Assumes mailbox incoming@gitlab.example.com.
1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature
and fill in the details for your specific IMAP server and email account:
Example for Omnibus installs:
```sh
sudo editor config/gitlab.yml
```
```ruby
gitlab_rails['incoming_email_enabled'] = true
Configuration for Postfix mail server, assumes mailbox
incoming@gitlab.example.com
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "incoming+%{key}@gitlab.example.com"
```yaml
incoming_email:
# 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
```
Example for source installs:
```yaml
incoming_email:
enabled: true
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
......@@ -248,13 +212,47 @@ for a real-world example of this exploit.
mailbox: "inbox"
# The IDLE command timeout.
idle_timeout: 60
```
```
#### Gmail
Example configuration for Gmail/G Suite. Assumes mailbox gitlab-incoming@gmail.com.
Configuration for Gmail / Google Apps, assumes mailbox
gitlab-incoming@gmail.com
Example for Omnibus installs:
```yaml
incoming_email:
```ruby
gitlab_rails['incoming_email_enabled'] = true
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it 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
```
Example for source installs:
```yaml
incoming_email:
enabled: true
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
......@@ -281,13 +279,41 @@ for a real-world example of this exploit.
mailbox: "inbox"
# The IDLE command timeout.
idle_timeout: 60
```
```
Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the
catch-all mailbox incoming@exchange.example.com
#### MS Exchange
```yaml
incoming_email:
Example configuration for Microsoft Exchange mail server with IMAP enabled. Assumes the
catch-all mailbox incoming@exchange.example.com.
Example for Omnibus installs:
```ruby
gitlab_rails['incoming_email_enabled'] = true
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it 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
```
Example for source installs:
```yaml
incoming_email:
enabled: true
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
......@@ -314,25 +340,4 @@ for a real-world example of this exploit.
mailbox: "inbox"
# The IDLE command timeout.
idle_timeout: 60
```
1. Enable `mail_room` in the init script at `/etc/default/gitlab`:
```sh
sudo mkdir -p /etc/default
echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab
```
1. Restart GitLab:
```sh
sudo service gitlab restart
```
1. Verify that everything is configured correctly:
```sh
sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
```
1. Reply by email should now be working.
```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7