gerrit/Documentation/rest-api-access.txt
David Pursehouse 7f04237529 Merge branch 'stable-2.15'
* stable-2.15:
  ProjectTagsScreen: Base visibility on the create refs/tags/* permission
  Upgrade JGit to 4.9.4.201809090327-r
  Upgrade JGit to 4.7.3.201809090215-r
  Set version to 2.14.13-SNAPSHOT
  ProjectTagsScreen: Base visibility on the create refs/tags/* permission
  Set version to 2.15.4-SNAPSHOT
  Set version to 2.14.12
  [project.config] Allow to add commentLink entries
  ElasticVersionTest: Align tested versions w/ ElasticContainer last ones
  Assume correct relative or absolute URL from Weblink provider
  AbstractSubmit: Remove redundant assertion about null IOException
  ListMailFilter: Fix operator precedence warning raised by ErrorProne
  ListProjects: Fix operator precedence warning raised by ErrorProne
  ChangeBundle: Fix operator precedence warning raised by ErrorProne
  Bazel: fix error_prone_warnings_toolchain rule
  Elastic{Index|ReindexIT} Remove tests for 6.2 and 6.3
  ElasticVersionTest#version6: Add missing test for V6_4
  Allow more email RFC accepted chars in username
  Make inheritance of receive.maxObjectSizeLimit optional
  Allow to inherit receive.maxObjectSizeLimit from parent project
  RestApiServlet: Skip capability check for administrators
  CreateAccount: Simplify error message when username is invalid
  Bazel: Provide toolchain with activated error prone warnings
  Use ExternalId.isValidUsername instead of ExternalId.USER_NAME_PATTERN_REGEX
  Move regular expressions for user name from Account to ExternalId
  AccountIT: Add basic tests for creating user with {in}valid username
  Revert refactoring of Account.USER_NAME_PATTERN
  Fix code that caused changes to break in MS Edge
  Add support for Elasticsearch 6.4.0
  Upgrade elasticsearch-rest-client to 6.4.0
  ElasticVersion: Say 'Unsupported' rather than 'Invalid'
  ElasticQueryAdapter: Move isV6 method to ElasticVersion and simplify
  Account.java: introduce compiled pattern and use where applicable
  Optimize USER_NAME_PATTERN string and its usage
  ElasticContainer: Test against Elasticsearch version 5.6.11
  rest-api-accounts: Fix documentation of "Get Active" response
  GetCapabilities#CheckOne: Return json content type
  ConfigSuite: Instantiate class via getDeclaredConstructor()

Change-Id: I08136f1d27da08ce8a523f2dc062316723e17c45
2018-09-12 13:27:01 +09:00

426 lines
12 KiB
Plaintext

= 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,
"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
---------