gerrit/Documentation/rest-api-access.txt

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

426 lines
12 KiB
Plaintext
Raw Normal View History

= Gerrit Code Review - /access/ REST API
This page describes the access rights related REST endpoints.
Please also take note of the general information on the
link:rest-api.html[REST API].
[[access-endpoints]]
== Access Rights Endpoints
[[list-access]]
=== List Access Rights
--
'GET /access/?project=link:rest-api-projects.html#project-name[\{project-name\}]'
--
Lists the access rights for projects. The projects for which the access
rights should be returned must be specified as `project` options. The
`project` can be specified multiple times.
As result a map is returned that maps the project name to
link:#project-access-info[ProjectAccessInfo] entities.
The entries in the map are sorted by project name.
.Request
----
GET /access/?project=MyProject&project=All-Projects HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
{
"All-Projects": {
"revision": "edd453d18e08640e67a8c9a150cec998ed0ac9aa",
"local": {
"GLOBAL_CAPABILITIES": {
"permissions": {
"priority": {
"rules": {
"15bfcd8a6de1a69c50b30cedcdcc951c15703152": {
"action": "BATCH"
}
}
},
"streamEvents": {
"rules": {
"15bfcd8a6de1a69c50b30cedcdcc951c15703152": {
"action": "ALLOW"
}
}
},
"administrateServer": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
}
}
}
}
},
"refs/meta/config": {
"permissions": {
"submit": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
},
"label-Code-Review": {
"label": "Code-Review",
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW",
"min": -2,
"max": 2
},
"global:Project-Owners": {
"action": "ALLOW",
"min": -2,
"max": 2
}
}
},
"read": {
"exclusive": true,
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
},
"push": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
}
}
},
"refs/for/refs/*": {
"permissions": {
"pushMerge": {
"rules": {
"global:Registered-Users": {
"action": "ALLOW"
}
}
},
"push": {
"rules": {
"global:Registered-Users": {
"action": "ALLOW"
}
}
}
}
},
"refs/tags/*": {
"permissions": {
Rename 'Push Annotated/Signed Tag' permission to 'Create Annotated/Signed Tag' Each tag type requires a special permission for the tag creation: - Lightweight tags require 'Create Reference' - Annontated tags require 'Push Annotated Tag' - Signed tags require 'Push Signed Tag' This naming is inconsistent and may be confusing. E.g. whether tags can be updated is controlled by the 'Push' permission on 'refs/tags/*' and not by the 'Push Annotated/Signed Tag' permission, as some users might expect. This change includes a schema migration that renames the permissions for creating annotated/signed tags. Permission rules in project.config that use the old names are still respected. They are automatically converted when the project config is saved the next time. This is needed so that multi-master sites can do a multi-step-migration: 1. First upgrade all hosts to the new binary: Projects may still contain permissions with the old names, new permissions are saved with the new names. 2. Run a background job on all hosts that migrates the permissions for all projects to the new names: Projects do not contain permissions with the old names, new permissions are saved with the new names. 3. Upgrade all hosts to a binary that doesn't respect the old names anymore. The migration for schema 130 is rewritten because ProjectConfig no longer allows to change the force flag for 'pushTag' without converting it to 'createTag'. Change-Id: I839be24f82a908b5184f15e746f3588a0d397b7e Signed-off-by: Edwin Kempin <ekempin@google.com>
2016-09-05 14:32:38 +02:00
"createSignedTag": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
},
Rename 'Push Annotated/Signed Tag' permission to 'Create Annotated/Signed Tag' Each tag type requires a special permission for the tag creation: - Lightweight tags require 'Create Reference' - Annontated tags require 'Push Annotated Tag' - Signed tags require 'Push Signed Tag' This naming is inconsistent and may be confusing. E.g. whether tags can be updated is controlled by the 'Push' permission on 'refs/tags/*' and not by the 'Push Annotated/Signed Tag' permission, as some users might expect. This change includes a schema migration that renames the permissions for creating annotated/signed tags. Permission rules in project.config that use the old names are still respected. They are automatically converted when the project config is saved the next time. This is needed so that multi-master sites can do a multi-step-migration: 1. First upgrade all hosts to the new binary: Projects may still contain permissions with the old names, new permissions are saved with the new names. 2. Run a background job on all hosts that migrates the permissions for all projects to the new names: Projects do not contain permissions with the old names, new permissions are saved with the new names. 3. Upgrade all hosts to a binary that doesn't respect the old names anymore. The migration for schema 130 is rewritten because ProjectConfig no longer allows to change the force flag for 'pushTag' without converting it to 'createTag'. Change-Id: I839be24f82a908b5184f15e746f3588a0d397b7e Signed-off-by: Edwin Kempin <ekempin@google.com>
2016-09-05 14:32:38 +02:00
"createTag": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
}
}
},
"refs/heads/*": {
"permissions": {
"forgeCommitter": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
},
"forgeAuthor": {
"rules": {
"global:Registered-Users": {
"action": "ALLOW"
}
}
},
"submit": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
},
"editTopicName": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW",
"force": true
},
"global:Project-Owners": {
"action": "ALLOW",
"force": true
}
}
},
"label-Code-Review": {
"label": "Code-Review",
"rules": {
"global:Registered-Users": {
"action": "ALLOW",
"min": -1,
"max": 1
},
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW",
"min": -2,
"max": 2
},
"global:Project-Owners": {
"action": "ALLOW",
"min": -2,
"max": 2
}
}
},
"create": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
},
"push": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
}
}
},
"refs/*": {
"permissions": {
"read": {
"rules": {
"global:Anonymous-Users": {
"action": "ALLOW"
},
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
}
}
}
}
}
},
"is_owner": true,
"owner_of": [
"GLOBAL_CAPABILITIES",
"refs/meta/config",
"refs/for/refs/*",
"refs/tags/*",
"refs/heads/*",
"refs/*"
],
"can_upload": true,
"can_add": true,
"can_add_tags": true,
"config_visible": true,
"groups": {
"53a4f647a89ea57992571187d8025f830625192a": {
"url": "#/admin/groups/uuid-53a4f647a89ea57992571187d8025f830625192a",
"options": {},
"description": "Gerrit Site Administrators",
"group_id": 1,
"owner": "Administrators",
"owner_id": "53a4f647a89ea57992571187d8025f830625192a",
"created_on": "2009-06-08 23:31:00.000000000",
"name": "Administrators"
},
"global:Registered-Users": {
"options": {},
"name": "Registered Users"
},
"global:Project-Owners": {
"options": {},
"name": "Project Owners"
},
"15bfcd8a6de1a69c50b30cedcdcc951c15703152": {
"url": "#/admin/groups/uuid-15bfcd8a6de1a69c50b30cedcdcc951c15703152",
"options": {},
"description": "Users who perform batch actions on Gerrit",
"group_id": 2,
"owner": "Administrators",
"owner_id": "53a4f647a89ea57992571187d8025f830625192a",
"created_on": "2009-06-08 23:31:00.000000000",
"name": "Non-Interactive Users"
},
"global:Anonymous-Users": {
"options": {},
"name": "Anonymous Users"
}
}
},
"MyProject": {
"revision": "61157ed63e14d261b6dca40650472a9b0bd88474",
"inherits_from": {
"id": "All-Projects",
"name": "All-Projects",
"description": "Access inherited by all other projects."
},
"local": {},
"is_owner": true,
"owner_of": [
"refs/*"
],
"can_upload": true,
"can_add": true,
"can_add_tags": true,
"config_visible": true
}
}
----
[[json-entities]]
== JSON Entities
[[access-section-info]]
=== AccessSectionInfo
The `AccessSectionInfo` describes the access rights that are assigned
on a ref.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`permissions` ||
The permissions assigned on the ref of this access section as a map
that maps the permission names to link:#permission-info[PermissionInfo]
entities.
|==================================
[[permission-info]]
=== PermissionInfo
The `PermissionInfo` entity contains information about an assigned
permission.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`label` |optional|
The name of the label. Not set if it's not a label permission.
|`exclusive` |not set if `false`|
Whether this permission is assigned exclusively.
|`rules` ||
The rules assigned for this permission as a map that maps the UUIDs of
the groups for which the permission are assigned to
link:#permission-info[PermissionRuleInfo] entities.
|==================================
[[permission-rule-info]]
=== PermissionRuleInfo
The `PermissionRuleInfo` entity contains information about a permission
rule that is assigned to group.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`action` ||
The action of this rule. For normal permissions this can be `ALLOW`,
`DENY` or `BLOCK`. Special values for global capabilities are
`INTERACTIVE` and `BATCH`.
|`force` |not set if `false`|
Whether the force flag is set.
|`min` |
not set if range is empty (from `0` to `0`) or not set|
The min value of the permission range.
|`max` |
not set if range is empty (from `0` to `0`) or not set|
The max value of the permission range.
|==================================
[[project-access-info]]
=== ProjectAccessInfo
The `ProjectAccessInfo` entity contains information about the access
rights for a project.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`revision` ||
The revision of the `refs/meta/config` branch from which the access
rights were loaded.
|`inherits_from` |not set for the `All-Project` project|
The parent project from which permissions are inherited as a
link:rest-api-projects.html#project-info[ProjectInfo] entity.
|`local` ||
The local access rights of the project as a map that maps the refs to
link:#access-section-info[AccessSectionInfo] entities.
|`is_owner` |not set if `false`|
Whether the calling user owns this project.
|`owner_of` ||The list of refs owned by the calling user.
|`can_upload` |not set if `false`|
Whether the calling user can upload to any ref.
|`can_add` |not set if `false`|
Whether the calling user can add any ref.
|`can_add_tags` |not set if `false`|
Whether the calling user can add any tag ref.
|`config_visible` |not set if `false`|
Whether the calling user can see the `refs/meta/config` branch of the
project.
|`groups` ||A map of group UUID to
link:rest-api-groups.html#group-info[GroupInfo] objects, with names and
URLs for the group UUIDs used in the `local` map.
This will include names for groups that might
be invisible to the caller.
|`configWebLinks` ||
A list of URLs that display the history of the configuration file
governing this project's access rights.
|==================================
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------