README.md 6.87 KB
Newer Older
Douwe Maan's avatar
Douwe Maan committed
1 2 3 4
# Reply by email

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

Douwe Maan's avatar
Douwe Maan committed
5
## Get a mailbox
Douwe Maan's avatar
Douwe Maan committed
6

Douwe Maan's avatar
Douwe Maan committed
7
Reply by email requires an IMAP-enabled email account, with a provider or server that supports [email sub-addressing](https://en.wikipedia.org/wiki/Email_address#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, Yahoo! Mail, Outlook.com and iCloud, as well as the Postfix mail server which you can run on-premises.
Douwe Maan's avatar
Douwe Maan committed
8

Douwe Maan's avatar
Douwe Maan committed
9 10 11
If you want to use Gmail with Reply by email, make sure you have [IMAP access enabled](https://support.google.com/mail/troubleshooter/1668960?hl=en#ts=1665018) and [allow less secure apps to access the account](https://support.google.com/accounts/answer/6010255).

To set up a basic Postfix mail server with IMAP access on Ubuntu, follow [these instructions](./postfix.md).
Douwe Maan's avatar
Douwe Maan committed
12

Douwe Maan's avatar
Douwe Maan committed
13 14
## Set it up

15
In this example, we'll use the Gmail address `gitlab-replies@gmail.com`.
Douwe Maan's avatar
Douwe Maan committed
16

17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
### Omnibus package installations

1. Find the `reply_by_email` section in `/etc/gitlab/gitlab.rb`, enable the feature, enter the email address including a placeholder for the `reply_key` and fill in the details for your specific IMAP server and email account:

    ```ruby
    gitlab_rails['reply_by_email_enabled'] = true
    gitlab_rails['reply_by_email_address'] = "gitlab-replies+%{reply_key}@gmail.com"
    gitlab_rails['reply_by_email_host'] = "imap.gmail.com" # IMAP server host
    gitlab_rails['reply_by_email_port'] = 993 # IMAP server port
    gitlab_rails['reply_by_email_ssl'] = true # Whether the IMAP server uses SSL
    gitlab_rails['reply_by_email_email'] = "gitlab-replies@gmail.com"  # Email account username. Usually the full email address.
    gitlab_rails['reply_by_email_password'] = "password" # Email account password
    gitlab_rails['reply_by_email_mailbox_name'] = "inbox" # The name of the mailbox where incoming mail will end up. Usually "inbox".
    ```

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

1. Reconfigure GitLab for the changes to take effect:

    ```sh
    sudo gitlab-ctl reconfigure
    ```

1. Verify that everything is configured correctly:

    ```sh
    sudo gitlab-rake gitlab:reply_by_email:check
    ```

1. Reply by email should now be working.

Douwe Maan's avatar
Douwe Maan committed
48 49
### Installations from source

Douwe Maan's avatar
Douwe Maan committed
50 51 52 53 54
1. Go to the GitLab installation directory:

    ```sh
    cd /home/git/gitlab
    ```
Douwe Maan's avatar
Douwe Maan committed
55 56

1. Find the `reply_by_email` section in `config/gitlab.yml`, enable the feature and enter the email address including a placeholder for the `reply_key`:
Douwe Maan's avatar
Douwe Maan committed
57 58 59 60

    ```sh
    sudo editor config/gitlab.yml
    ```
61

Douwe Maan's avatar
Douwe Maan committed
62 63 64 65 66 67
    ```yaml
    reply_by_email:
      enabled: true
      address: "gitlab-replies+%{reply_key}@gmail.com"
    ```

68
    As mentioned, the part after `+` in the address is ignored, and any email sent here will end up in the mailbox for `gitlab-replies@gmail.com`.
Douwe Maan's avatar
Douwe Maan committed
69

70
2. Copy `config/mail_room.yml.example` to `config/mail_room.yml`:
71

Douwe Maan's avatar
Douwe Maan committed
72
    ```sh
Douwe Maan's avatar
Douwe Maan committed
73
    sudo cp config/mail_room.yml.example config/mail_room.yml
Douwe Maan's avatar
Douwe Maan committed
74 75 76 77
    ```

3. Uncomment the configuration options in `config/mail_room.yml` and fill in the details for your specific IMAP server and email account:

Douwe Maan's avatar
Douwe Maan committed
78 79 80 81
    ```sh
    sudo editor config/mail_room.yml
    ```

Douwe Maan's avatar
Douwe Maan committed
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98
    ```yaml
    :mailboxes:
      -
        # IMAP server host
        :host: "imap.gmail.com"
        # IMAP server port
        :port: 993
        # Whether the IMAP server uses SSL
        :ssl: true
        # Email account username. Usually the full email address.
        :email: "gitlab-replies@gmail.com"
        # Email account password
        :password: "[REDACTED]"
        # The name of the mailbox where incoming mail will end up. Usually "inbox".
        :name: "inbox"
        # Always "sidekiq".
        :delivery_method: sidekiq
99 100
        # Always true.
        :delete_after_delivery: true
Douwe Maan's avatar
Douwe Maan committed
101 102 103 104 105 106 107 108 109 110 111
        :delivery_options:
          # The URL to the Redis server used by Sidekiq. Should match the URL in config/resque.yml.
          :redis_url: redis://localhost:6379
          # Always "resque:gitlab".
          :namespace: resque:gitlab
          # Always "incoming_email".
          :queue: incoming_email
          # Always "EmailReceiverWorker"
          :worker: EmailReceiverWorker
    ```

Douwe Maan's avatar
Douwe Maan committed
112
5. Edit the init script configuration at `/etc/default/gitlab` to enable `mail_room`:
113

Douwe Maan's avatar
Douwe Maan committed
114
    ```sh
Douwe Maan's avatar
Douwe Maan committed
115 116
    sudo mkdir -p /etc/default
    echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab
Douwe Maan's avatar
Douwe Maan committed
117 118
    ```

119
6. Restart GitLab:
120

Douwe Maan's avatar
Douwe Maan committed
121 122 123 124
    ```sh
    sudo service gitlab restart
    ```

125
7. Verify that everything is configured correctly:
126 127

    ```sh
128
    sudo -u git -H bundle exec rake gitlab:reply_by_email:check RAILS_ENV=production
129 130
    ```

Douwe Maan's avatar
Douwe Maan committed
131 132
8. Reply by email should now be working.

133 134 135 136 137
### Development

1. Go to the GitLab installation directory.

1. Find the `reply_by_email` section in `config/gitlab.yml`, enable the feature and enter the email address including a placeholder for the `reply_key`:
138

139 140 141 142 143 144 145 146
    ```yaml
    reply_by_email:
      enabled: true
      address: "gitlab-replies+%{reply_key}@gmail.com"
    ```

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

147
2. Copy `config/mail_room.yml.example` to `config/mail_room.yml`:
148

149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171
    ```sh
    sudo cp config/mail_room.yml.example config/mail_room.yml
    ```

3. Uncomment the configuration options in `config/mail_room.yml` and fill in the details for your specific IMAP server and email account:

    ```yaml
    :mailboxes:
      -
        # IMAP server host
        :host: "imap.gmail.com"
        # IMAP server port
        :port: 993
        # Whether the IMAP server uses SSL
        :ssl: true
        # Email account username. Usually the full email address.
        :email: "gitlab-replies@gmail.com"
        # Email account password
        :password: "[REDACTED]"
        # The name of the mailbox where incoming mail will end up. Usually "inbox".
        :name: "inbox"
        # Always "sidekiq".
        :delivery_method: sidekiq
172 173
        # Always true.
        :delete_after_delivery: true
174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
        :delivery_options:
          # The URL to the Redis server used by Sidekiq. Should match the URL in config/resque.yml.
          :redis_url: redis://localhost:6379
          # Always "resque:gitlab".
          :namespace: resque:gitlab
          # Always "incoming_email".
          :queue: incoming_email
          # Always "EmailReceiverWorker"
          :worker: EmailReceiverWorker
    ```

4. Uncomment the `mail_room` line in your `Procfile`:

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

6. Restart GitLab:
192

193 194 195 196
    ```sh
    bundle exec foreman start
    ```

197
7. Verify that everything is configured correctly:
198 199 200 201 202 203

    ```sh
    bundle exec rake gitlab:reply_by_email:check RAILS_ENV=development
    ```

8. Reply by email should now be working.