The @PLUGIN@ plugin has many configuration parameters that can be used to customize its behavior. These configuration parameters are described in the config documentation. This guide gives some additional recommendations for the configuration, but doesn't cover all configuration parameters.
Please also check out the config FAQs.
Before installing/enabling the plugin, or enabling the code owners functionality for further projects, it is important to do some basic configuration. This includes choosing a code owner backend, defining the approvals that count as code owner approval and as code owner override, opting-out projects or branches and configuring the allowed email domain. All this configuration is covered in detail by the setup guide.
Some of the configuration parameters have an effect on the user workflow.
Code owner approvals and code owner overrides can be made sticky by enabling copy rules in the definitions of the labels that are configured as required approval and override approval.
Alternatively code owner approvals can be made sticky per file by enabling sticky approvals in the plugin configuration.
It's possible to enable implicit approvals of code owners on their own changes. If enabled, changes of code owners are automatically code owner approved, but only if the last patch set was uploaded by the change owner (change owner == last patch set uploader). This implict code owner approval covers all files that are owned by the change owner. This means if a code owner uploads a change that only touches files that they own, no approval from other code owners is required for submitting the change.
If implicit approvals are enabled, paths can be exempted from requiring code owner approvals by assigning the code ownership to all users, as then any modification to the path is always implicitly approved by the change owner.
NOTE: If implicit approvals are disabled, users can still self-approve their own changes by voting on the required label.
IMPORTANT: Enabling implicit approvals is considered unsafe, see security pitfalls below.
For merge commits the list of modified files depends on the base against which the merge commit is compared:
comparison against the destination branch (aka first parent commit): All files which differ between the merge commit and the destination branch. This includes all files which have been modified in the source branch since the last merge into the destination branch has been done.
comparison against the Auto-Merge (Auto-Merge = result of automatically merging the source branch into the destination branch): Only shows files for which a conflict resolution has been done.
Which files a users sees on the change screen depends on their base selection.
For the @PLUGIN@ plugin it can be configured which files of a merge commit require code owner approvals, all files that differ with the destination branch (case 1) or only files that differ with the Auto-Merge (case 2). If case 1 is configured, all file diffs that have been approved in one branch must be re-approved when they are merged into another branch. If case 2 is configured, only conflict resolutions have to be approved when a merge is done.
IMPORTANT: Requiring code owner approvals only for files that differ with the Auto-Merge (case 2) is considered unsafe, see security pitfalls below.
Code owners can be defined on different levels, which differ by scope. This section gives an overview of the different levels and explains when they should be used.
OWNERS file) in the refs/meta/config branch and apply for all branches (unless inheritance is ignored).refs/meta/config branch, but default code owners are suggested to users the same way as other code owners.In addition users can be allowed to override the code owner submit check. This permission is normally granted to users that that need to react to emergencies and need to submit changes quickly (e.g sheriffs) or users that need to make large-scale changes across many repositories.
By default, when code owner config files are modified they are validated on push. If any issues in the modified code owner config files are found, the push is rejected. This is important since non-parsable code owner config files make submissions fail which likely blocks the development teams, and hence needs to be prevented.
However rejecting pushes in case of invalid code owner config files is not an ideal workflow for everyone. Instead it may be wanted that the push always succeeds and that issues with modified code owner config files are then detected and reported by a CI bot. The CI bot would then post its findings as checks on the open change which prevent the change submission. To enable this the validation of code owner config files on push can be disabled, but then the host admins should setup a bot to do the validation of modified code owner config files externally. For this the bot could use the Check Code Owner Config Files In Revision REST endpoint.
If a respository is forked and code owners are used in the original repository, the code owner configuration of the original repository shouldn‘t apply for the fork (the fork should have different code owners, and if the fork is stored on another Gerrit host it’s also likely that the original code owners cannot be resolved on that host). In this case it is possible to configure a file extension for code owner config files in the fork so that its code owner config files do not clash with the original code owner config files.
While requiring code owner approvals is primarily considered as a code quality feature and not a security feature, many admins / projects owners are concerned about possibilities to bypass code owner approvals. These admins / projects owners should be aware that some configuration settings may make it possible to bypass code owner approvals, and hence using them is not recommended.
If implicit approvals are enabled, it is important that code owners are aware of their implicit approval when they upload new changes for other users.
Example:
To avoid situations like this it is recommended to not enable implicit approvals.
NOTE: Why are implicit approvals not always applied for the change owner?
If implicit approvals would be always applied for the change owner, and not only when the change owner is also the last uploader, anyone could upload a new patch set to a change that is owned by a code owner and get it implicitly approved by the change owner. This would be really bad, as it means that anyone could submit arbitrary code without a code owner having actually looked at it before the submission.
NOTE: Why are implicit approvals not always applied for the last uploader?
If implicit approvals would be always applied for the last uploader, and not only when the last uploader is also the change owner, changes would get implicitly approved whenever a code owner touches a change of somebody else (e.g. when editing the commit message, since editing the commit message creates a new patch set which has the user editing the commit message as an uploader). This would be bad, because code owners are not aware that editing the commit message of a change would implictly code-owner approve it.
If any branch doesn‘t require code owner approvals or if the code owners in any branch are not trusted, it is not safe to configure for merge commits that they only require code owner approvals for files that differ with the Auto-Merge. E.g. if there is a branch that doesn’t require code owner approvals, with this setting the code owners check can be bypassed by:
As soon as the code owners functionality is enabled for a project / branch, all files in it require code owner approvals. This means if any path doesn't have any code owners defined, submitting changes to the path is only possible with
Configuring all users as fallback code owners is problematic, as it can happen easily that code owner config files are misconfigured so that some paths are accidentally not covered by code owners. In this case, the affected paths would suddenly be open to all users, which may not be wanted. This is why configuring all users as fallback code owners is not recommended.
If all files / folders in a repository / branch are owned by the same users, using the @PLUGIN@ plugin is not needed and not recommended. Instead you should use plain Gerrit permissions to control who can approve changes:
Code-Review label with a voting range from -2 to +2 (see label configuration).Code-Review-2 to Code-Review+2 and allow other users only to vote from Code-Review-1 to Code-Review+1 (see label permissions)Code-Review+2 approval for making the change submittable, optionally with disallowing self approvals (see submit requirements).With this configuration a Code-Review+2 approval from a code owner is required for changes to become submittable.
Advantages of this approach over using the @PLUGIN@ plugin:
OWNERS files)Disadvantages:
Back to @PLUGIN@ documentation index
Part of Gerrit Code Review