opendev/gerrit
Code Issues Proposed changes
6471515891
gerrit/Documentation/rest-api-access.txt
Edwin Kempin 62c156857e 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-08 13:50:04 +09:00

380 lines
11 KiB
Plaintext
Raw Blame 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": {
"createSignedTag": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
},
"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,
"config_visible": true
},
"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,
"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 if empty (from `0` to `0`) or not set|
The min value of the permission range.
|`max` |
not set if range if 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.
|`config_visible` |not set if `false`|
Whether the calling user can see the `refs/meta/config` branch of the
project.
|==================================
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------
View Git Blame Copy Permalink