Merge branch 'stable-2.11'
* stable-2.11:
Describe how admins can control what service users can do
Change-Id: I2d8d21b8f7745eae8a46dab26fe901b2a3e5714a
diff --git a/src/main/resources/Documentation/config.md b/src/main/resources/Documentation/config.md
index 443cd4b..1d5bdb2 100644
--- a/src/main/resources/Documentation/config.md
+++ b/src/main/resources/Documentation/config.md
@@ -66,3 +66,79 @@
`plugin.@PLUGIN@.createNotesAsync`
: Whether the Git notes on commits that are pushed by a service user
should be created asynchronously. By default false.
+
+Control what service users can do
+---------------------------------
+
+The @PLUGIN@ plugin provides a self-service for creating service users.
+Project owners can then grant access rights to the service users on
+their projects. Independent of these access rights Gerrit
+administrators have some control over what service users can do.
+
+### Git over SSH / Access to SSH API
+
+Every service user for which a public SSH key is uploaded can access
+Gerrit projects via Git over SSH (if the
+[Read](access-control.html#category_read) permission is granted).
+
+In addition these service users can make use of the Gerrit
+[SSH API](cmd-index.html#user_commands).
+
+E.g. this enables service users to be used for continuous integration
+builds: They can clone projects, fetch open changes and then vote and
+comment on the changes (for voting the corresponding
+[label permission](access-control.html#category_review_labels) must be
+assigned on the project).
+
+There is no setting to disable SSH access for service users.
+
+### Git over HTTP / Access to REST API
+
+To be able to do Git operations over HTTP and to access the Gerrit
+[REST API](rest-api.html) service users must have an HTTP password.
+
+Gerrit administrators can control by the
+[allowHttpPassword](#allowHttpPassword) plugin configuration parameter
+whether service user owners can generate HTTP passwords for their
+service users. As a consequence of setting this option to `false`
+by default service users can neither do git operations over HTTP nor
+access the Gerrit REST API. Still Gerrit administrators may approve
+access for certain service users by explicitly generating a HTTP
+passwords for them. This can be done on the service user screen.
+
+*WARNING*: If access to the REST API is enabled, service users can use
+the [Create Email REST endpoint](../../../Documentation/rest-api-accounts.html#create-account-email)
+in Gerrit core to create an email address even if
+[allowEmail](#allowEmail) is set to `false`.
+
+### Git Push
+
+To be able to push to Gerrit service users must have an email address.
+
+Gerrit administrators can control by the
+[allowEmail](#allowEmail) plugin configuration parameter whether
+service user owners can set email addresses for their service
+users. As a consequence of setting this option to `false` git push is
+by default not allowed for service users. Still Gerrit administrators
+may approve git push for certain service users by explicitly setting
+email addresses for them. This can be done on the service user screen.
+
+When git push is allowed, the plugin can be configured to
+[create a git note](#createNotes) on each commit pushed by a service
+user which records the service user owners at that point in time. This
+allows to track back which person is responsible for the commits done
+by the service user.
+
+### Block access rights for service users
+
+By automatically adding newly created service users to a Gerrit
+[group](#group) Gerrit administrators can use this group to globally
+block certain access rights for this group on the `All-Projects`
+project so that by default service users cannot do these operations.
+
+E.g. blocking push on `refs/heads/*` and `refs/meta/config` would
+prevent service users from pushing commits, while they still may push
+tags.
+
+Gerrit administrators can make exceptions for certain service users by
+removing them from the group for which access rights are blocked.
