Config FAQ's

How to update the code-owners.config file for a project

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):

  • clone the repository
  • fetch and checkout the refs/meta/config branch (e.g. git fetch origin refs/meta/config && git checkout FETCH_HEAD)
  • create or edit the code-owners.config file
  • commit the changes
  • push the newly created commit back to the refs/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.

How to check if the code owners functionality is enabled for a project or branch

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_config
https://<host>/projects/<project-name>/code_owners.project_config
(remember to URL-encode the project-name and branch-name)

How to avoid issues with code owner config files

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.

How to investigate issues with code owner config files

If code owners config files are not working as expected, this is either caused by:

  • issues in the code owner config files
  • a bug in the @PLUGIN@ plugin

Since code owner config files are part of the source code, any issues with them should be investigated and fixed by the project owners and host administrators. To do this they can:

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.

How to setup code owner overrides

To setup code owner overrides do:

1. Define a label that should count as code owner override:

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

2. Configure this label as override approval:

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.

3. Assign permissions to vote on the override approval:

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.


Back to @PLUGIN@ documentation index

Part of Gerrit Code Review