GitSwarm 2016.3-2 Documentation

Reply by email

GitSwarm can be set up to allow users to comment on issues and merge requests by replying to notification emails.

Requirement

Reply by email requires an IMAP-enabled email account. GitSwarm allows you to use three strategies for this feature:

using email sub-addressing
using a dedicated email address
using a catch-all mailbox

Email sub-addressing

If your provider or server supports email sub-addressing, we recommend using it.

Sub-addressing is a feature where any email to [email protected] will end up in the mailbox for [email protected], and is supported by providers such as Gmail, Google Apps, Yahoo! Mail, Outlook.com and iCloud, as well as the Postfix mail server which you can run on-premises.

Dedicated email address

This solution is really simple to set up: you just have to create an email address dedicated to receive your users' replies to GitSwarm notifications.

Catch-all mailbox

A catch-all mailbox for a domain will "catch all" the emails addressed to the domain that do not exist in the mail server.

How it works?

1. GitSwarm sends a notification email

When GitSwarm sends a notification and Reply by email is enabled, the Reply-To header is set to the address defined in your GitSwarm configuration, with the %{key} placeholder (if present) replaced by a specific "reply key". In addition, this "reply key" is also added to the References header.

2. You reply to the notification email

When you reply to the notification email, your email client will:

send the email to the Reply-To address it got from the notification email
set the In-Reply-To header to the value of the Message-ID header from the notification email
set the References header to the value of the Message-ID plus the value of the notification email's References header.

3. GitSwarm receives your reply to the notification email

When GitSwarm receives your reply, it will look for the "reply key" in the following headers, in this order:

the To header
the References header

If it finds a reply key, it will be able to leave your reply as a comment on the entity the notification was about (issue, merge request, commit...).

For more details about the Message-ID, In-Reply-To, and References headers, please consult RFC 5322.

Set it up

If you want to use Gmail / Google Apps with Reply by email, make sure you have IMAP access enabled and allowed less secure apps to access the account.

To set up a basic Postfix mail server with IMAP access on Ubuntu, follow these instructions.

Package installations

Find the incoming_email section in /etc/gitswarm/gitswarm.rb, enable the feature and fill in the details for your specific IMAP server and email account:

# Configuration for Postfix mail server, assumes mailbox [email protected]
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}@gitswarm.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'] = "gitswarm.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"

# Configuration for Gmail / Google Apps, assumes mailbox [email protected]
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'] = "gitswarm-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'] = "[email protected]"
# 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"

Reconfigure GitSwarm and restart mailroom for the changes to take effect:
```
sudo gitswarm-ctl reconfigure
sudo gitswarm-ctl restart mailroom
```

Verify that everything is configured correctly:

sudo gitswarm-rake gitswarm:incoming_email:check

Reply by email should now be working.

Source installations

Go to the GitLab installation directory:
```
cd /home/git/gitlab
```

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:

sudo editor config/gitlab.yml

# Configuration for Postfix mail server, assumes mailbox [email protected]
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}@gitswarm.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: "gitswarm.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"

# Configuration for Gmail / Google Apps, assumes mailbox [email protected]
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: "gitswarm-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: "[email protected]"
  # 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"

Enable mail_room in the init script at /etc/default/gitlab:

sudo mkdir -p /etc/default
echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab

Restart GitSwarm:
```
sudo service gitlab restart
```

Verify that everything is configured correctly:

sudo -u git -H bundle exec rake gitswarm:incoming_email:check RAILS_ENV=production

Reply by email should now be working.

Development

Go to the GitLab installation directory.

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:

# Configuration for Gmail / Google Apps, assumes mailbox [email protected]
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: "gitswarm-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: "[email protected]"
  # 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"

As mentioned, the part after + is ignored, and this will end up in the mailbox for [email protected].

Uncomment the mail_room line in your Procfile:

mail_room: bundle exec mail_room -q -c config/mail_room.yml

Restart GitSwarm:
```
bundle exec foreman start
```

Verify that everything is configured correctly:

bundle exec rake gitswarm:incoming_email:check RAILS_ENV=development

Reply by email should now be working.