265 lines
8.6 KiB
Plaintext
265 lines
8.6 KiB
Plaintext
= 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.
|
|
|
|
[[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.
|
|
+
|
|
* `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.
|
|
|
|
[[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 numeric ID 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
|
|
---------
|