The project-level configuration of the code-owners plugin is done in the code-owners.config file that is stored in the refs/meta/config branch of a project. If it is not present, all configuration parameters are inherited from the parent projects or the global configuration.
The code-owners.config file has the format of a Git config file (same as the project.config file).
To update the code-owners.config file do (requires to be a project owner):
refs/meta/config branch (e.g. git fetch origin refs/meta/config && git checkout FETCH_HEAD)code-owners.config filerefs/meta/config branch (e.g. git push origin HEAD:refs/meta/config)Some of the configuration parameters can also be set via the Update Code Owner Project Config REST endpoint.
To check if the code owners functionality is enabled for a single branch, use the Get Code Owner Branch Config REST endpoint and inspect the disabled field in the response (if it is not present, the code owners functionality is enabled).
To check if the code owners functionality is enabled for a project or for multiple branches, use the Get Code Owner Project Config REST endpoint and inspect the status in the response (an empty status means that the code owners functionality is enabled for all branches of the project).
You can invoke the REST endpoints via curl from the command-line or alternatively open the following URLs in a browser:https://<host>/projects/<project-name>/branches/<branch-name>/code_owners.branch_confighttps://<host>/projects/<project-name>/code_owners.project_config
(remember to URL-encode the project-name and branch-name)
To avoid issues with code owner config files it's highly recommended to keep the validation of code owner config files that is performed on receive commits and submit enabled, as it prevents that issues are newly introduced to code owner config files. Whether this validation is enabled and whether code owner config files with new issues are rejected is controlled by the following configuration parameters:
Since code owner config files can also get issues after they have been submitted, host administrators and project owners are also recommended to regularly check the existing code owner config files for issues by calling the Check Code Owner Config File REST endpoint (e.g. from a cronjob) and then fix the reported issues.
If code owners config files are not working as expected, this is either caused by:
Since code owner config files are part of the source code, any issues with them should be investigated and fixed by the project team, the project owners and the host administrators.
To do this they can:
debug_logs) is more detailed.Bugs with the @PLUGIN@ plugin should be filed as issues for the Gerrit team, but only after issues with the code owner config files have been excluded.
Also see above how to avoid issues with code owner config files in the first place.
If the code owners config suggestion is not working as expected, this is either caused by:
Issues with code owner config files, user permissions, account visibility and account states should be investigated and fixed by the project team, the project owners and the host administrators.
To do this they can:
debug_logs) is more detailed.--debug option of the List Code Owners REST endpoints to get debug information (field debug_logs) included into the response (requires the caller to have the Administrate Server global capability or the Check Code Owner global capability).Bugs with the @PLUGIN@ plugin should be filed as issues for the Gerrit team, but only after other causes have been excluded.
Also see above how to avoid issues with code owner config files in the first place.
When creating a new branch, all code owner config files that are contained in the initial commit are newly validated, even if the branch is created for a commit that already exists in the repository.
If creating a branch fails due to this validation, it is recommended to:
branches field in the CheckCodeOwnerConfigFilesInput) to see which code owner config files have issues.It's also possible to switch of the code owner config validation on branch creation by configuration.
Default code owners that apply to all branches can be defined in an OWNERS file in the root directory of the refs/meta/config branch.
To add an OWNERS file in the refs/meta/config branch do (requires to be a project owner):
refs/meta/config branch (e.g. git fetch origin refs/meta/config && git checkout FETCH_HEAD)OWNERS filerefs/meta/config branch (e.g. git push origin HEAD:refs/meta/config)To setup code owner overrides do:
Create a review label via the Create Label REST endpoint:
curl -X PUT -d '{"commit_message": "Create Owners-Override Label", "values": {" 0": "No Override", "+1": "Override"}}' --header "Content-Type: application/json" https://<gerrit-host>/a/projects/<project-name>/labels/Owners-Override
Configure the override label via the Update Code Owner Project Config REST endpoint:
curl -X PUT -d '{"override_approvals": ["Owners-Override+1"]}' --header "Content-Type: application/json" https://<gerrit-host>/a/projects/<project-name>/code_owners.project_config
Also see the description of the override_approval configuration parameter.
Go to the access screen of your project in the Gerrit web UI and assign permissions to vote on the override label.
Alternatively the permissions can also be assigned via the Set Access REST endpoint.
The global plugin configuration can either be maintained in the gerrit.config file or in the code-owners.config file in the refs/meta/config branch of the All-Projects project. From the perspective of the code-owners plugin both places are equally good. However which place is preferred can depend on the system setup, e.g. changes to gerrit.config may be harder to do and require a multi-day rollout, whereas changes of the All-Projects configuration can be done through the REST API and are always instant (this can also be a disadvantage as it means that also bad config changes are effective immediately).
NOTE: Any configuration that is done in All-Projects overrides the corresponding configuration that is inherited from gerrit.config.
NOTE: There are a few configuration parameters (e.g. for allowed email domains) that cannot be set on project level and hence must be set in gerrit.config.
The @PLUGIN@ plugin uses the Java NIO API which reads the default character encoding from the system language settings. On Unix this means the LANG and LC_CTYPE environment variables (setting one of them is sufficent). To enable unicode characters in file paths e.g. set: LANG=en_US.UTF-8
If paths are used that are not valid according to the system language setting (e.g. if a path contains unicode characters but LANG is en_US.iso88591) the Java NIO API throws a java.nio.file.InvalidPathException with the message Malformed input or input contains unmappable characters. If such an exception occurs code-owner requests return 409 Conflict, telling the user about the invalid path.
Back to @PLUGIN@ documentation index
Part of Gerrit Code Review