diff options
author | Cody West <cwest@gitlab.com> | 2019-02-21 07:02:10 +0300 |
---|---|---|
committer | Evan Read <eread@gitlab.com> | 2019-02-21 07:02:10 +0300 |
commit | c6ddf4256312cf64e09e8b0d485d2323241cb084 (patch) | |
tree | b31d82f4813730fdf8d8f9d70cb14b927040b5c8 /doc | |
parent | 3b899d82dfa2365fb6079a9b198605e709d1e030 (diff) |
Reorganize incoming email doc
Configuration examples were moved into their own section for the purpose
of organizing and being able to link directly.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/administration/incoming_email.md | 385 |
1 files changed, 195 insertions, 190 deletions
diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 05873e01a08..658b2f55d30 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -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 +``` |