BigW Consortium Gitlab

Name Last update
..
README.md
postfix.md

Reply by email

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

Get a mailbox

Reply by email requires an IMAP-enabled email account, with a provider or server that supports email sub-addressing. Sub-addressing is a feature where any email to user+some_arbitrary_tag@example.com will end up in the mailbox for user@example.com, 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.

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

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

Set it up

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:

    # Configuration for Postfix mail server, assumes mailbox incoming@gitlab.example.com
    gitlab_rails['incoming_email_enabled'] = true
    
    # The email address including a placeholder for the key that references the item being replied to.
    # The `%{key}` placeholder is added after the user part, 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"
    # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com
    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 `%{key}` placeholder is added after the user part, after a `+` character, 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"

    As mentioned, the part after + in the address is ignored, and any email sent here will end up in the mailbox for incoming@gitlab.example.com/gitlab-incoming@gmail.com.

  2. Reconfigure GitLab for the changes to take effect:

    sudo gitlab-ctl reconfigure
  3. Verify that everything is configured correctly:

    sudo gitlab-rake gitlab:incoming_email:check
  4. Reply by email should now be working.

Installations from source

  1. Go to the GitLab installation directory:

    cd /home/git/gitlab
  2. 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 incoming@gitlab.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 `%{key}` placeholder is added after the user part, after a `+` character, 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"
    # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com
    incoming_email:
      enabled: true
    
      # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
      # The `%{key}` placeholder is added after the user part, after a `+` character, 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"

    As mentioned, the part after + in the address is ignored, and any email sent here will end up in the mailbox for incoming@gitlab.example.com/gitlab-incoming@gmail.com.

  3. 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
  4. Restart GitLab:

    sudo service gitlab restart
  5. Verify that everything is configured correctly:

    sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
  6. Reply by email should now be working.

Development

  1. Go to the GitLab installation directory.

  2. 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 gitlab-incoming@gmail.com
    incoming_email:
      enabled: true
    
      # The email address including a placeholder for the key that references the item being replied to.
      # The `%{key}` placeholder is added after the user part, 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"

    As mentioned, the part after + is ignored, and this will end up in the mailbox for gitlab-incoming@gmail.com.

  3. Uncomment the mail_room line in your Procfile:

    mail_room: bundle exec mail_room -q -c config/mail_room.yml
  4. Restart GitLab:

    bundle exec foreman start
  5. Verify that everything is configured correctly:

    bundle exec rake gitlab:incoming_email:check RAILS_ENV=development
  6. Reply by email should now be working.