src/main/resources/Documentation/config.md

Configuration
=============

The configuration of the @PLUGIN@ plugin is done in the `gerrit.config`
file.

```
  [plugin "@PLUGIN@"]
    group = Service Users
```

<a id="block"></a>
`plugin.@PLUGIN@.block`
:	A username which is forbidden to be used as name for a service
	user. The blocked username is case insensitive. The match can
	either be exact, have a wildcard ('*') at the end or use regular
	expressions, which have to start with '^'. If the regex pattern is not
	ending with '$', every username starting with a matching prefix will be
	blocked. Multiple usernames can be blocked by specifying multiple
	`plugin.@PLUGIN@.block` entries.
	Examples:

```
   [plugin "serviceuser"]
        block = johndoe
        block = jane*
        block = ^gerrit[0-9]*
```

<a id="group"></a>
`plugin.@PLUGIN@.group`
:	The name of an internal group to which newly created service users
	should be automatically added. Multiple groups can be specified by
	having multiple `plugin.@PLUGIN@.group` entries.

<a id="infoMessage"></a>
`plugin.@PLUGIN@.infoMessage`
:	HTML formatted message that should be displayed on the service user
	creation screen.

<a id="onSuccessMessage"></a>
`plugin.@PLUGIN@.onSuccessMessage`
:	Message that should be displayed after a service user was
	successfully created.

<a id="allowEmail"></a>
`plugin.@PLUGIN@.allowEmail`
:	Whether it is allowed for service user owners to set email
	addresses for their service users. Independent of this setting
	Gerrit administrators are always able to set email addresses for
	any service user.
	By default false.

<a id="allowHttpPassword"></a>
`plugin.@PLUGIN@.allowHttpPassword`
:	Whether it is allowed for service user owners to generate HTTP
    passwords for their service users. Independent of this setting
    Gerrit administrators are always able to set/generate HTTP
    passwords for any service user.
    By default false.

<a id="allowCustomHttpPassword"></a>
`plugin.@PLUGIN@.allowCustomHttpPassword`
:	Whether it is allowed for service user owners to set custom HTTP
	passwords for their service users. This option requires
	`plugin.@PLUGIN@.allowHttpPassword` to be true. Independent of this
	setting Gerrit administrators are always able to set custom HTTP
	passwords for any service user.
	By default false.

<a id="allowOwner"></a>
`plugin.@PLUGIN@.allowOwner`
:	Whether it is allowed to set an owner group for a service user.
	By default false.

<a id="createNotes"></a>
`plugin.@PLUGIN@.createNotes`
:	Whether commits of a service user should be annotated by a Git note
	that contains information about the current owners of the service
	user. This allows to find a real person that is responsible for
	this commit. To get such a Git note for each commit of a service
	user the 'Forge Committer' access right must be blocked for service
	users. By default true.

<a id="createNotes"></a>
`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.md#category_read) permission is granted).

In addition these service users can make use of the Gerrit
[SSH API](cmd-index.md#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.md#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.md) 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`, unless
[registration of email addresses in Gerrit is disabled](../../../Documentation/config-gerrit.html#sendemail.allowRegisterNewEmail).

### 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.