| = Gerrit Code Review - Email Notifications |
| |
| == Description |
| |
| Gerrit can automatically notify users by email when new changes are |
| uploaded for review, after comments have been posted on a change, |
| or after the change has been submitted to a branch. |
| |
| [[recipient-types]] |
| == Recipient Type |
| |
| Those are the available recipient types: |
| |
| * `to`: The standard To field is used; addresses are visible to all. |
| * `cc`: The standard CC field is used; addresses are visible to all. |
| * `bcc`: SMTP RCPT TO is used to hide the address. |
| |
| [[user]] |
| == User Level Settings |
| |
| Individual users can configure email subscriptions by editing |
| watched projects through Settings > Watched Projects with the web UI. |
| |
| Specific projects may be watched, or the special project |
| `All-Projects` can be watched to watch all projects that |
| are visible to the user. |
| |
| link:user-search.html[Change search expressions] can be used to filter |
| change notifications to specific subsets, for example `branch:master` |
| to only see changes proposed for the master branch. If a filter would |
| match at the `All-Projects` level as well as a specific project, the |
| more specific project's notification settings are used. |
| |
| Notification mails for new changes and new patch sets are not sent to |
| the change owner. |
| |
| Notification mails for comments added on changes are not sent to the user |
| who added the comment unless the user has enabled the 'Every comment' |
| option in the user preferences. |
| |
| |
| [[project]] |
| == Project Level Settings |
| |
| Project owners and site administrators can configure project level |
| notifications, enabling Gerrit Code Review to automatically send |
| emails to team mailing lists, or groups of users. Project settings |
| are stored inside of the `refs/meta/config` branch of each Git |
| repository, and are placed inside of the `project.config` file. |
| |
| To edit the project level notify settings, ensure the project owner |
| has Push permission already granted for the `refs/meta/config` |
| branch. Consult link:access-control.html[access controls] for |
| details on how access permissions work. |
| |
| Initialize a temporary Git repository to edit the configuration: |
| ---- |
| mkdir cfg_dir |
| cd cfg_dir |
| git init |
| ---- |
| |
| Download the existing configuration from Gerrit: |
| ---- |
| git fetch ssh://localhost:29418/project refs/meta/config |
| git checkout FETCH_HEAD |
| ---- |
| |
| Enable notifications to an email address by adding to |
| `project.config`, this can be done using the `git config` command: |
| ---- |
| git config -f project.config --add notify.team.email team-address@example.com |
| git config -f project.config --add notify.team.email paranoid-manager@example.com |
| ---- |
| |
| Examining the project.config file with any text editor should show |
| a new notify section describing the email addresses to deliver to: |
| ---- |
| [notify "team"] |
| email = team-address@example.com |
| email = paranoid-manager@example.com |
| ---- |
| |
| Each notify section within a single project.config file must have a |
| unique name. The section name itself does not matter and may later |
| appear in the web UI. Naming a section after the email address or |
| group it delivers to is typical. Multiple sections can be specified |
| if different filters are needed. |
| |
| Commit the configuration change, and push it back: |
| ---- |
| git commit -a -m "Notify team-address@example.com of changes" |
| git push ssh://localhost:29418/project HEAD:refs/meta/config |
| ---- |
| |
| [[notify.name.email]]notify.<name>.email:: |
| + |
| List of email addresses to send matching notifications to. Each |
| email address should be placed on its own line. |
| + |
| Internal groups within Gerrit Code Review can also be named using |
| `group NAME` syntax. If this format is used the group's UUID must |
| also appear in the corresponding `groups` file. Gerrit will expand |
| the group membership and BCC all current users. |
| |
| [[notify.name.type]]notify.<name>.type:: |
| + |
| Types of notifications to send. If not specified, all notifications |
| are sent. |
| + |
| * `new_changes`: Only newly created changes. |
| * `new_patchsets`: Only newly created patch sets. |
| * `all_comments`: Only comments on existing changes. |
| * `submitted_changes`: Only changes that have been submitted. |
| * `abandoned_changes`: Only changes that have been abandoned. |
| * `all`: All notifications. |
| |
| + |
| Like email, this variable may be a list of options. |
| |
| [[notify.name.header]]notify.<name>.header:: |
| + |
| Email header used to list the destination. If not set BCC is used. |
| Only one value may be specified. To use different headers for each |
| address list them in different notify blocks. |
| |
| The possible options are the link:#recipient-types[recipient types]. |
| |
| [[notify.name.filter]]notify.<name>.filter:: |
| + |
| link:user-search.html[Change search expression] to match changes that |
| should be sent to the emails named in this section. Within a Git-style |
| configuration file double quotes around complex operator values may |
| need to be escaped, e.g. `filter = branch:\"^(maint|stable)-.*\"`. |
| Single quotes are illegal and must be omitted. |
| |
| When sending email to a bare email address in a notify block, Gerrit |
| Code Review ignores read access controls and assumes the administrator |
| has set the filtering options correctly. Project owners can implement |
| security filtering by adding the `visibleto:groupname` predicate to |
| the filter expression, for example: |
| |
| ---- |
| [notify "Developers"] |
| email = team-address@example.com |
| filter = visibleto:Developers |
| ---- |
| |
| When sending email to an internal group, the internal group's read |
| access is automatically checked by Gerrit and therefore does not |
| need to use the `visibleto:` operator in the filter. |
| |
| [[footers]] |
| == Email Footers |
| |
| Notification emails related to changes include metadata about the change |
| to support writing mail filters. This metadata is included in the form |
| of footers in the message content. For HTML emails, these footers are |
| hidden, but they can be examined by viewing the HTML source of messages. |
| |
| In this way users may apply filters and rules to their incoming Gerrit |
| notifications using the values of these footers. For example a Gmail |
| filter to find emails regarding reviews that you are a reviewer of might |
| take the following form. |
| |
| ---- |
| "Gerrit-Reviewer: Your Name <your.email@example.com>" |
| ---- |
| |
| [[Gerrit-MessageType]]Gerrit-MessageType:: |
| |
| The message type footer states the type of the message and will take one |
| of the following values. |
| |
| * abandon |
| * comment |
| * deleteReviewer |
| * deleteVote |
| * merged |
| * newchange |
| * newpatchset |
| * restore |
| * revert |
| * setassignee |
| |
| [[Gerrit-Change-Id]]Gerrit-Change-Id:: |
| |
| The change ID footer states the ID of the change, such as |
| `I3443af49fcdc16ca941ee7cf2b5e33c1106f3b1d`. |
| |
| [[Gerrit-Change-Number]]Gerrit-Change-Number:: |
| |
| The change number footer states the change number of the change, for |
| example `92191`. |
| |
| [[Gerrit-PatchSet]]Gerrit-PatchSet:: |
| |
| The patch set footer states the number of the patch set that the email |
| relates to. For example, a notification email for a vote being set on |
| the seventh patch set will take a value of `7`. |
| |
| [[Gerrit-Owner]]Gerrit-Owner:: |
| |
| The owner footer states the name and email address of the change's |
| owner. For example, `Owner Name <owner@example.com>`. |
| |
| [[Gerrit-Reviewer]]Gerrit-Reviewer:: |
| |
| The reviewer footers list the names and email addresses of the change's |
| reviewrs. One footer is included for each reviewer. For example, if a |
| change has two reviewers, the footers might include: |
| |
| ---- |
| Gerrit-Reviewer: Reviewer One <one@example.com> |
| Gerrit-Reviewer: Reviewer Two <two@example.com> |
| ---- |
| |
| [[Gerrit-CC]]Gerrit-CC:: |
| |
| The CC footers list the names and email addresses of those who have been |
| CC'd on the change. One footer is included for each reviewer. For |
| example, if a change CCs two users, the footers might include: |
| |
| ---- |
| Gerrit-CC: User One <one@example.com> |
| Gerrit-CC: User Two <two@example.com> |
| ---- |
| |
| [[Gerrit-Project]]Gerrit-Project:: |
| |
| The project footer states the project to which the change belongs. |
| |
| [[Gerrit-Branch]]Gerrit-Branch:: |
| |
| The branch footer states the abbreviated name of the branch that the |
| change targets. |
| |
| [[Gerrit-Comment-Date]]Gerrit-Comment-Date:: |
| |
| In comment emails, the comment date footer states the date that the |
| comment was posted. |
| |
| [[Gerrit-HasComments]]Gerrit-HasComments:: |
| |
| In comment emails, the has-comments footer states whether inline |
| comments had been posted in that notification using "Yes" or "No", for |
| example `Gerrit-HasComments: Yes`. |
| |
| [[Gerrit-HasLabels]]Gerrit-HasLabels:: |
| |
| In comment emails, the has-labels footer states whether label votes had |
| been posted in that notification using "Yes" or "No", for |
| example `Gerrit-HasLabels: No`. |
| |
| [[Gerrit-Comment-In-Reply-To]]Gerrit-Comment-In-Reply-To:: |
| |
| In comment emails, a comment-in-reply-to footer is present for each |
| account who has a comment that is replied-to in that set of comments. |
| For example, to apply a filter to Gerrit messages in which your own diff |
| comments are responded to, you might search for the following: |
| |
| ---- |
| Gerrit-Comment-In-Reply-To: User Name <user@example.com> |
| ---- |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |