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