Commit 413ab738 authored by Brett Walker's avatar Brett Walker Committed by Mike Lewis

Document new incoming email address format

parent 31f2c7b0
...@@ -13,43 +13,45 @@ GitLab has several features based on receiving incoming emails: ...@@ -13,43 +13,45 @@ GitLab has several features based on receiving incoming emails:
## Requirements ## Requirements
Handling incoming emails requires an [IMAP]-enabled email account. GitLab Handling incoming emails requires an [IMAP](https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol)-enabled
requires one of the following three strategies: email account. GitLab requires one of the following three strategies:
- Email sub-addressing - Email sub-addressing (recommended)
- Dedicated email address
- Catch-all mailbox - Catch-all mailbox
- Dedicated email address (supports Reply by Email only)
Let's walk through each of these options. Let's walk through each of these options.
**If your provider or server supports email sub-addressing, we recommend using it.
Most features (other than reply by email) only work with sub-addressing.**
[IMAP]: https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol
### Email sub-addressing ### Email sub-addressing
[Sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) is [Sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) is
a feature where any email to `user+some_arbitrary_tag@example.com` will end up a mail server feature where any email to `user+arbitrary_tag@example.com` will end up
in the mailbox for `user@example.com`, and is supported by providers such as in the mailbox for `user@example.com` . It is supported by providers such as
Gmail, Google Apps, Yahoo! Mail, Outlook.com and iCloud, as well as the Gmail, Google Apps, Yahoo! Mail, Outlook.com, and iCloud, as well as the
[Postfix mail server] which you can run on-premises. [Postfix mail server](reply_by_email_postfix_setup.md), which you can run on-premises.
[Postfix mail server]: reply_by_email_postfix_setup.md TIP: **Tip:**
If your provider or server supports email sub-addressing, we recommend using it.
A dedicated email address only supports Reply by Email functionality.
A catch-all mailbox supports the same features as sub-addressing as of GitLab 11.7,
but sub-addressing is still preferred because only one email address is used,
leaving a catch-all available for other purposes beyond GitLab.
### Dedicated email address ### Catch-all mailbox
This solution is really simple to set up: you just have to create an email A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain
address dedicated to receive your users' replies to GitLab notifications. receives all emails addressed to the domain that do not match any addresses that
exist on the mail server.
### Catch-all mailbox As of GitLab 11.7, catch-all mailboxes support the same features as
email sub-addressing, but email sub-addressing remains our recommendation so that you
can reserve your catch-all mailbox for other purposes.
A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain will ### Dedicated email address
"catch all" the emails addressed to the domain that do not exist in the mail
server.
GitLab can be set up to allow users to comment on issues and merge requests by This solution is relatively simple to set up: you just need to create an email
replying to notification emails. address dedicated to receive your users' replies to GitLab notifications. However,
this method only supports replies, and not the other features of [incoming email](#incoming-email).
## Set it up ## Set it up
...@@ -160,14 +162,16 @@ for a real-world example of this exploit. ...@@ -160,14 +162,16 @@ for a real-world example of this exploit.
gitlab_rails['incoming_email_idle_timeout'] = 60 gitlab_rails['incoming_email_idle_timeout'] = 60
``` ```
Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the
mailbox incoming@exchange.example.com catch-all mailbox incoming@exchange.example.com
```ruby ```ruby
gitlab_rails['incoming_email_enabled'] = true gitlab_rails['incoming_email_enabled'] = true
# The email address replies are sent to - Exchange does not support sub-addressing so %{key} is not used here # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
gitlab_rails['incoming_email_address'] = "incoming@exchange.example.com" # 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"
# Email account username # Email account username
# Typically this is the userPrincipalName (UPN) # Typically this is the userPrincipalName (UPN)
...@@ -279,15 +283,17 @@ for a real-world example of this exploit. ...@@ -279,15 +283,17 @@ for a real-world example of this exploit.
idle_timeout: 60 idle_timeout: 60
``` ```
Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the
mailbox incoming@exchange.example.com catch-all mailbox incoming@exchange.example.com
```yaml ```yaml
incoming_email: incoming_email:
enabled: true enabled: true
# The email address replies are sent to - Exchange does not support sub-addressing so %{key} is not used here # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
address: "incoming@exchange.example.com" # 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 # Email account username
# Typically this is the userPrincipalName (UPN) # Typically this is the userPrincipalName (UPN)
......
...@@ -76,14 +76,32 @@ See the [Rails guides] for more info. ...@@ -76,14 +76,32 @@ See the [Rails guides] for more info.
## Email namespace ## Email namespace
If you need to implement a new feature which requires a new email handler, follow these rules: As of GitLab 11.7, we support a new format for email handler addresses. This was done to
support catch-all mailboxes.
- You must choose a namespace. The namespace cannot contain `/` or `+`, and cannot match `\h{16}`. If you need to implement a feature which requires a new email handler, follow these rules
- If your feature is related to a project, you will append the namespace **after** the project path, separated by a `+` for the format of the email key:
- If you have different actions in the namespace, you add the actions **after** the namespace separated by a `+`. The action name cannot contain `/` or `+`, , and cannot match `\h{16}`.
- You will register your handlers in `lib/gitlab/email/handler.rb`
Therefore, these are the only valid formats for an email handler: - Actions are always at the end, separated by `-`. For example `-issue` or `-merge-request`
- If your feature is related to a project, the key begins with the project identifiers (project path slug
and project id), separated by `-`. For example, `gitlab-org-gitlab-ce-20`
- Additional information, such as an author's token, can be added between the project identifiers and
the action, separated by `-`. For example, `gitlab-org-gitlab-ce-20-Author_Token12345678-issue`
- You register your handlers in `lib/gitlab/email/handler.rb`
Examples of valid email keys:
- `gitlab-org-gitlab-ce-20-Author_Token12345678-issue` (create a new issue)
- `gitlab-org-gitlab-ce-20-Author_Token12345678-merge-request` (create a new merge request)
- `1234567890abcdef1234567890abcdef-unsubscribe` (unsubscribe from a conversation)
- `1234567890abcdef1234567890abcdef` (reply to a conversation)
Please note that the action `-issue-` is used in GitLab Premium as the handler for the Service Desk feature.
### Legacy format
Although we continue to support the older legacy format, no new features should use a legacy format.
These are the only valid legacy formats for an email handler:
- `path/to/project+namespace` - `path/to/project+namespace`
- `path/to/project+namespace+action` - `path/to/project+namespace+action`
......
...@@ -39,34 +39,40 @@ It opens a new issue for that project labeled after its respective list. ...@@ -39,34 +39,40 @@ It opens a new issue for that project labeled after its respective list.
## New issue via email ## New issue via email
*This feature needs [incoming email](../../../administration/incoming_email.md) At the bottom of a project's Issues List page, a link to **Email a new issue to this project**
to be configured by a GitLab administrator to be available for CE/EE users, and is displayed if your GitLab instance has [incoming email](../../../administration/incoming_email.md) configured.
it's available on GitLab.com.*
At the bottom of a project's issue page, click ![Bottom of a project issues page](img/new_issue_from_email.png)
**Email a new issue to this project**, and you will find an email address
which belongs to you. You could add this address to your contact. When you click this link, an email address is displayed which belongs to you for creating issues in this project.
You can save this address as a contact in your email client for easy acceess.
This is a private email address, generated just for you. CAUTION: **Caution:**
**Keep it to yourself** as anyone who gets ahold of it can create issues or This is a private email address, generated just for you. **Keep it to yourself**,
merge requests as if they were you. You can add this address to your contact as anyone who gets ahold of it can create issues or merge requests as if they
list for easy access. were you. If the address is compromised, or you'd like it to be regenerated for
any reason, click **Email a new issue to this project** again and click the reset link.
Sending an email to this address will create a new issue on your behalf for Sending an email to this address will create a new issue on your behalf for
this project, where the email subject becomes the issue title, and the email this project, where:
body becomes the issue description. [Markdown] and [quick actions] are
supported.
![Bottom of a project issues page](img/new_issue_from_email.png) - The email subject becomes the issue title.
- The email body becomes the issue description.
- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported.
NOTE: **Note:**
In GitLab 11.7, we updated the format of the generated email address.
However the older format is still supported, allowing existing aliases
or contacts to continue working._
## New issue via URL with prefilled fields ## New issue via URL with prefilled fields
You can link directly to the new issue page for a given project, with prefilled You can link directly to the new issue page for a given project, with prefilled
field values using query string parameters in a URL. This is useful for embedding field values using query string parameters in a URL. This is useful for embedding
a URL in an external HTML page, and also certain scenarios where you want the user to a URL in an external HTML page, and also certain scenarios where you want the user to
create an issue with certain fields prefilled. create an issue with certain fields prefilled.
The title, description, and description template fields can be prefilled using The title, description, and description template fields can be prefilled using
this method. The description and description template fields cannot be pre-entered this method. The description and description template fields cannot be pre-entered
in the same URL (since a description template just populates the description field). in the same URL (since a description template just populates the description field).
......
...@@ -169,9 +169,9 @@ those conflicts in the GitLab UI. ...@@ -169,9 +169,9 @@ those conflicts in the GitLab UI.
## Create new merge requests by email ## Create new merge requests by email
*This feature needs [incoming email](../../../administration/incoming_email.md) _This feature needs [incoming email](../../../administration/incoming_email.md)
to be configured by a GitLab administrator to be available for CE/EE users, and to be configured by a GitLab administrator to be available for CE/EE users, and
it's available on GitLab.com.* it's available on GitLab.com._
You can create a new merge request by sending an email to a user-specific email You can create a new merge request by sending an email to a user-specific email
address. The address can be obtained on the merge requests page by clicking on address. The address can be obtained on the merge requests page by clicking on
...@@ -183,8 +183,16 @@ will be used as the merge request description. You need ...@@ -183,8 +183,16 @@ will be used as the merge request description. You need
this feature. If it's not enabled to your instance, you may ask your GitLab this feature. If it's not enabled to your instance, you may ask your GitLab
administrator to do so. administrator to do so.
This is a private email address, generated just for you. **Keep it to yourself**
as anyone who gets ahold of it can create issues or merge requests as if they were you.
You can add this address to your contact list for easy access.
![Create new merge requests by email](img/create_from_email.png) ![Create new merge requests by email](img/create_from_email.png)
_In GitLab 11.7, we updated the format of the generated email address.
However the older format is still supported, allowing existing aliases
or contacts to continue working._
### Adding patches when creating a merge request via e-mail ### Adding patches when creating a merge request via e-mail
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22723) in GitLab 11.5. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22723) in GitLab 11.5.
......
Markdown is supported
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