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
Hide whitespace changes
Inline Side-by-side
Showing with 195 additions and 190 deletions
doc/administration/incoming_email.md
View file @ c6ddf425
...@@ -95,244 +95,249 @@ for a real-world example of this exploit. ...@@ -95,244 +95,249 @@ for a real-world example of this exploit.
### Omnibus package installations ### Omnibus package installations
1. Find the `incoming_email` section in `/etc/gitlab/gitlab.rb`, enable the 1. Find the `incoming_email` section in `/etc/gitlab/gitlab.rb`, enable the feature
feature and fill in the details for your specific IMAP server and email account: 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 1. Reconfigure GitLab for the changes to take effect:
incoming@gitlab.example.com
```ruby ```sh
gitlab_rails['incoming_email_enabled'] = true sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart
```
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. 1. Verify that everything is configured correctly:
# 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 ```sh
# With third party providers, this is usually the full email address. sudo gitlab-rake gitlab:incoming_email:check
# 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 Reply by email should now be working.
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". ### Installations from source
gitlab_rails['incoming_email_mailbox_name'] = "inbox"
# The IDLE command timeout. 1. Go to the GitLab installation directory:
gitlab_rails['incoming_email_idle_timeout'] = 60
```sh
cd /home/git/gitlab
``` ```
Configuration for Gmail / Google Apps, assumes mailbox 1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature
gitlab-incoming@gmail.com and fill in the details for your specific IMAP server and email account (see [examples](#config-examples) below).
```ruby 1. Enable `mail_room` in the init script at `/etc/default/gitlab`:
gitlab_rails['incoming_email_enabled'] = true
```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
```
Reply by email should now be working.
### Config examples
#### Postfix
Example configuration for Postfix mail server. Assumes mailbox incoming@gitlab.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 `@`).
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
# 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. # 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 `@`). # 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" address: "incoming+%{key}@gitlab.example.com"
# Email account username # Email account username
# With third party providers, this is usually the full email address. # 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. # With self-hosted email servers, this is usually the user part of the email address.
gitlab_rails['incoming_email_email'] = "gitlab-incoming@gmail.com" user: "incoming"
# Email account password # Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]" password: "[REDACTED]"
# IMAP server host # IMAP server host
gitlab_rails['incoming_email_host'] = "imap.gmail.com" host: "gitlab.example.com"
# IMAP server port # IMAP server port
gitlab_rails['incoming_email_port'] = 993 port: 143
# Whether the IMAP server uses SSL # Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true ssl: false
# Whether the IMAP server uses StartTLS # Whether the IMAP server uses StartTLS
gitlab_rails['incoming_email_start_tls'] = false start_tls: false
# The mailbox where incoming mail will end up. Usually "inbox". # The mailbox where incoming mail will end up. Usually "inbox".
gitlab_rails['incoming_email_mailbox_name'] = "inbox" mailbox: "inbox"
# The IDLE command timeout. # The IDLE command timeout.
gitlab_rails['incoming_email_idle_timeout'] = 60 idle_timeout: 60
``` ```
#### Gmail
Example configuration for Gmail/G Suite. Assumes mailbox gitlab-incoming@gmail.com.
Example for Omnibus installs:
```ruby
gitlab_rails['incoming_email_enabled'] = true
Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
catch-all mailbox incoming@exchange.example.com # 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"
```ruby # Email account username
gitlab_rails['incoming_email_enabled'] = true # 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. # 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 `@`). # 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. address: "gitlab-incoming+%{key}@gmail.com"
gitlab_rails['incoming_email_address'] = "incoming-%{key}@exchange.example.com"
# Email account username # Email account username
# Typically this is the userPrincipalName (UPN) # With third party providers, this is usually the full email address.
gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com" # With self-hosted email servers, this is usually the user part of the email address.
user: "gitlab-incoming@gmail.com"
# Email account password # Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]" password: "[REDACTED]"
# IMAP server host # IMAP server host
gitlab_rails['incoming_email_host'] = "exchange.example.com" host: "imap.gmail.com"
# IMAP server port # IMAP server port
gitlab_rails['incoming_email_port'] = 993 port: 993
# Whether the IMAP server uses SSL # Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true ssl: true
``` # Whether the IMAP server uses StartTLS
start_tls: false
1. Reconfigure GitLab for the changes to take effect:
```sh # The mailbox where incoming mail will end up. Usually "inbox".
sudo gitlab-ctl reconfigure mailbox: "inbox"
sudo gitlab-ctl restart # The IDLE command timeout.
``` idle_timeout: 60
```
1. Verify that everything is configured correctly: #### MS Exchange
```sh Example configuration for Microsoft Exchange mail server with IMAP enabled. Assumes the
sudo gitlab-rake gitlab:incoming_email:check catch-all mailbox incoming@exchange.example.com.
```
1. Reply by email should now be working. Example for Omnibus installs:
### Installations from source ```ruby
gitlab_rails['incoming_email_enabled'] = true
1. Go to the GitLab installation directory: # 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"
```sh # Email account username
cd /home/git/gitlab # 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. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature # IMAP server host
and fill in the details for your specific IMAP server and email account: 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 Example for source installs:
sudo editor config/gitlab.yml
```
Configuration for Postfix mail server, assumes mailbox ```yaml
incoming@gitlab.example.com incoming_email:
enabled: true
```yaml
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 `@`).
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.
user: "incoming"
# Email account password
password: "[REDACTED]"
# IMAP server host
host: "gitlab.example.com"
# IMAP server port
port: 143
# Whether the IMAP server uses SSL
ssl: false
# Whether the IMAP server uses StartTLS
start_tls: false
# The mailbox where incoming mail will end up. Usually "inbox".
mailbox: "inbox"
# The IDLE command timeout.
idle_timeout: 60
```
Configuration for Gmail / Google Apps, assumes mailbox # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
gitlab-incoming@gmail.com # 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.
```yaml address: "incoming-%{key}@exchange.example.com"
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 `@`).
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.
user: "gitlab-incoming@gmail.com"
# Email account password
password: "[REDACTED]"
# IMAP server host
host: "imap.gmail.com"
# IMAP server port
port: 993
# Whether the IMAP server uses SSL
ssl: true
# Whether the IMAP server uses StartTLS
start_tls: false
# The mailbox where incoming mail will end up. Usually "inbox".
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
```yaml
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.
address: "incoming-%{key}@exchange.example.com"
# Email account username
# Typically this is the userPrincipalName (UPN)
user: "incoming@ad-domain.example.com"
# Email account password
password: "[REDACTED]"
# IMAP server host
host: "exchange.example.com"
# IMAP server port
port: 993
# Whether the IMAP server uses SSL
ssl: true
# Whether the IMAP server uses StartTLS
start_tls: false
# The mailbox where incoming mail will end up. Usually "inbox".
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: # Email account username
# Typically this is the userPrincipalName (UPN)
user: "incoming@ad-domain.example.com"
# Email account password
password: "[REDACTED]"
```sh # IMAP server host
sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production host: "exchange.example.com"
``` # IMAP server port
port: 993
# Whether the IMAP server uses SSL
ssl: true
# Whether the IMAP server uses StartTLS
start_tls: false
1. Reply by email should now be working. # The mailbox where incoming mail will end up. Usually "inbox".
mailbox: "inbox"
# The IDLE command timeout.
idle_timeout: 60
```
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