Validation

The code owners functionality relies on the validity of the following:

To reduce the risk that these files become invalid, they are validated when they are modified and invalid modifications are rejected. In addition code owner config files in a repository can be validated on demand by the Check code owners files REST endpoint.

NOTE: Most configuration issues are gracefully handled and do not break the code owners functionality (e.g. non-resolveable code owners or non-resolveable imports are silently ignored), however some configuration issue (non-parseable configuration files, configuration of a non-existing backend etc.) are severe errors and block the submission of all changes for which the affected configuration files are relevant.

NOTE: It's possible to disable the validation of code owner config files on push and setup an external validation by a CI bot instead. In this case findings would be posted on the change.

All validations are best effort to prevent invalid configurations from entering the repository, but not all possible issues can be prevented. Doing the validation is useful since it prevents most issues and also gives quick feedback to uploaders about typos (e.g. if an email is misspelled it's not breaking anything, but the intended change of the uploader is not working).

No validation is done when:

  • the @PLUGIN@ plugin is not installed/enabled (this means when the @PLUGIN@ plugin gets installed/enabled, it is possible that invalid configuration files already exist in the repository)
  • updates happen behind Gerrit's back (e.g. pushes that bypass Gerrit)
  • the validation is disabled via the enableValidationOnCommitReceived or enableValidationOnSubmit config options
  • the --code-owners~skip-validation push option was specified on push

In addition for code owner config files no validation is done when:

  • the code owners functionality is disabled for the repository or branch (this means when the code owners functionality gets enabled, it is possible that invalid code owner configs already exist in the repository)
  • the @PLUGIN@ plugin configuration is invalid (in this case we don't know which files are code owner config files, so we allow all uploads rather than blocking all uploads, to reduce the risk of breaking the plugin configuration code-owner.config files are validated too)

In addition it is possible that code owner config files get issues after they have been submitted:

When updating code owner config files the validation only rejects the update if it introduces new issues. This means the update is allowed if:

  • there are issues that are still present after the update, but the update doesn't introduce any new issues
  • the file was non-parseable and the update makes it parseable, but issues are present (since a parseable file with issues is better than a non-parseable file)
  • the file was non-parseable and with the update it is still non-parseable

For code owner config files the validation may also be performed on submit (in addition to the validation that is performed on upload of the change, see enableValidationOnSubmit config setting). Repeating the validation on submit can make sense because relevant configuration can change between the time a change is uploaded and the time a change is submitted. If enabled, on submit we repeat the exact same validation that was done on upload. This means, all visibility checks will be done from the perspective of the uploader.

Code owner config validation on branch creation

It's possible to enable validation of code owner config files on branch creation (off by default).

If the validation is enabled and a new branch is created, 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.

Validating code owner config files newly when a branch is created makes sense because:

  • the validation configuration of the new branch may differ from the validation configuration of the branch that already contains the commit
  • imports from other projects that do not specify a branch may not be resolvable: If a branch is not specified it's assumed that the code owner config file from the other project should be imported from the same branch that contains the importing code owner config. This means when a new branch foo is being created a code owner config file that is referenced by such an import is expected to be found in the branch foo of the other project, but this branch may not exist there so that the import is unresolvable. By validating the code owner config files on branch creation such unresolvable imports are detected and flagged.

What should be done if the creation of a branch fails due to invalid code owner config files is explained in the config FAQs.

Skip code owner config validation on demand

By setting the code-owners~skip-validation push option it is possible to skip the code owner config validation on push: git push -o code-owners~skip-validation origin HEAD:refs/for/master

For the Create Branch, Create Change, the Cherry Pick Revision and the Rebase REST endpoints skipping the code owner config validation is possible by setting code-owners~skip-validation with the value true as a validation option in the input (see field validation_options).

Using the push option or the validation option requires the calling user to have the Can Skip Code Owner Config Validation global capability. Host administrators have this capability implicitly assigned via the Administrate Server global capability.

NOTE: Using this option only makes sense if the code owner config validation on submit is disabled, as otherwise it's not possible to submit the created change (using the push option only skips the validation for the push, but not for the submission of the change).

Validation checks for code owner config files

For code owner config files the following checks are performed:

  • the code owner config files are parseable
  • the code owner emails are resolveable (unless this check is disabled):
    a code owners email is not resolveable if:
    • the account that owns it is inactive
    • the account that owns it is not visible to the uploader (according to accounts.visibility setting)
    • it is a non-visible secondary email
    • there is no account that has this email assigned
    • it is ambiguous (the same email is assigned to multiple active accounts)
    • it has an email domain that is disallowed (see allowedEmailDomain) configuration
  • the imports are resolveable (unless this check is disabled):
    an import is not resolveable if:
    • the imported file is not a code owner config file
    • the imported file is not parseable
    • the imported file doesn't exists
    • the branch from which the file should be imported doesn't exist or is not visible to the uploader
    • the project from which the file should be imported doesn't exist or is not visible to the uploader
    • the project from which the file should be imported doesn't permit reads (e.g. has the state HIDDEN)

NOTE: Non-resolvable code owner emails are rejected with a generic message, rather than informing about the exact reason why a code owner email is not resolvable. This is intentional and prevents that uploaders can probe the existence of emails/accounts (if specific reasons would be returned an uploader could create a code owner config file with arbitrary emails and then deduce from the messages which emails/accounts exist, which would a privacy issue).

NOTE: Whether commits that newly add non-resolvable code owners and non-resolvable imports are rejected on commit received and on submit is controlled by the rejectNonResolvableCodeOwners and rejectNonResolvableImports config settings.

The following things are not checked (not an exhaustive list):

  • Cycles in imports of owner config files:
    Detecting cycles in imports can be expensive and they are not seen as a problem. When imports are resolved we keep track of the imported code owner config files and stop if we see a code owner config file that we’ve imported already. This behaviour is consistent with how Gerrit handles cycles in group includes.
  • Impossible code owner configurations:
    It is possible to create a code owner configuration where some folders/files have no code owners. In this case nobody can give a code owner approval for these folders/files, and submitting changes to them requires a code owner override.

Validation checks for code-owners.config files

For the code-owner.config in the refs/meta/config branch the following checks are performed:

Back to @PLUGIN@ documentation index

Part of Gerrit Code Review