| # Configuration |
| |
| The global configuration of the @PLUGIN@ plugin is stored in the `gerrit.config` |
| file in the `plugin.@PLUGIN@` subsection. |
| |
| This page describes all available configuration parameters. For configuration |
| recommendations please consult the [config guide](#config-guide.html). |
| |
| ## <a id="projectLevelConfigFile"> |
| In addition some configuration can be done on the project level in |
| `@PLUGIN@.config` files that are stored in the `refs/meta/config` branches of |
| the projects. |
| |
| Parameters that are not set for a project are inherited from the parent project. |
| |
| # <a id="globalConfiguration">Global configuration in gerrit.config</a> |
| |
| <a id="pluginCodeOwnersDisabled">plugin.@PLUGIN@.disabled</a> |
| : Whether the code owners functionality is disabled for the project.\ |
| If `true` submitting changes doesn't require code owner approvals.\ |
| This allows projects to opt-out of the code owners functionality.\ |
| Can be overridden per project by setting |
| [codeOwners.disabled](#codeOwnersDisabled) in |
| `@PLUGIN@.config`.\ |
| By default `false`. |
| |
| <a id="pluginCodeOwnersDisabledBranch">plugin.@PLUGIN@.disabledBranch</a> |
| : An exact ref, a ref pattern or a regular expression to disable the code |
| owners functionality for the matched branches.\ |
| By using a negative lookahead, it's possible to match all but one |
| branches. E.g. to disable the code owners functionality for all branches |
| except the `refs/heads/master` branch the following regular expression |
| can be used: `^refs/(?!heads/master$).*` |
| For matched branches submitting changes doesn't require code owner |
| approvals.\ |
| This allows branches to opt-out of the code owners functionality.\ |
| Can be set multiple times.\ |
| Can be overridden per project by setting |
| [codeOwners.disabledBrancg](#codeOwnersDisabledBranch) in |
| `@PLUGIN@.config`.\ |
| By default unset. |
| |
| <a id="pluginCodeOwnersBackend">plugin.@PLUGIN@.backend</a> |
| : The code owners backend that should be used.\ |
| Can be overridden per project by setting |
| [codeOwners.backend](#codeOwnersBackend) in |
| `@PLUGIN@.config`.\ |
| The supported code owner backends are listed at the |
| [Backends](backends.html) page.\ |
| By default `find-owners`.\ |
| \ |
| **NOTE:** Be careful with changing this parameter as it invalidates all |
| existing [code owner config files](user-guide.html#codeOwnerConfigFiles). |
| E.g. by changing the backend code owner configurations may now be read |
| from different files, or even worse from the same files but with another |
| syntax so that the existing code owner config files can no longer be |
| parsed. |
| |
| <a id="pluginCodeOwnersFileExtension">plugin.@PLUGIN@.fileExtension</a> |
| : The file extension that should be used for code owner config files.\ |
| Allows to use different owner configurations for upstream and internal |
| in the same repository. E.g. if upstream uses `OWNERS` code owner config |
| files (no file extension configured) one could set `internal` as file |
| extension internally so that internally `OWNERS.internal` files are used |
| and the existing `OWNERS` files are ignored.\ |
| Can be overridden per project by setting |
| [codeOwners.fileExtension](#codeOwnersFileExtension) in |
| `@PLUGIN@.config`.\ |
| By default unset (no file extension is used). |
| |
| <a id="pluginCodeOwnersOverrideInfoUrl">plugin.@PLUGIN@.overrideInfoUrl</a> |
| : A URL for a page that provides host-specific information about how to |
| request a code owner override.\ |
| The frontend displays a link to this page on the change screen so that |
| users can discover the override instructions easily.\ |
| Can be overridden per project by setting |
| [codeOwners.overrideInfoUrl](#codeOwnersFileExtension) in |
| `@PLUGIN@.config`.\ |
| By default unset (no override info URL). |
| |
| <a id="pluginCodeOwnersEnableImplicitApprovals">plugin.@PLUGIN@.enableImplictApprovals</a> |
| : Whether an implicit code owner approval from the last uploader is |
| assumed.\ |
| If enabled, code owners need to be aware of their implicit approval when |
| they upload new patch sets for other users (e.g. if a contributor pushes |
| a change to a wrong branch and a code owner helps them to get it rebased |
| onto the correct branch, the rebased change has implicit approvals from |
| the code owner, since the code owner is the uploader).\ |
| If implicit code owner approvals are disabled, code owners can still |
| self-approve their own changes by voting on the change.\ |
| Can be overridden per project by setting |
| [codeOwners.enableImplictApprovals](#codeOwnersEnableImplicitApprovals) |
| in `@PLUGIN@.config`.\ |
| By default `false`. |
| |
| <a id="pluginCodeOwnersGlobalCodeOwner">plugin.@PLUGIN@.globalCodeOwner</a> |
| : The email of a user that should be a code owner globally across all |
| branches.\ |
| If global code owners should be omitted in the code owner suggestion |
| (e.g. because they are bots and cannot react to review requests), they |
| can be added to the `Service Users` group (since members of this group |
| are not suggested as code owners).\ |
| Can be specified multiple time to set multiple global code owners.\ |
| Can be overridden per project by setting |
| [codeOwners.globalCodeOwner](#codeOwnersGlobalCodeOwner) in |
| `@PLUGIN@.config`.\ |
| By default unset (no global code owners). |
| |
| <a id="pluginCodeOwnersReadOnly">plugin.@PLUGIN@.readOnly</a> |
| : Whether code owner config files are read-only.\ |
| Can be overridden per project by setting |
| [codeOwners.readOnly](#codeOwnersReadOnly) in |
| `@PLUGIN@.config`.\ |
| By default `false`. |
| |
| <a id="pluginCodeOwnersEnableValidationOnCommitReceived">plugin.@PLUGIN@.enableValidationOnCommitReceived</a> |
| : Policy for validating code owner config files when a commit is received. |
| Allowed values are `true` (the code owner config file validation is |
| enabled and the upload of invalid code owner config files is rejected), |
| `false` (the code owner config file validation is disabled, invalid code |
| owner config files are not rejected) and `dry_run` (code owner config |
| files are validated, but invalid code owner config files are not |
| rejected).\ |
| Should only be disabled if there is bot that validates the code owner |
| config files in open changes as part of a pre-submit validation.\ |
| Can be overridden per project by setting |
| [codeOwners.enableValidationOnCommitReceived](#codeOwnersEnableValidationOnCommitReceived) |
| in `@PLUGIN@.config`.\ |
| By default `true`. |
| |
| <a id="pluginCodeOwnersAllowedEmailDomain">plugin.@PLUGIN@.allowedEmailDomain</a> |
| : Email domain that allows to assign code ownerships to emails with this |
| domain.\ |
| Can be specified multiple times.\ |
| Code ownerships that are assigned to emails with non-allowed domains are |
| ignored and rejected on push.\ |
| By default unset (all email domains are allowed). |
| |
| <a id="pluginCodeOwnersRequiredApproval">plugin.@PLUGIN@.requiredApproval</a> |
| : Approval that is required from code owners to approve the files in a |
| change.\ |
| The required approval must be specified in the format |
| "\<label-name\>+\<label-value\>".\ |
| The configured label must exist for all projects for which this setting |
| applies (all projects that have code owners enabled and for which this |
| setting is not overridden).\ |
| If the definition of the configured label has [copy |
| rules](../../../Documentation/config-labels.html#label_copyAnyScore) |
| enabled so that votes are sticky across patch sets, also the code owner |
| approvals will be sticky.\ |
| Can be overridden per project by setting |
| [codeOwners.requiredApproval](#codeOwnersRequiredApproval) in |
| `@PLUGIN@.config`.\ |
| By default "Code-Review+1". |
| |
| <a id="pluginCodeOwnersOverrideApproval">plugin.@PLUGIN@.overrideApproval</a> |
| : Approval that is required to override the code owners submit check.\ |
| The override approval must be specified in the format |
| "\<label-name\>+\<label-value\>".\ |
| The configured label must exist for all projects for which this setting |
| applies (all projects that have code owners enabled and for which this |
| setting is not overridden).\ |
| Can be overridden per project by setting |
| [codeOwners.overrideApproval](#codeOwnersOverrideApproval) in |
| `@PLUGIN@.config`.\ |
| By default unset which means that the override functionality is |
| disabled. |
| |
| <a id="pluginCodeOwnersEnableExperimentalRestEndpoints">plugin.@PLUGIN@.enableExperimentalRestEndpoints</a> |
| : Whether experimental REST endpoints are enabled.\ |
| By default `false`. |
| |
| <a id="pluginCodeOwnersMergeCommitStrategy">plugin.@PLUGIN@.mergeCommitStrategy</a> |
| : Strategy that defines for merge commits which files require code owner |
| approvals.\ |
| \ |
| Can be `ALL_CHANGED_FILES` or `FILES_WITH_CONFLICT_RESOLUTION`.\ |
| \ |
| `ALL_CHANGED_FILES`:\ |
| All files which differ between the merge commmit that is being reviewed |
| and its first parent commit (which is the HEAD of the destination |
| branch) require code owner approvals.\ |
| Using this strategy is the safest option, but requires code owners to |
| also approve files which have been merged automatically.\ |
| Using this strategy makes sense if the code owners differ between |
| branches and the code owners in one branch don't trust what the code |
| owners in other branches have approved, or if there are branches that do |
| not require code owner approvals at all.\ |
| \ |
| `FILES_WITH_CONFLICT_RESOLUTION`:\ |
| Only files which differ between the merge commmit that is being reviewed |
| and the auto merge commit (the result of automatically merging the 2 |
| parent commits, may contain Git conflict markers) require code owner |
| approvals.\ |
| Using this strategy means that files that have been merged automatically |
| and for which no manual conflict resolution has been done do not require |
| code owner approval.\ |
| Using this strategy is only recommended, if all branches require code |
| owner approvals and if the code owners in all branches are trusted. If |
| this is not the case, it is recommended to use the `ALL_CHANGED_FILES` |
| strategy instead.\ |
| *Example*: If this strategy is used and there is a branch that doesn't |
| require code owner approvals (e.g. a user sandbox branch or an |
| experimental branch) the code owners check can be bypassed by:\ |
| a) setting the branch that doesn't require code owner approvals to the |
| same commit as the main branch that does require code owner approvals\ |
| b) making a change in the branch that doesn't require code owner |
| approvals\ |
| c) merging this change back into the main branch that does require code |
| owner approvals\ |
| d) since it's a clean merge, all files are merged automatically and no |
| code owner approval is required\ |
| \ |
| Can be overridden per project by setting |
| [codeOwners.mergeCommitStrategy](#codeOwnersMergeCommitStrategy) in |
| `@PLUGIN@.config`.\ |
| By default `ALL_CHANGED_FILES`. |
| |
| <a id="pluginCodeOwnersFallbackCodeOwners">plugin.@PLUGIN@.fallbackCodeOwners</a> |
| : Policy that controls who should own paths that have no code owners |
| defined. This policy only applies if the inheritance of parent code |
| owners hasn't been explicity disabled in a relevant code owner config |
| file and if there are no unresolved imports.\ |
| \ |
| Can be `NONE` or `ALL_USERS`.\ |
| \ |
| `NONE`:\ |
| Paths for which no code owners are defined are owned by no one. This |
| means changes that touch these files can only be submitted with a code |
| owner override.\ |
| \ |
| `ALL_USERS`:\ |
| Paths for which no code owners are defined are owned by all users. This |
| means changes to these paths can be approved by anyone. If [implicit |
| approvals](#pluginCodeOwnersEnableImplicitApprovals) are enabled, these |
| files are always automatically approved. The `ALL_USERS` option should |
| only be used with care as it means that any path that is not covered by |
| the code owner config files is automatically opened up to everyone and |
| mistakes with configuring code owners can easily happen. This is why |
| this option is intended to be only used if requiring code owner |
| approvals should not be enforced.\ |
| \ |
| Can be overridden per project by setting |
| [codeOwners.fallbackCodeOwners](#codeOwnersFallbackCodeOwners) in |
| `@PLUGIN@.config`.\ |
| By default `NONE`. |
| |
| # <a id="projectConfiguration">Project configuration in @PLUGIN@.config</a> |
| |
| <a id="codeOwnersDisabled">codeOwners.disabled</a> |
| : Whether the code owners functionality is disabled for the project.\ |
| If `true` submitting changes doesn't require code owner approvals.\ |
| This allows projects to opt-out of the code owners functionality.\ |
| Overrides the global setting |
| [plugin.@PLUGIN@.disabled](#pluginCodeOwnersDisabled) in |
| `gerrit.config`.\ |
| By default `false`. |
| |
| <a id="codeOwnersDisabledBranch">codeOwners.disabledBranch</a> |
| : An exact ref, a ref pattern or a regular expression to disable the code |
| owners functionality for the matched branches.\ |
| By using a negative lookahead, it's possible to match all but one |
| branches. E.g. to disable the code owners functionality for all branches |
| except the `refs/heads/master` branch the following regular expression |
| can be used: `^refs/(?!heads/master$).*` |
| For matched branches submitting changes doesn't require code owner |
| approvals.\ |
| This allows branches to opt-out of the code owners functionality.\ |
| Can be set multiple times.\ |
| By default unset. |
| |
| <a id="codeOwnersBackend">codeOwners.backend</a> |
| : The code owners backend that should be used for the project.\ |
| Overrides the global setting |
| [plugin.@PLUGIN@.backend](#pluginCodeOwnersBackend) in `gerrit.config`.\ |
| Can be overridden per branch by setting |
| [codeOwners.\<branch\>.backend](#codeOwnersBranchBackend).\ |
| The supported code owner backends are listed at the |
| [Backends](backends.html) page.\ |
| If not set, the global setting |
| [plugin.@PLUGIN@.backend](#pluginCodeOwnersBackend) in `gerrit.config`\ |
| is used.\ |
| \ |
| **NOTE:** Be careful with changing this parameter as it invalidates all |
| existing [code owner config files](user-guide.html#codeOwnerConfigFiles). |
| E.g. by changing the backend code owner configurations may now be read |
| from different files, or even worse from the same files but with another |
| syntax so that the existing code owner config files can no longer be |
| parsed. |
| |
| <a id="codeOwnersBranchBackend">codeOwners.\<branch\>.backend</a> |
| : The code owners backend that should be used for this branch.\ |
| The branch can be the short or full name. If both configurations exist |
| the one for the full name takes precedence.\ |
| Overrides the per repository setting |
| [codeOwners.backend](#codeOwnersBackend).\ |
| The supported code owner backends are listed at the |
| [Backends](backends.html) page.\ |
| If not set, the project level configuration |
| [codeOwners.backend](#codeOwnersBackend) is used.\ |
| \ |
| **NOTE:** Be careful with changing this parameter as it invalidates all |
| existing [code owner config files](user-guide.html#codeOwnerConfigFiles). |
| E.g. by changing the backend code owner configurations may now be read |
| from different files, or even worse from the same files but with another |
| syntax so that the existing code owner config files can no longer be |
| parsed. |
| |
| <a id="codeOwnersFileExtension">codeOwners.fileExtension</a> |
| : The file extension that should be used for the code owner config files |
| in this project.\ |
| Allows to use different owner configurations for upstream and internal |
| in the same repository. E.g. if upstream uses `OWNERS` code owner config |
| files (no file extension configured) one could set `internal` as file |
| extension internally so that internally `OWNERS.internal` files are used |
| and the existing `OWNERS` files are ignored.\ |
| Overrides the global setting |
| [plugin.@PLUGIN@.fileExtension](#pluginCodeOwnersFileExtension) in |
| `gerrit.config`.\ |
| If not set, the global setting |
| [plugin.@PLUGIN@.fileExtension](#pluginCodeOwnersFileExtension) in |
| `gerrit.config` is used. |
| |
| <a id="codeOwnersOverrideInfoUrl">codeOwners.overrideInfoUrl</a> |
| : A URL for a page that provides project-specific information about how to |
| request a code owner override.\ |
| The frontend displays a link to this page on the change screen so that |
| users can discover the override instructions easily.\ |
| Overrides the global setting |
| [plugin.@PLUGIN@.overrideInfoUrl](#pluginCodeOwnersOverrideInfoUrl) in |
| `gerrit.config`.\ |
| If not set, the global setting |
| [plugin.@PLUGIN@.overrideInfoUrl](#pluginCodeOwnersOverrideInfoUrl) in |
| `gerrit.config` is used. |
| |
| <a id="codeOwnersEnableImplicitApprovals">codeOwners.enableImplicitApprovals</a> |
| : Whether an implicit code owner approval from the last uploader is |
| assumed.\ |
| If enabled, code owners need to be aware of their implicit approval when |
| they upload new patch sets for other users (e.g. if a contributor pushes |
| a change to a wrong branch and a code owner helps them to get it rebased |
| onto the correct branch, the rebased change has implicit approvals from |
| the code owner, since the code owner is the uploader).\ |
| If implicit code owner approvals are disabled, code owners can still |
| self-approve their own changes by voting on the change.\ |
| Overrides the global setting |
| [plugin.@PLUGIN@.enableImplicitApprovals](#pluginCodeOwnersenableImplicitApprovals) |
| in `gerrit.config`.\ |
| If not set, the global setting |
| [plugin.@PLUGIN@.enableImplicitApprovals](#pluginCodeOwnersenableImplicitApprovals) |
| in `gerrit.config` is used. |
| |
| <a id="codeOwnersGlobalCodeOwner">codeOwners.globalCodeOwner</a> |
| : The email of a user that should be a code owner globally across all |
| branches.\ |
| If global code owners should be omitted in the code owner suggestion |
| (e.g. because they are bots and cannot react to review requests), they |
| can be added to the `Service Users` group (since members of this group |
| are not suggested as code owners).\ |
| Can be specified multiple time to set multiple global code owners.\ |
| Overrides the global setting |
| [plugin.@PLUGIN@.globalCodeOwner](#pluginCodeOwnersGlobalCodeOwner) in |
| `gerrit.config`.\ |
| If not set, the global setting |
| [plugin.@PLUGIN@.globalCodeOwner](#pluginCodeOwnersGlobalCodeOwner) in |
| `gerrit.config` is used. |
| |
| <a id="codeOwnersReadOnly">codeOwners.readOnly</a> |
| : Whether code owner config files are read-only.\ |
| Overrides the global setting |
| [plugin.@PLUGIN@.readOnly](#pluginCodeOwnersReadOnly) in |
| `gerrit.config`.\ |
| If not set, the global setting |
| [plugin.@PLUGIN@.readOnly](#pluginCodeOwnersReadOnly) in |
| `gerrit.config` is used. |
| |
| <a id="codeOwnersEnableValidationOnCommitReceived">codeOwners.enableValidationOnCommitReceived</a> |
| : Policy for validating code owner config files when a commit is received. |
| Allowed values are `true` (the code owner config file validation is |
| enabled and the upload of invalid code owner config files is rejected), |
| `false` (the code owner config file validation is disabled, invalid code |
| owner config files are not rejected) and `dry_run` (code owner config |
| files are validated, but invalid code owner config files are not |
| rejected).\ |
| Should only be disabled if there is bot that validates the code owner |
| config files in open changes as part of a pre-submit validation.\ |
| Overrides the global setting |
| [plugin.@PLUGIN@.enableValidationOnCommitReceived](#pluginCodeOwnersEnableValidationOnCommitReceived) |
| in `gerrit.config`.\ |
| If not set, the global setting |
| [plugin.@PLUGIN@.enableValidationOnCommitReceived](#pluginCodeOwnersEnableValidationOnCommitReceived) |
| in `gerrit.config` is used. |
| |
| <a id="codeOwnersRequiredApproval">codeOwners.requiredApproval</a> |
| : Approval that is required from code owners to approve the files in a |
| change.\ |
| The required approval must be specified in the format |
| "\<label-name\>+\<label-value\>".\ |
| The configured label must exist for all projects for which this setting |
| applies (all child projects that have code owners enabled and for which |
| this setting is not overridden).\ |
| If the definition of the configured label has [copy |
| rules](../../../Documentation/config-labels.html#label_copyAnyScore) |
| enabled so that votes are sticky across patch sets, also the code owner |
| approvals will be sticky.\ |
| Overrides the global setting |
| [plugin.@PLUGIN@.requiredApproval](#pluginCodeOwnersRequiredApproval) in |
| `gerrit.config`.\ |
| If not set, the global setting |
| [plugin.@PLUGIN@.requiredApproval](#pluginCodeOwnersRequiredApproval) in |
| `gerrit.config` is used. |
| |
| <a id="codeOwnersOverrideApproval">codeOwners.overrideApproval</a> |
| : Approval that is required to override the code owners submit check.\ |
| The override approval must be specified in the format |
| "\<label-name\>+\<label-value\>".\ |
| The configured label must exist for all projects for which this setting |
| applies (all projects that have code owners enabled and for which this |
| setting is not overridden).\ |
| Overrides the global setting |
| [plugin.@PLUGIN@.overrideApproval](#pluginCodeOwnersOverrideApproval) in |
| `gerrit.config`.\ |
| If not set, the global setting |
| [plugin.@PLUGIN@.overrideApproval](#pluginCodeOwnersOverrideApproval) in |
| `gerrit.config` is used. |
| |
| <a id="codeOwnersMergeCommitStrategy">codeOwners.mergeCommitStrategy</a> |
| : Strategy that defines for merge commits which files require code owner |
| approvals.\ |
| Can be `ALL_CHANGED_FILES` or `FILES_WITH_CONFLICT_RESOLUTION` |
| (see [plugin.@PLUGIN@.mergeCommitStrategy](#pluginCodeOwnersMergeCommitStrategy) |
| for an explanation of these values).\ |
| Overrides the global setting |
| [plugin.@PLUGIN@.mergeCommitStrategy](#pluginCodeOwnersMergeCommitStrategy) |
| in `gerrit.config`.\ |
| If not set, the global setting |
| [plugin.@PLUGIN@.mergeCommitStrategy](#pluginCodeOwnersMergeCommitStrategy) |
| in `gerrit.config` is used. |
| |
| <a id="codeOwnersFallbackCodeOwners">codeOwners.fallbackCodeOwners</a> |
| : Policy that controls who should own paths that have no code owners |
| defined. This policy only applies if the inheritance of parent code |
| owners hasn't been explicity disabled in a relevant code owner config |
| file and if there are no unresolved imports.\ |
| Can be `NONE` or `ALL_USERS` (see |
| [plugin.@PLUGIN@.fallbackCodeOwners](#pluginCodeOwnersFallbackCodeOwners) |
| for an explanation of these values).\ |
| Overrides the global setting |
| [plugin.@PLUGIN@.fallbackCodeOwners](#pluginCodeOwnersFallbackCodeOwners) |
| in `gerrit.config`.\ |
| If not set, the global setting |
| [plugin.@PLUGIN@.fallbackCodeOwners](#pluginCodeOwnersFallbackCodeOwners) |
| in `gerrit.config` is used. |
| |
| --- |
| |
| Back to [@PLUGIN@ documentation index](index.html) |
| |
| Part of [Gerrit Code Review](../../../Documentation/index.html) |
| |
