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:
## Requirements
Handling incoming emails requires an [IMAP]-enabled email account. GitLab
requires one of the following three strategies:
Handling incoming emails requires an [IMAP](https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol)-enabled
email account. GitLab requires one of the following three strategies:
- Email sub-addressing
- Dedicated email address
- Email sub-addressing (recommended)
- Catch-all mailbox
- Dedicated email address (supports Reply by Email only)
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
[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
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.
[Postfix mail server]: reply_by_email_postfix_setup.md
a mail server feature where any email to `user+arbitrary_tag@example.com` will end up
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
[Postfix mail server](reply_by_email_postfix_setup.md), which you can run on-premises.
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
address dedicated to receive your users' replies to GitLab notifications.
A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain
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
"catch all" the emails addressed to the domain that do not exist in the mail
server.
### Dedicated email address
GitLab can be set up to allow users to comment on issues and merge requests by
replying to notification emails.
This solution is relatively simple to set up: you just need to create an email
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
......@@ -160,14 +162,16 @@ for a real-world example of this exploit.
gitlab_rails['incoming_email_idle_timeout'] = 60
```
Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes
mailbox incoming@exchange.example.com
Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the
catch-all mailbox incoming@exchange.example.com
```ruby
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
gitlab_rails['incoming_email_address'] = "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 `@`).
# 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
# Typically this is the userPrincipalName (UPN)
......@@ -279,15 +283,17 @@ for a real-world example of this exploit.
idle_timeout: 60
```
Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes
mailbox incoming@exchange.example.com
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 replies are sent to - Exchange does not support sub-addressing so %{key} is not used here
address: "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 `@`).
# 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)
......
......@@ -76,14 +76,32 @@ See the [Rails guides] for more info.
## 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 your feature is related to a project, you will append the namespace **after** the project path, separated by a `+`
- 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`
If you need to implement a feature which requires a new email handler, follow these rules
for the format of the email key:
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+action`
......
......@@ -39,34 +39,40 @@ It opens a new issue for that project labeled after its respective list.
## New issue via email
*This feature needs [incoming email](../../../administration/incoming_email.md)
to be configured by a GitLab administrator to be available for CE/EE users, and
it's available on GitLab.com.*
At the bottom of a project's Issues List page, a link to **Email a new issue to this project**
is displayed if your GitLab instance has [incoming email](../../../administration/incoming_email.md) configured.
At the bottom of a project's issue page, click
**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.
![Bottom of a project issues page](img/new_issue_from_email.png)
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.
**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.
CAUTION: **Caution:**
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. 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
this project, where the email subject becomes the issue title, and the email
body becomes the issue description. [Markdown] and [quick actions] are
supported.
this project, where:
![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
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
a URL in an external HTML page, and also certain scenarios where you want the user to
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
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
in the same URL (since a description template just populates the description field).
......
......@@ -169,9 +169,9 @@ those conflicts in the GitLab UI.
## 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
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
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
this feature. If it's not enabled to your instance, you may ask your GitLab
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)
_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
> [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