This page describes the code owners REST endpoints that are added by the @PLUGIN@ plugin.
Please also take note of the general information on the REST API.
‘GET /projects/{project-name}/code_owners.project_config’
Gets the code owner project configuration.
As a response a CodeOwnerProjectConfigInfo entity is returned that describes the code owner project configuration.
The response includes the configuration of all branches. If a caller is interested in a particular branch only, the Get Code Owner Branch Config REST endpoint should be used instead, as that REST endpoint is much faster if the project contains many branches.
GET /projects/foo%2Fbar/code_owners.project_config HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"general": {
"merge_commit_strategy": "ALL_CHANGED_FILES"
},
"status": {
"disabled_branches": [
"refs/meta/config"
]
},
"backend": {
"id": "find-owners",
"ids_by_branch": {
"refs/heads/experimental": "proto"
}
},
"required_approval": {
"label": "Code-Review",
"value": 1
},
"override_approval": [
{
"label": "Owners-Override",
"value": 1
}
]
}
‘POST /projects/{project-name}/code_owners.check_config’
Checks/validates the code owner config files in a project.
Requires that the caller is an owner of the project.
Input options can be set in the request body as a CheckCodeOwnerConfigFilesInput entity.
No validation is done for branches for which the code owner functionality is disabled, unless validate_disabled_branches is set to true in the input.
As a response a map is returned that maps a branch name to a map that maps an owner configuration file path to a list of ConsistencyProblemInfo entities.
Code owner config files that have no issues are omitted from the response.
POST /projects/foo%2Fbar/code_owners.check_config HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"refs/heads/master": {
"/OWNERS": [
{
"status": "ERROR",
"message": "code owner email 'foo@example.com' in '/OWNERS' cannot be resolved for John Doe"
},
{
"status": "ERROR",
"message": "code owner email 'bar@example.com' in '/OWNERS' cannot be resolved for John Doe"
}
],
"/foo/OWNERS": [
{
"status": "ERROR",
"message": "invalid global import in '/foo/OWNERS': '/not-a-code-owner-config' is not a code owner config file"
}
]
},
"refs/heads/stable-1.0" {},
"refs/heads/stable-1.1" {
"/foo/OWNERS": [
{
"status": "ERROR",
"message": "invalid global import in '/foo/OWNERS': '/not-a-code-owner-config' is not a code owner config file"
}
]
}
}
‘GET /projects/{project-name}/branches/{branch-id}/code_owners.branch_config’
Gets the code owner branch configuration.
As a response a CodeOwnerBranchConfigInfo entity is returned that describes the code owner branch configuration.
GET /projects/foo%2Fbar/branches/master/code_owners.branch_config HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"general": {
"merge_commit_strategy": "ALL_CHANGED_FILES"
},
"backend_id": "find-owners",
"required_approval": {
"label": "Code-Review",
"value": 1
},
"override_approval": [
{
"label": "Owners-Override",
"value": 1
}
]
}
‘GET /projects/{project-name}/branches/{branch-id}/code_owners.config_files/’
Lists the code owner config files in a branch.
This REST endpoint scans all code owner config files in the branch and it is expected that it can take a long time if the branch contains many files. This is why this REST endpoint must not be used in any critical paths where performance matters.
The following request parameters can be specified:
| Field Name | Description | |
|---|---|---|
include-non-parsable-files | optional | Includes non-parseable code owner config files in the response. By default false. Cannot be used in combination with the email option. |
email | optional | Code owner email that must appear in the returned code owner config files. |
path | optional | Path glob that must be matched by the returned code owner config files. |
GET /projects/foo%2Fbar/branches/master/code_owners.config_files HTTP/1.0
As response the paths of the code owner config files are returned as a list. The result also includes code owner config that use name prefixes (‘<prefix>_OWNERS’) or name extensions (‘OWNERS_<extension>’).
Non-parseable code owner config files are omitted from the response, unless the include-non-parsable-files option was set.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
"/OWNERS",
"/foo/OWNERS",
"/foo/bar/baz/OWNERS",
"/foo/bar/baz/OWNERS_BUILD"
]
‘GET /projects/{project-name}/branches/{branch-id}/code_owners.check/’
Checks the code ownership of a user for a path in a branch.
The following request parameters can be specified:
| Field Name | Description | |
|---|---|---|
email | mandatory | Email for which the code ownership should be checked. |
path | mandatory | Path for which the code ownership should be checked. |
user | optional | User for which the code owner visibility should be checked. If not specified the code owner visibility is not checked. Can be used to investigate why a code owner is not shown/suggested to this user. |
Requires that the caller has the Check Code Owner or the Administrate Server global capability.
This REST endpoint is intended to investigate code owner configurations that do not work as intended. The response contains debug logs that may point out issues with the code owner configuration. For example, with this REST endpoint it is possible to find out why a certain email that is listed as code owner in a code owner config file is ignored (e.g. because it is ambiguous or because it belongs to an inactive account).
GET /projects/foo%2Fbar/branches/master/code_owners.check?email=xyz@example.com&path=/foo/bar/baz.md HTTP/1.0
As response a CodeOwnerCheckInfo entity is returned.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"is_code_owner": "false",
"is_resolvable": "false",
"code_owner_config_file_paths": [
"/OWNERS",
],
"is_default_code_owner": "false",
"is_global_code_owner": "false",
"debug_logs": [
"checking code owner config file foo/bar:master:/OWNERS",
"found email xyz@example.com as code owner in /OWNERS",
"trying to resolve email xyz@example.com",
"resolving code owner reference CodeOwnerReference{email=xyz@example.com}",
"all domains are allowed",
"cannot resolve code owner email xyz@example.com: email is ambiguous",
"email xyz@example.com is not a code owner of path '/foo/bar/baz.md'"
]
}
‘POST /projects/{project-name}/branches/{branch-id}/code_owners.rename/’
Renames an email in all code owner config files in the branch.
The old and new email must be specified in the request body as RenameEmailInput.
The old and new email must both belong to the same Gerrit account.
All updates are done atomically within one commit. The calling user will be the author of this commit.
Requires that the calling user is a project owner (Owner permission on ‘refs/*’) or has direct push permissions for the branch.
POST /projects/foo%2Fbar/branches/master/code_owners.rename HTTP/1.0
As response a RenameEmailResultInfo entity is returned.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"commit": {
"commit": "",
"parents": [
{
"commit": "1efe2c9d8f352483781e772f35dc586a69ff5646",
"subject": "Fix Foo Bar"
}
],
"author": {
"name": "John Doe",
"email": "john.doe@example.com",
"date": "2020-03-30 18:08:08.000000000",
"tz": -420
},
"committer": {
"name": "Gerrit Code Review",
"email": "no-reply@gerritcodereview.com",
"date": "2020-03-30 18:08:08.000000000",
"tz": -420
},
"subject": "Rename email in code owner config files",
"message": "Rename email in code owner config files"
}
}
‘GET /projects/{project-name}/branches/{branch-id}/code_owners.config/{path}’
Gets a code owner config for a path in a branch.
The code owner config is returned as CodeOwnerConfigInfo entity
This REST endpoint is experimental which means that the response format is likely still going to be changed. It is only available if experimental REST endpoints are enabled in gerrit.config.
GET /projects/foo%2Fbar/branches/master/code_owners.config/%2Fdocs%2Fconfig HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"code_sets": [
"code_owners" [
{
"email": "jane.roe@example.com"
},
{
"email": "john.doe@example.com"
}
]
]
}
If the path does not exist or if no code owner config exists for the path ‘204 No Content’ is returned.
‘GET /projects/{project-name}/branches/{branch-id}/code_owners/{path}’
Lists the accounts that are code owners of a file or folder in a branch.
The code owners are computed from the owner configuration at the tip of the specified branch.
Code owners that
are omitted from the result.
The following request parameters can be specified:
| Field Name | Description | |
|---|---|---|
o | optional | Account option that controls which fields in the returned accounts should be populated. Can be specified multiple times. If not given, only the _account_id field for the account ID is populated. |
O | optional | Account option in hex. For the explanation see o parameter. |
limit|n | optional | Limit defining how many code owners should be returned at most. By default 10. |
seed | optional | Seed, as a long value, that should be used to shuffle code owners that have the same score. Can be used to make the sort order stable across several requests, e.g. to get the same set of random code owners for different file paths that have the same code owners. Important: the sort order is only stable if the requests use the same seed and the same limit. In addition, the sort order is not guaranteed to be stable if new accounts are created in between the requests, or if the account visibility is changed. |
revision | optional | Revision from which the code owner configs should be read as commit SHA1. Can be used to read historic code owners from this branch, but imports from other branches or repositories as well as default and global code owners from refs/meta/config are still read from the current revisions. If not specified the code owner configs are read from the HEAD revision of the branch. Not supported for getting code owners for a path in a change. |
As a response a list of CodeOwnerInfo entities is returned. The returned code owners are sorted by an internal score that expresses how good the code owners are considered as reviewers/approvers for the path. Code owners with higher scores are returned first. If code owners have the same score the order is random. If the path is owned by all users (e.g. the code ownership is assigned to ‘*’) a random set of (visible) users is returned, as many as are needed to fill up the requested limit.
The following factors are taken into account for computing the scores of the listed code owners:
Other factors like OOO state, recent review activity or code authorship are not considered.
GET /projects/foo%2Fbar/branches/master/code_owners/docs%2Findex.md HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"account": {
"_account_id": 1000096
}
},
{
"account": {
"_account_id": 1001439
},
}
]
There is no REST endpoint that allows to retrieve code owners for multiple paths/files at once with a single batch request, but callers are expected to send one request per path/file and do any necessary grouping of results (e.g. grouping of files with the same code owners) on their own.
To ensure a stable sort order across requests for different paths/files it's possible to set a seed on the requests that should be used to shuffle code owners that have the same score (see seed request parameter above).
To speed up getting code owners for multiple paths/files callers are advised to send batches of list code owners requests in parallel (e.g. 10) and start processing the results as soon as they come in (this approach is faster than having a batch REST endpoint, as the batch REST endpoint could only return results after the server has computed code owners for all paths).
‘GET /changes/{change-id}/code_owners.status’
Gets the code owner statuses for the files in a change.
The code owner statuses are always listed for the files in the current revision of the change (latest patch set).
The code owner statuses are returned as a CodeOwnerStatusInfo entity.
GET /changes/275378/code_owners.status HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"patch_set_number": 2,
"file_code_owner_statuses": [
{
"change_type": "ADDED",
"new_path_status" {
"path": "docs/readme.md",
"status": "APPROVED"
}
},
{
"change_type": "DELETED",
"old_path_status" {
"path": "docs/todo.txt",
"status": "PENDING"
}
},
{
"change_type": "RENAMED",
"old_path_status" {
"path": "user-introduction.txt",
"status": "INSUFFICIENT_REVIEWERS"
},
"new_path_status" {
"path": "docs/user-intro.md",
"status": "APPROVED"
}
}
]
}
If the destination branch of a change no longer exists (e.g. because it was deleted), 409 Conflict is returned. Since the code owners are retrieved from the destination branch, computing the code owner status is not possible, if the destination branch is missing.
‘GET /changes/{change-id}/revisions/{revison-id}/code_owners/{path}’
Suggests accounts that are code owners of a file in a change revision.
The code owners are computed from the owner configuration at the tip of the change's destination branch.
This REST endpoint has the exact same request and response format as the REST endpoint to list code owners for a path in a branch, but filters out code owners that which should be omitted from the code owner suggestion.
The following code owners are filtered out additionally:
Service Users group)In addition, by default the change number is used as seed if none was specified. This way the sort order on a change is always the same for files that have the exact same code owners (requires that the limit is the same on all requests).
‘POST /changes/{change-id}/revisions/{revison-id}/code_owners.check_config’
Checks/validates the code owner config files in a revision that have been modified.
The validation is performed from the perspective of the uploader, so that the validation is exactly the same as the validation that will be done on submit.
Input options can be set in the request body as a CheckCodeOwnerConfigFilesInRevisionInput entity.
As a response a map is returned that that maps an owner configuration file path to a list of ConsistencyProblemInfo entities.
Code owner config files that were not modified in the revision are omitted from the response.
POST /changes/20187/revisions/current/code_owners.check_config HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"/OWNERS": [
{
"status": "ERROR",
"message": "code owner email 'foo@example.com' in '/OWNERS' cannot be resolved for John Doe"
},
{
"status": "ERROR",
"message": "code owner email 'bar@example.com' in '/OWNERS' cannot be resolved for John Doe"
}
],
"/foo/OWNERS": [
{
"status": "ERROR",
"message": "invalid global import in '/foo/OWNERS': '/not-a-code-owner-config' is not a code owner config file"
}
]
}
All REST endpoints may return the following responses:
409 Conflict is returned if a request cannot be executed due to:An arbitrary absolute path.
The leading ‘/’ can be omitted.
The path may or may not exist in the branch.
The BackendInfo entity describes the code owner backend configuration.
| Field Name | Description | |
|---|---|---|
id | ID of the code owner backend that is configured for the project. | |
ids_by_branch | optional | IDs of the code owner backends that are configured for individual branches as map of full branch names to code owner backend IDs. Only contains entries for branches for which a code owner backend is configured that differs from the backend that is configured for the project (see id field). Configurations for non-existing and non-visible branches are omitted. Not set if no branch specific backend configuration is returned. |
The CheckCodeOwnerConfigFilesInput allows to set options for the Check Code Owner Config Files REST endpoint.
| Field Name | Description | |
|---|---|---|
validate_disabled_branches | optional | Whether code owner config files in branches for which the code owners functionality is disabled should be validated too. By default unset, false. |
branches | optional | List of branches for which code owner config files should be validated. The refs/heads/ prefix may be omitted. By default unset, which means that code owner config files in all branches should be validated. |
path | optional | Glob that limits the validation to code owner config files that have a path that matches this glob. By default unset, which means that all code owner config files should be validated. |
The CheckCodeOwnerConfigFilesInRevisionInput allows to set options for the Check Code Owner Config Files In Revision REST endpoint.
| Field Name | Description | |
|---|---|---|
path | optional | Glob that limits the validation to code owner config files that have a path that matches this glob. By default unset, which means that all modified code owner config files should be validated. |
The CodeOwnerCheckInfo entity contains the result of checking the code ownership of a user for a path in a branch.
| Field Name | Description |
|---|---|
is_code_owner | Whether the given email owns the specified path in the branch. True if: a) the given email is resolvable (see field is_resolvable') and b) any code owner config file assigns codeownership to the email for the path (see field code_owner_config_file_paths) or the email is configured as default code owner (see field is_default_code_owneror the email is configured as global code owner (see fieldis_global_code_owner`). |
is_resolvable | Whether the given email is resolvable for the specified user or the calling user if no user was specified. |
code_owner_config_file_paths | Paths of the code owner config files that assign code ownership to the specified email and path as a list. Note that if code ownership is assigned to the email via a code owner config files, but the email is not resolvable (see field is_resolvable field), the user is not a code owner. |
is_default_code_owner | Whether the given email is configured as a default code owner in the code owner config file in refs/meta/config. Note that if the email is configured as default code owner, but the email is not resolvable (see is_resolvable field), the user is not a code owner. |
is_global_code_owner | Whether the given email is configured as a global |
code owner. Note that if the email is configured as global code owner, but the email is not resolvable (see is_resolvable field), the user is not a code owner. | |
debug_logs | List of debug logs that may help to understand why the user is or isn't a code owner. |
The CodeOwnerConfigInfo entity contains information about a code owner config for a path.
| Field Name | Description | |
|---|---|---|
ignore_parent_code_owners | optional, not set if false | Whether code owners from parent code owner configs (code owner configs in parent folders) should be ignored. |
code_owner_sets | optional | A list of code owner sets as CodeOwnerSetInfo entities. |
The CodeOwnerInfo entity contains information about a code owner.
| Field Name | Description | |
|---|---|---|
account | optional | The account of the code owner as an AccountInfo entity. At the moment the account field is always set, but it's marked as optional as in the future we may also return groups as code owner and then the account field would be unset. |
The CodeOwnerBranchConfigInfo entity describes the code owner branch configuration.
| Field Name | Description | |
|---|---|---|
general | optional | The general code owners configuration as GeneralInfo entity. Not set if disabled is true. |
disabled | optional | Whether the code owners functionality is disabled for the branch. If true the code owners API is disabled and submitting changes doesn't require code owner approvals. Not set if false. |
backend_id | optional | ID of the code owner backend that is configured for the branch. Not set if disabled is true. |
required_approval | optional | The approval that is required from code owners to approve the files in a change as RequiredApprovalInfo entity. The required approval defines which approval counts as code owner approval. Any approval on this label with a value >= the given value is considered as code owner approval. Not set if disabled is true. |
override_approval | optional | Approvals that count as override for the code owners submit check as a list of RequiredApprovalInfo entities (sorted alphabetically). If multiple approvals are returned, any of them is sufficient to override the code owners submit check. All returned override approvals are guarenteed to have distinct label names. Any approval on these labels with a value >= the given values is considered as code owner override. If unset, overriding the code owners submit check is disabled. Not set if disabled is true. |
no_code_owners_defined | optional | Whether the branch doesn‘t contain any code owner config file yet. If a branch doesn’t contain any code owner config file yet, the projects owners are considered as code owners. Once a first code owner config file is added to the branch, the project owners are no longer code owners (unless code ownership is granted to them via the code owner config file). Not set if false or if disabled is true. |
The CodeOwnerProjectConfigInfo entity describes the code owner project configuration.
| Field Name | Description | |
|---|---|---|
general | optional | The general code owners configuration as GeneralInfo entity. Not set if status.disabled is true. |
status | optional | The code owner status configuration as CodeOwnersStatusInfo entity. Contains information about whether the code owners functionality is disabled for the project or for any branch. |
backend | optional | The code owner backend configuration as BackendInfo entity. Not set if status.disabled is true. |
required_approval | optional | The approval that is required from code owners to approve the files in a change as RequiredApprovalInfo entity. The required approval defines which approval counts as code owner approval. Not set if status.disabled is true. |
override_approval | optional | Approvals that count as override for the code owners submit check as a list of RequiredApprovalInfo entities. If multiple approvals are returned, any of them is sufficient to override the code owners submit check. All returned override approvals are guarenteed to have distinct label names. If unset, overriding the code owners submit check is disabled. Not set if disabled is true. |
The CodeOwnerReferenceInfo entity contains information about a code owner reference in a code owner config.
| Field Name | Description |
|---|---|
email | The email of the code owner. |
The CodeOwnerSetInfo entity defines a set of code owners.
| Field Name | Description | |
|---|---|---|
code_owners | optional | The list of code owners as CodeOwnerReferenceInfo entities. |
The CodeOwnerStatusInfo entity describes the code owner statuses for the files in a change.
| Field Name | Description |
|---|---|
patch_set_number | The number of the patch set for which the code owner statuses are returned. |
file_code_owner_statuses | List of the code owner statuses for the files in the change as FileCodeOwnerStatusInfo entities, sorted by new path, then old path. |
The CodeOwnersStatusInfo contains information about whether the code owners functionality is disabled for a project or for any branch.
| Field Name | Description | |
|---|---|---|
disabled | optional | Whether the code owners functionality is disabled for the project. If true the code owners API is disabled and submitting changes doesn't require code owner approvals. Not set if false. |
disabled_branches | optional | Branches for which the code owners functionality is disabled. Configurations for non-existing and non-visible branches are omitted. Not set if the disabled field is true or if no branch specific status configuration is returned. |
The FileCodeOwnerStatusInfo entity describes the code owner statuses for a file in a change.
| Field Name | Description | |
|---|---|---|
change_type | optional | The type of the file modification. Can be ADDED, MODIFIED, DELETED, RENAMED or COPIED. Not set if MODIFIED. |
old_path_status | optional | The code owner status for the old path as PathCodeOwnerStatusInfo entity. Only set if change_type is DELETED or RENAMED. |
new_path_status | optional | The code owner status for the new path as PathCodeOwnerStatusInfo entity. Not set if change_type is DELETED. |
The GeneralInfo entity contains general code owners configuration parameters.
| Field Name | Description | |
|---|---|---|
file_extension | optional | The file extension that is used for the code owner config files in this project. Not set if no file extension is used. |
merge_commit_strategy | Strategy that defines for merge commits which files require code owner approvals. Can be ALL_CHANGED_FILES or FILES_WITH_CONFLICT_RESOLUTION (see mergeCommitStrategy for an explanation of these values). | |
implicit_approvals | optional | Whether an implicit code owner approval from the last uploader is assumed (see enableImplicitApprovals for details). When unset, false. |
override_info_url | optional | Optional URL for a page that provides project/host-specific information about how to request a code owner override. |
fallback_code_owners | Policy that controls who should own paths that have no code owners defined. Possible values are: NONE: Paths for which no code owners are defined are owned by no one. ALL_USER: Paths for which no code owners are defined are owned by all users. |
The PathCodeOwnerStatusInfo entity describes the code owner status for a path in a change.
| Field Name | Description |
|---|---|
path | The path to which the code owner status applies. |
status | The code owner status for the path. Can be ‘INSUFFICIENT_REVIEWERS’ (the path needs a code owner approval, but none of its code owners is currently a reviewer of the change), PENDING (a code owner of this path has been added as reviewer, but no code owner approval for this path has been given yet) or APPROVED (the path has been approved by a code owner or a code owners override is present). |
The RenameEmailInput entity specifies how an email should be renamed.
| Field Name | Description | |
|---|---|---|
message | optional | Commit message that should be used for the commit that renames the email in the code owner config files. If not set the following default commit message is used: “Rename email in code owner config files” |
old_email | The old email that should be replaced with the new email. | |
new_email | The new email that should be used to replace the old email. |
The RenameEmailResultInfo entity describes the result of the rename email REST endpoint.
| Field Name | Description | |
|---|---|---|
commit | optional | The commit that did the email rename. Not set, if no update was necessary. |
The RequiredApprovalInfo entity describes an approval that is required for an action.
| Field Name | Description |
|---|---|
label | The name of label on which an approval is required. |
value | The voting value that is required on the label. |
Global capability that allows a user to call the Check Code Owner REST endpoint.
Assigning this capability allows users to inspect code ownerships. This may reveal accounts and secondary emails to the user that the user cannot see otherwise. Hence this capability should only ge granted to trusted users.
Administrators have this capability implicitly assigned.
Back to @PLUGIN@ documentation index
Part of Gerrit Code Review