Skip to content
Snippets Groups Projects
Commit c6ddf425 authored by Cody West's avatar Cody West Committed by Evan Read
Browse files

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
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/administration/incoming_email.md
+ 195
− 190
View file @ c6ddf425
@@ -95,244 +95,249 @@ 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
1. Reconfigure GitLab for the changes to take effect:
 
```ruby
gitlab_rails['incoming_email_enabled'] = true
```sh
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.
# 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"
1. Verify that everything is configured correctly:
 
# 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]"
```sh
sudo gitlab-rake gitlab:incoming_email:check
```
 
# 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
Reply by email should now be working.
 
# 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
### Installations from source
1. Go to the GitLab installation directory:
```sh
cd /home/git/gitlab
```
 
Configuration for Gmail / Google Apps, assumes mailbox
gitlab-incoming@gmail.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).
 
```ruby
gitlab_rails['incoming_email_enabled'] = true
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
```
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 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
# 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"
user: "incoming"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"
password: "[REDACTED]"
 
# IMAP server host
gitlab_rails['incoming_email_host'] = "imap.gmail.com"
host: "gitlab.example.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
port: 143
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true
ssl: false
# 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".
gitlab_rails['incoming_email_mailbox_name'] = "inbox"
mailbox: "inbox"
# 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
catch-all mailbox incoming@exchange.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'] = "gitlab-incoming+%{key}@gmail.com"
 
```ruby
gitlab_rails['incoming_email_enabled'] = true
# 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.
# 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"
address: "gitlab-incoming+%{key}@gmail.com"
 
# Email account username
# Typically this is the userPrincipalName (UPN)
gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com"
# 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
gitlab_rails['incoming_email_password'] = "[REDACTED]"
password: "[REDACTED]"
 
# IMAP server host
gitlab_rails['incoming_email_host'] = "exchange.example.com"
host: "imap.gmail.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
port: 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true
```
1. Reconfigure GitLab for the changes to take effect:
ssl: true
# Whether the IMAP server uses StartTLS
start_tls: false
 
```sh
sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart
```
# The mailbox where incoming mail will end up. Usually "inbox".
mailbox: "inbox"
# The IDLE command timeout.
idle_timeout: 60
```
 
1. Verify that everything is configured correctly:
#### MS Exchange
 
```sh
sudo gitlab-rake gitlab:incoming_email:check
```
Example configuration for Microsoft Exchange mail server with IMAP enabled. Assumes the
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
cd /home/git/gitlab
```
# 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. 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:
# 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 editor config/gitlab.yml
```
Example for source installs:
 
Configuration for Postfix mail server, assumes mailbox
incoming@gitlab.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 `@`).
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
```
```yaml
incoming_email:
enabled: true
 
Configuration for Gmail / Google Apps, assumes mailbox
gitlab-incoming@gmail.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 `@`).
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
```
# 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"
 
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
sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
```
# 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
 
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
```
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