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.
It's possible to enable implicit approvals of code owners on their own changes. If enabled and the uploader of a patch set is a code owner, an approval of the uploader is assumed for all owned files. This means if a code owner uploads a change / patch set 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 uploader.
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.
refs/meta/config branch that 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 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. To avoid situations like this it is recommended to not enable implicit approvals.
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.
Back to @PLUGIN@ documentation index
Part of Gerrit Code Review