diff options
| -rw-r--r-- | doc/administration/incoming_email.md | 70 | ||||
| -rw-r--r-- | doc/development/emails.md | 30 | ||||
| -rw-r--r-- | doc/user/project/issues/create_new_issue.md | 40 | ||||
| -rw-r--r-- | doc/user/project/merge_requests/img/create_from_email.png | bin | 55777 -> 112256 bytes | |||
| -rw-r--r-- | doc/user/project/merge_requests/index.md | 12 |
5 files changed, 95 insertions, 57 deletions
diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 27a3710632d..05873e01a08 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -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) diff --git a/doc/development/emails.md b/doc/development/emails.md index 35ada35babe..8baf343b133 100644 --- a/doc/development/emails.md +++ b/doc/development/emails.md @@ -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` diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index c33d1365001..2bf4fa287e9 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -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. + + +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: - +- 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). diff --git a/doc/user/project/merge_requests/img/create_from_email.png b/doc/user/project/merge_requests/img/create_from_email.png Binary files differindex 610f0b3d0c1..5cb2afaf976 100644 --- a/doc/user/project/merge_requests/img/create_from_email.png +++ b/doc/user/project/merge_requests/img/create_from_email.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index d4f8cf929f6..a19989afb91 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -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. +  +_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. |
