Document new incoming email address format
This commit is contained in:
parent
31f2c7b00e
commit
413ab73846
|
@ -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.
|
||||
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.
|
||||
|
||||
[Postfix mail server]: reply_by_email_postfix_setup.md
|
||||
|
||||
### 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 GitLab notifications.
|
||||
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.
|
||||
|
||||
### Catch-all mailbox
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
GitLab can be set up to allow users to comment on issues and merge requests by
|
||||
replying to notification emails.
|
||||
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.
|
||||
|
||||
### Dedicated email address
|
||||
|
||||
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 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
![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.
|
||||
|
||||
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.
|
||||
- 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).
|
||||
|
||||
|
|
Binary file not shown.
Before Width: | Height: | Size: 54 KiB After Width: | Height: | Size: 110 KiB |
|
@ -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.
|
||||
|
|
Loading…
Reference in New Issue