This page describes the project related REST endpoints. Please also take note of the general information on the REST API.
Project Endpoints
List Projects
'GET /projects/'
Lists the projects accessible by the caller. This is the same as using the ls-projects command over SSH, and accepts the same options as query parameters.
As result a map is returned that maps the project names to ProjectInfo entries. The entries in the map are sorted by project name.
GET /projects/?d HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"external/bison": {
"id": "external%2Fbison",
"description": "GNU parser generator"
},
"external/gcc": {
"id": "external%2Fgcc"
},
"external/openssl": {
"id": "external%2Fopenssl",
"description": "encryption\ncrypto routines"
},
"test": {
"id": "test",
"description": "\u003chtml\u003e is escaped"
}
}
Project Options
- Branch(b)
-
Limit the results to the projects having the specified branch and include the sha1 of the branch in the results.
Get projects that have a 'master' branch:
RequestGET /projects/?b=master HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "some-project": { "id": "some-project", "branches": { "master": "c5ed9dfcbf002ca0e432d788dab6ca2387829ca7" } }, "some-other-project": { "id": "some-other-project", "branches": { "master": "ef1c270142f9581ecf768f4193fc8f8a81102ec2" } }, } - Description(d)
-
Include project description in the results.
Get all the projects with their description:
RequestGET /projects/?d HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "some-project": { "id": "some-project", "description": "Description of some project." }, "some-other-project": { "id": "some-other-project", "description": "Description of some other project." } }, } - Limit(n)
-
Limit the number of projects to be included in the results.
Query the first project in the project list:
RequestGET /projects/?n=1 HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "some-project": { "id": "some-project", _more_projects: true } }
If the number of projects matching the query exceeds either the
internal limit or a supplied limit query parameter, the last project
object has a _more_projects: true JSON field set.
- Prefix(p)
-
Limit the results to those projects that start with the specified prefix.
The match is case sensitive. May not be used together with
morr.List all projects that start with
platform/:RequestGET /projects/?p=platform%2F HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "platform/drivers": { "id": "platform%2Fdrivers" }, "platform/tools": { "id": "platform%2Ftools" } }E.g. this feature can be used by suggestion client UI’s to limit results.
- Regex(r)
-
Limit the results to those projects that match the specified regex.
Boundary matchers '^' and '$' are implicit. For example: the regex 'test.*' will match any projects that start with 'test' and regex '.*test' will match any project that end with 'test'.
The match is case sensitive. May not be used together with
morp.List all projects that match regex
test.*project:RequestGET /projects/?r=test.*project HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "test/some-project": { "id": "test%2Fsome-project" }, "test/some-other-project": { "id": "test%2Fsome-other-project" } } - Skip(S)
-
Skip the given number of projects from the beginning of the list.
Query the second project in the project list:
RequestGET /projects/?n=1&S=1 HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "some-other-project": { "id": "some-other-project" } } - Substring(m)
-
Limit the results to those projects that match the specified substring.
The match is case insensitive. May not be used together with
rorp.List all projects that match substring
test/:RequestGET /projects/?m=test%2F HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "test/some-project": { "id": "test%2Fsome-project" }, "some-path/test/some-other-project": { "id": "some-path%2Ftest%2Fsome-other-project" } } - Tree(t)
-
Get projects inheritance in a tree-like format. This option does not work together with the branch option.
|
Note
|
If the calling user does not meet any of the following criteria: |
-
The state of the parent project is either "ACTIVE" or "READ ONLY", and the calling user has READ permission to at least one ref.
-
The state of the parent project is "HIDDEN" and the calling user has READ permission for 'refs/meta/config'.
Then the 'parent' field will be labeled as '?-N', where N represents the nesting level within the project’s tree structure. In the provided example, 'All-Projects' corresponds to level 1, 'parent-project' to level 2, and 'child-project' to level 3.
Get all the projects with tree option:
+ .Request
GET /projects/?t HTTP/1.0
+ .Response
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"All-Projects" {
"id": "All-Projects"
},
"child-project": {
"id": "child-project",
"parent": "parent-project"
},
"parent-project": {
"id": "parent-project",
"parent": "All-Projects"
}
}
- Type(type)
-
Get projects with specified type: ALL, CODE, PERMISSIONS.
Get all the projects of type 'PERMISSIONS':
RequestGET /projects/?type=PERMISSIONS HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "All-Projects" { "id": "All-Projects" }, "some-parent-project": { "id": "some-parent-project" } } - All
-
Get all projects, including those whose state is "HIDDEN". May not be used together with the
stateoption.RequestGET /projects/?all HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "All-Projects" { "id": "All-Projects", "state": "ACTIVE" }, "some-other-project": { "id": "some-other-project", "state": "HIDDEN" } } - State(s)
-
Get all projects with the given state. May not be used together with the
alloption.RequestGET /projects/?state=HIDDEN HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "some-other-project": { "id": "some-other-project", "state": "HIDDEN" } }
Query Projects
'GET /projects/?query=<query>'
Queries projects visible to the caller. The
query string must be
provided by the query parameter. The start and limit parameters
can be used to skip/limit results.
As result a list of ProjectInfo entities is returned.
GET /projects/?query=name:test HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"id": "test",
"description": "\u003chtml\u003e is escaped"
}
]
Project Limit
The /projects/?query=<query> URL also accepts a limit integer in the
limit parameter. This limits the results to limit projects.
Query the first 25 projects in project list.
GET /projects/?query=<query>&limit=25 HTTP/1.0
If the number of projects matching the query exceeds either the
internal limit or a supplied limit query parameter, the last project
object has a _more_projects: true JSON field set.
The /projects/ URL also accepts a start integer in the start
parameter. The results will skip start projects from project list.
Query 25 projects starting from index 50.
GET /projects/?query=<query>&limit=25&start=50 HTTP/1.0
Project Options
Additional fields can be obtained by adding o parameters. Each option
requires more lookups and slows down the query response time to the
client so they are generally disabled by default. The supported fields
are described in the context of the List Projects
REST endpoint.
Get Project
'GET /projects/{project-name}'
Retrieves a project.
GET /projects/plugins%2Freplication HTTP/1.0
As response a ProjectInfo entity is returned that describes the project.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "plugins%2Freplication",
"name": "plugins/replication",
"parent": "Public-Plugins",
"description": "Copies to other servers using the Git protocol",
"state": "ACTIVE",
"labels": {
"Code-Review": {
"values": {
" 0": "No score",
"+1": "Approved"
},
"default_value": 0
}
}
}
Create Project
'PUT /projects/{project-name}'
Creates a new project.
In the request body additional data for the project can be provided as ProjectInput.
PUT /projects/MyProject HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"description": "This is a demo project.",
"submit_type": "INHERIT",
"owners": [
"MyProject-Owners"
]
}
As response the ProjectInfo entity is returned that describes the created project.
HTTP/1.1 201 Created
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "MyProject",
"name": "MyProject",
"parent": "All-Projects",
"description": "This is a demo project.",
"labels": {
"Code-Review": {
"values": {
" 0": "No score",
"+1": "Approved"
},
"default_value": 0
}
}
}
Get Project Description
'GET /projects/{project-name}/description'
Retrieves the description of a project.
GET /projects/plugins%2Freplication/description HTTP/1.0
HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' "Copies to other servers using the Git protocol"
If the project does not have a description an empty string is returned.
Set Project Description
'PUT /projects/{project-name}/description'
Sets the description of a project.
The new project description must be provided in the request body inside a ProjectDescriptionInput entity.
PUT /projects/plugins%2Freplication/description HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"description": "Plugin for Gerrit that handles the replication.",
"commit_message": "Update the project description"
}
As response the new project description is returned.
HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' "Plugin for Gerrit that handles the replication."
If the description was deleted the response is “204 No Content”.
Delete Project Description
'DELETE /projects/{project-name}/description'
Deletes the description of a project.
DELETE /projects/plugins%2Freplication/description HTTP/1.0
HTTP/1.1 204 No Content
A commit message can be provided in the request body as a ProjectDescriptionInput entity. Historically, this method allowed a body in the DELETE, but that behavior is deprecated. In this case, use PUT instead.
PUT /projects/plugins%2Freplication/description HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"commit_message": "Update the project description"
}
HTTP/1.1 204 No Content
Get Project Parent
'GET /projects/{project-name}/parent'
Retrieves the name of a project’s parent project. For the
All-Projects root project an empty string is returned.
GET /projects/plugins%2Freplication/parent HTTP/1.0
HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' "All-Projects"
Set Project Parent
'PUT /projects/{project-name}/parent'
Sets the parent project for a project.
The new name of the parent project must be provided in the request body inside a ProjectParentInput entity.
PUT /projects/plugins%2Freplication/parent HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"parent": "Public-Plugins",
"commit_message": "Update the project parent"
}
As response the new parent project name is returned.
HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' "Public-Plugins"
Get HEAD
'GET /projects/{project-name}/HEAD'
Retrieves for a project the name of the branch to which HEAD points.
GET /projects/plugins%2Freplication/HEAD HTTP/1.0
HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' "refs/heads/master"
Set HEAD
'PUT /projects/{project-name}/HEAD'
Sets HEAD for a project.
The new ref to which HEAD should point must be provided in the
request body inside a HeadInput entity.
PUT /projects/plugins%2Freplication/HEAD HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"ref": "refs/heads/stable"
}
As response the new ref to which HEAD points is returned.
HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' "refs/heads/stable"
Get Repository Statistics
'GET /projects/{project-name}/statistics.git'
Return statistics for the repository of a project.
GET /projects/plugins%2Freplication/statistics.git HTTP/1.0
The repository statistics are returned as a RepositoryStatisticsInfo entity.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"number_of_loose_objects": 127,
"number_of_loose_refs": 15,
"number_of_pack_files": 15,
"number_of_packed_objects": 67,
"number_of_packed_refs": 0,
"size_of_loose_objects": 29466,
"size_of_packed_objects": 9646
}
Get Config
'GET /projects/{project-name}/config'
Gets some configuration information about a project. Note that this
config info is not simply the contents of project.config; it generally
contains fields that may have been inherited from parent projects.
GET /projects/myproject/config
A ConfigInfo entity is returned that describes the
project configuration. Some fields are only visible to users that have
read access to refs/meta/config.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"description": "demo project",
"use_contributor_agreements": {
"value": true,
"configured_value": "TRUE",
"inherited_value": false
},
"use_content_merge": {
"value": true,
"configured_value": "INHERIT",
"inherited_value": true
},
"use_signed_off_by": {
"value": false,
"configured_value": "INHERIT",
"inherited_value": false
},
"create_new_change_for_all_not_in_target": {
"value": false,
"configured_value": "INHERIT",
"inherited_value": false
},
"require_change_id": {
"value": false,
"configured_value": "FALSE",
"inherited_value": true
},
"max_object_size_limit": {
"value": "15m",
"configured_value": "15m",
"inherited_value": "20m"
},
"submit_type": "INHERIT",
"default_submit_type": {
"value": "MERGE_IF_NECESSARY",
"configured_value": "INHERIT",
"inherited_value": "MERGE_IF_NECESSARY"
},
"state": "ACTIVE",
"commentlinks": {},
"plugin_config": {
"helloworld": {
"language": {
"display_name": "Preferred Language",
"type": "STRING",
"value": "en"
}
}
},
"actions": {
"cookbook~hello-project": {
"method": "POST",
"label": "Say hello",
"title": "Say hello in different languages",
"enabled": true
}
}
}
Set Config
'PUT /projects/{project-name}/config'
Sets the configuration of a project.
The new configuration must be provided in the request body as a ConfigInput entity.
PUT /projects/myproject/config HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"description": "demo project",
"use_contributor_agreements": "FALSE",
"use_content_merge": "INHERIT",
"use_signed_off_by": "INHERIT",
"create_new_change_for_all_not_in_target": "INHERIT",
"enable_signed_push": "INHERIT",
"require_signed_push": "INHERIT",
"reject_implicit_merges": "INHERIT",
"require_change_id": "TRUE",
"max_object_size_limit": "10m",
"submit_type": "REBASE_IF_NECESSARY",
"state": "ACTIVE"
}
As response the new configuration is returned as a ConfigInfo entity.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"use_contributor_agreements": {
"value": false,
"configured_value": "FALSE",
"inherited_value": false
},
"use_content_merge": {
"value": true,
"configured_value": "INHERIT",
"inherited_value": true
},
"use_signed_off_by": {
"value": false,
"configured_value": "INHERIT",
"inherited_value": false
},
"create_new_change_for_all_not_in_target": {
"value": true,
"configured_value": "INHERIT",
"inherited_value": false
},
"require_change_id": {
"value": true,
"configured_value": "TRUE",
"inherited_value": true
},
"enable_signed_push": {
"value": true,
"configured_value": "INHERIT",
"inherited_value": false
},
"require_signed_push": {
"value": false,
"configured_value": "INHERIT",
"inherited_value": false
},
"reject_implicit_merges": {
"value": false,
"configured_value": "INHERIT",
"inherited_value": false
},
"max_object_size_limit": {
"value": "10m",
"configured_value": "10m",
"inherited_value": "20m"
},
"submit_type": "REBASE_IF_NECESSARY",
"default_submit_type": {
"value": "REBASE_IF_NECESSARY",
"configured_value": "INHERIT",
"inherited_value": "REBASE_IF_NECESSARY"
},
"state": "ACTIVE",
"commentlinks": {}
}
Run GC
'POST /projects/{project-name}/gc'
Run the Git garbage collection for the repository of a project.
Options for the Git garbage collection can be specified in the request body as a GCInput entity.
POST /projects/plugins%2Freplication/gc HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"show_progress": true
}
The response is the streamed output of the garbage collection.
HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: text/plain; charset=UTF-8 collecting garbage for "plugins/replication": Pack refs: 100% (21/21) Counting objects: 20 Finding sources: 100% (20/20) Getting sizes: 100% (13/13) Compressing objects: 83% (5/6) Writing objects: 100% (20/20) Selecting commits: 100% (7/7) Building bitmaps: 100% (7/7) Finding sources: 100% (41/41) Getting sizes: 100% (25/25) Compressing objects: 52% (12/23) Writing objects: 100% (41/41) Prune loose objects also found in pack files: 100% (36/36) Prune loose, unreferenced objects: 100% (36/36) done.
Asynchronous Execution
The option async allows to schedule a background task that asynchronously
executes a Git garbage collection.
The Location header of the response refers to the background task
which allows to inspect the progress of its execution. In case of asynchronous
execution the show_progress option is ignored.
POST /projects/plugins%2Freplication/gc HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"async": true
}
The response is empty.
HTTP/1.1 202 Accepted Content-Disposition: attachment Location: https:<host>/a/config/server/tasks/383a0602
Ban Commit
'PUT /projects/{project-name}/ban'
Marks commits as banned for the project. If a commit is banned Gerrit rejects every push that includes this commit with contains banned commit ….
|
Note
|
This REST endpoint only marks the commits as banned, but it does not remove the commits from the history of any central branch. This needs to be done manually. |
The commits to be banned must be specified in the request body as a BanInput entity.
The caller must be project owner.
PUT /projects/plugins%2Freplication/ban HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"commits": [
"a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96",
"cf5b56541f84b8b57e16810b18daca9c3adc377b"
],
"reason": "Violates IP"
}
As response a BanResultInfo entity is returned.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"newly_banned": [
"a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96",
"cf5b56541f84b8b57e16810b18daca9c3adc377b"
]
}
List Access Rights for Project
'GET /projects/{project-name}/access'
Lists the access rights for a single project.
As result a ProjectAccessInfo entity is returned.
GET /projects/MyProject/access HTTP/1.0
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
{
"revision": "61157ed63e14d261b6dca40650472a9b0bd88474",
"inherits_from": {
"id": "All-Projects",
"name": "All-Projects",
"description": "Access inherited by all other projects."
},
"local": {
"refs/*": {
"permissions": {
"read": {
"rules": {
"c2ce4749a32ceb82cd6adcce65b8216e12afb41c": {
"action": "ALLOW",
"force": false
},
"global:Anonymous-Users": {
"action": "ALLOW",
"force": false
}
}
}
}
}
},
"is_owner": true,
"owner_of": [
"refs/*"
],
"can_upload": true,
"can_add": true,
"can_add_tags": true,
"config_visible": true,
"groups": {
"c2ce4749a32ceb82cd6adcce65b8216e12afb41c": {
"url": "#/admin/groups/uuid-c2ce4749a32ceb82cd6adcce65b8216e12afb41c",
"options": {},
"description": "Users who perform batch actions on Gerrit",
"group_id": 2,
"owner": "Administrators",
"owner_id": "d5b7124af4de52924ed397913e2c3b37bf186948",
"created_on": "2009-06-08 23:31:00.000000000",
"name": "Service Users"
},
"global:Anonymous-Users": {
"options": {},
"name": "Anonymous Users"
}
}
}
Add, Update and Delete Access Rights for Project
'POST /projects/{project-name}/access'
Sets access rights for the project using the diff schema provided by ProjectAccessInput. Deductions are used to remove access sections, permissions or permission rules. The backend will remove the entity with the finest granularity in the request, meaning that if an access section without permissions is posted, the access section will be removed; if an access section with a permission but no permission rules is posted, the permission will be removed; if an access section with a permission and a permission rule is posted, the permission rule will be removed.
Additionally, access sections and permissions will be cleaned up after applying the deductions by removing items that have no child elements.
After removals have been applied, additions will be applied.
As result a ProjectAccessInfo entity is returned.
POST /projects/MyProject/access HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"remove": {
"refs/*": {
"permissions": {
"read": {
"rules": {
"c2ce4749a32ceb82cd6adcce65b8216e12afb41c": {
"action": "ALLOW"
}
}
}
}
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
{
"revision": "61157ed63e14d261b6dca40650472a9b0bd88474",
"inherits_from": {
"id": "All-Projects",
"name": "All-Projects",
"description": "Access inherited by all other projects."
},
"local": {
"refs/*": {
"permissions": {
"read": {
"rules": {
"global:Anonymous-Users": {
"action": "ALLOW",
"force": false
}
}
}
}
}
},
"is_owner": true,
"owner_of": [
"refs/*"
],
"can_upload": true,
"can_add": true,
"can_add_tags": true,
"config_visible": true,
"groups": {
"global:Anonymous-Users": {
"options": {},
"name": "Anonymous Users"
}
}
}
Create Change for review.
This endpoint is functionally equivalent to create change in the change API, but it has the project name in the URL, which is easier to route in sharded deployments.
POST /projects/myProject/create.change HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"subject" : "Let's support 100% Gerrit workflow direct in browser",
"branch" : "master",
"topic" : "create-change-in-browser",
"status" : "NEW"
}
As response a ChangeInfo entity is returned that describes the resulting change.
HTTP/1.1 201 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941",
"project": "myProject",
"branch": "master",
"topic": "create-change-in-browser",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941",
"subject": "Let's support 100% Gerrit workflow direct in browser",
"status": "NEW",
"created": "2014-05-05 07:15:44.639000000",
"updated": "2014-05-05 07:15:44.639000000",
"mergeable": true,
"insertions": 0,
"deletions": 0,
"_number": 4711,
"owner": {
"name": "John Doe"
}
}
Create Access Rights Change for review.
'PUT /projects/{project-name}/access:review
Sets access rights for the project using the diff schema provided by ProjectAccessInput
This takes the same input as Update Access Rights, but creates a pending change for review. Like Create Change, it returns a ChangeInfo entity describing the resulting change.
PUT /projects/MyProject/access:review HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"add": {
"refs/heads/*": {
"permissions": {
"read": {
"rules": {
"global:Anonymous-Users": {
"action": "DENY",
"force": false
}
}
}
}
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "testproj~refs%2Fmeta%2Fconfig~Ieaf185bf90a1fc3b58461e399385e158a20b31a2",
"project": "testproj",
"branch": "refs/meta/config",
"hashtags": [],
"change_id": "Ieaf185bf90a1fc3b58461e399385e158a20b31a2",
"subject": "Review access change",
"status": "NEW",
"created": "2017-09-07 14:31:11.852000000",
"updated": "2017-09-07 14:31:11.852000000",
"submit_type": "CHERRY_PICK",
"mergeable": true,
"insertions": 2,
"deletions": 0,
"unresolved_comment_count": 0,
"has_review_started": true,
"_number": 7,
"owner": {
"_account_id": 1000000
}
}
Check Access
'GET /projects/MyProject/check.access?account=1000098&ref=refs%2Fheads%2Fsecret%2Fbla'
This command runs access checks for other users. This requires the View Access global capability.
The result is a AccessCheckInfo entity detailing the access of the given user for the given project, project-ref, or project-permission-ref combination.
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
{
"message": "user Kristen Burns \u003cKristen.Burns@gerritcodereview.com\u003e (1000098) cannot see ref refs/heads/secret/bla in project MyProject",
"status": 403
}
Check Access Options
- Account(account)
-
The account for which to check access. Mandatory.
- Permission(perm)
-
The ref permission for which to check access. If not specified, read access to at least branch is checked.
- Ref(ref)
-
The branch for which to check access. This must be given if
permis specified.
Index project
Adds or updates the current project (and children, if specified) in the secondary index.
The indexing task is executed asynchronously in background and this command returns
immediately if async is specified in the input.
As an input, a IndexProjectInput entity can be provided.
POST /projects/MyProject/index HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"index_children": "true"
"async": "true"
}
HTTP/1.1 202 Accepted Content-Disposition: attachment
Index all changes in a project
Adds or updates all the changes belonging to a project in the secondary index. The indexing task is executed asynchronously in background, so this command returns immediately.
POST /projects/MyProject/index.changes HTTP/1.0
HTTP/1.1 202 Accepted Content-Disposition: attachment
Check project consistency
Performs consistency checks on the project.
Which consistency checks should be performed is controlled by the CheckProjectInput entity in the request body.
The following consistency checks are supported:
-
AutoCloseableChangesCheck: Searches for open changes that can be auto-closed because a patch set of the change is already contained in the destination branch or because the destination branch contains a commit with the same Change-Id. Normally Gerrit auto-closes such changes when the corresponding commits are pushed directly to the repository. However if a branch is updated behind Gerrit’s back or if auto-closing changes fails (and the push is still successful) change states can get inconsistent (changes that are already part of the destination branch are still open). This consistency check is intended to detect and repair this situation.
To fix any problems that can be fixed automatically set the fix field
in the inputs for the consistency checks to true.
This REST endpoint requires the Administrate Server global capability.
POST /projects/MyProject/check HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"auto_closeable_changes_check": {
"fix": true,
"branch": "refs/heads/master",
"max_commits": 100
}
}
As response a CheckProjectResultInfo entity is returned that results for the consistency checks.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"auto_closeable_changes_check_result": {
"auto_closeable_changes": {
"refs/heads/master": [
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
"subject": "Implementing Feature X",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"insertions": 34,
"deletions": 101,
"_number": 3965,
"owner": {
"name": "John Doe"
},
"problems": [
{
"message": "Patch set 1 (2f15e416237ed9b561199f24184f5f5d2708c584) is merged into destination ref refs/heads/master (2f15e416237ed9b561199f24184f5f5d2708c584), but change status is NEW",
"status": "FIXED",
"outcome": "Marked change as merged"
}
]
}
]
}
}
}
Get Commits Included In Refs
'GET /projects/{project-name}/commits:in'
Gets refs in which the specified commits were merged into. Returns a map of commits to sets of full ref names.
One or more commit query parameters are required and each specifies a
commit-id (SHA-1 in 40 digit hex representation). Commits will not be contained
in the map if they do not exist or are not reachable from visible, specified refs.
One or more ref query parameters are required and each specifies a full ref name.
Refs which are not visible to the calling user according to the project’s read
permissions and refs which do not exist will be filtered out from the result.
GET /projects/work%2Fmy-project/commits:in?commit=a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96&commit=6d2a3adb10e844c33617fc948dbeb88e868d396e&ref=refs/heads/master&ref=refs/heads/branch1 HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96": [
"refs/heads/master"
],
"6d2a3adb10e844c33617fc948dbeb88e868d396e": [
"refs/heads/branch1",
"refs/heads/master"
]
}
Branch Endpoints
List Branches
'GET /projects/{project-name}/branches/'
List the branches of a project.
As result a list of BranchInfo entries is returned.
If the limit parameter was set and the number of branches is larger than the
limit, the response header X-GERRIT-NEXT-PAGE-TOKEN will be set. Clients
can pass this token with subsequent requests (using the next-page-token
request parameter) for pagination to skip over previous results.
GET /projects/work%2Fmy-project/branches/ HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"ref": "HEAD",
"revision": "master"
},
{
"ref": "refs/meta/config",
"revision": "76016386a0d8ecc7b6be212424978bb45959d668"
},
{
"ref": "refs/heads/master",
"revision": "67ebf73496383c6777035e374d2d664009e2aa5c"
},
{
"ref": "refs/heads/stable",
"revision": "64ca533bd0eb5252d2fee83f63da67caae9b4674",
"can_delete": true
}
]
Branch Options
- Limit(n)
-
Limit the number of branches to be included in the results.
RequestGET /projects/testproject/branches?n=1 HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "ref": "HEAD", "revision": "master", } ] - Skip(S)
-
Skip the given number of branches from the beginning of the list.
RequestGET /projects/testproject/branches?n=1&s=0 HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "ref": "HEAD", "revision": "master", } ] - Substring(m)
-
Limit the results to those branches that match the specified substring.
The match is case insensitive. May not be used together with
r.List all branches that match substring
test:RequestGET /projects/testproject/branches?m=test HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "ref": "refs/heads/test1", "revision": "9c9d08a438e55e52f33b608415e6dddd9b18550d", "can_delete": true } ] - Regex(r)
-
Limit the results to those branches that match the specified regex. Boundary matchers '^' and '$' are implicit. For example: the regex 't*' will match any branches that start with 't' and regex '*t' will match any branches that end with 't'.
The match is case sensitive. May not be used together with
m.List all branches that match regex
t.*1:RequestGET /projects/testproject/branches?r=t.*1 HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "ref": "refs/heads/test1", "revision": "9c9d08a438e55e52f33b608415e6dddd9b18550d", "can_delete": true } ] - Next-page-token(t)
-
Skips over previous results. Cannot be set simultaneously with the
Skipparameter, and also must be set to an exact token received by the server in a previous call, otherwise the request would fail with400 Bad Request.
Get Branch
'GET /projects/{project-name}/branches/{branch-id}'
Retrieves a branch of a project. For the "All-Users" repository, the magic branch "refs/users/self" is automatically resolved to the user branch of the calling user.
GET /projects/work%2Fmy-project/branches/master HTTP/1.0
As response a BranchInfo entity is returned that describes the branch.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"ref": "refs/heads/master",
"revision": "67ebf73496383c6777035e374d2d664009e2aa5c"
}
Create Branch
'PUT /projects/{project-name}/branches/{branch-id}'
Creates a new branch.
In the request body additional data for the branch can be provided as
BranchInput. The {branch-id} in the URL
should exactly match with the ref field of BranchInput, or
otherwise the request would fail with 400 Bad Request.
PUT /projects/MyProject/branches/stable HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"revision": "76016386a0d8ecc7b6be212424978bb45959d668"
}
As response a BranchInfo entity is returned that describes the created branch.
HTTP/1.1 201 Created
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"ref": "refs/heads/stable",
"revision": "76016386a0d8ecc7b6be212424978bb45959d668",
"can_delete": true
}
Delete Branch
'DELETE /projects/{project-name}/branches/{branch-id}'
Deletes a branch.
DELETE /projects/MyProject/branches/stable HTTP/1.0
HTTP/1.1 204 No Content
Delete Branches
'POST /projects/{project-name}/branches:delete'
Delete one or more branches.
The branches to be deleted must be provided in the request body as a DeleteBranchesInput entity.
POST /projects/MyProject/branches:delete HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"branches": [
"stable-1.0",
"stable-2.0"
]
}
HTTP/1.1 204 No Content
If some branches could not be deleted, the response is “409 Conflict” and the error message is contained in the response body.
Get Content
'GET /projects/{project-name}/branches/{branch-id}/files/{file-id}/content'
Gets the content of a file from the HEAD revision of a certain branch.
GET /projects/gerrit/branches/master/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/content HTTP/1.0
The content is returned as base64 encoded string.
HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: text/plain; charset=UTF-8 Ly8gQ29weXJpZ2h0IChDKSAyMDEwIFRoZSBBbmRyb2lkIE9wZW4gU291cmNlIFByb2plY...
Suggest Reviewers
'GET /projects/{project-name}/branches/{branch-id}/suggest_reviewers?q=J&n=5'
Suggest the reviewers for a given query q and result limit n. If result
limit is not passed, then the default 10 is used.
This REST endpoint only suggests accounts that
-
are active
-
can see the branch
-
are visible to the calling user
-
are not service users (unless skipServiceUsers is set to
false)
Groups can be excluded from the results by specifying the 'exclude-groups' request parameter:
'GET /changes/{project-name}/branches/{branch-id}/suggest_reviewers?q=J&n=5&exclude-groups'
As result a list of SuggestedReviewerInfo entries is returned.
GET /projects/myProject/branches/myBranch/suggest_reviewers?q=J HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"account": {
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
},
"count": 1
},
{
"group": {
"id": "4fd581c0657268f2bdcc26699fbf9ddb76e3a279",
"name": "Joiner"
},
"count": 5
}
]
To suggest CCs reviewer-state=CC can be specified as additional URL
parameter.
'GET /changes/{project-name}/branches/{branch-id}/suggest_reviewers?q=J&reviewer-state=CC'
Get Mergeable Information
'GET /projects/{project-name}/branches/{branch-id}/mergeable'
Gets whether the source is mergeable with the target branch.
The source query parameter is required, which can be anything that
could be resolved to a commit, and is visible to the caller. See
examples of the source attribute in
MergeInput.
Also takes an optional parameter strategy, which can be recursive, resolve,
simple-two-way-in-core, ours or theirs, default will use project settings.
GET /projects/test/branches/master/mergeable?source=testbranch&strategy=recursive HTTP/1.0
As response a MergeableInfo entity is returned.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"submit_type": "MERGE_IF_NECESSARY",
"strategy": "recursive",
"mergeable": true,
"commit_merged": false,
"content_merged": false
}
or when there were conflicts.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"submit_type": "MERGE_IF_NECESSARY",
"strategy": "recursive",
"mergeable": false,
"conflicts": [
"common.txt",
"shared.txt"
]
}
or when the 'testbranch' has been already merged.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"submit_type": "MERGE_IF_NECESSARY",
"strategy": "recursive",
"mergeable": true,
"commit_merged": true,
"content_merged": true
}
or when only the content of 'testbranch' has been merged.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"submit_type": "MERGE_IF_NECESSARY",
"strategy": "recursive",
"mergeable": true,
"commit_merged": false,
"content_merged": true
}
Get Reflog
'GET /projects/{project-name}/branches/{branch-id}/reflog'
Gets the reflog of a certain branch.
The caller must be project owner.
GET /projects/gerrit/branches/master/reflog HTTP/1.0
As response a list of ReflogEntryInfo entities is returned that describe the reflog entries. The reflog entries are returned in reverse order.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"old_id": "976ced8f4fc0909d7e1584d18455299545881d60",
"new_id": "2eaa94bac536654eb592c941e33b91f925698d16",
"who": {
"name": "Jane Roe",
"email": "jane.roe@example.com",
"date": "2014-06-30 11:53:43.000000000",
"tz": 120
},
"comment": "merged: fast forward"
},
{
"old_id": "c271c6a7161b74f85560c5899c8c73ee89ca5e29",
"new_id": "976ced8f4fc0909d7e1584d18455299545881d60",
"who": {
"name": "John Doe",
"email": "john.doe@example.com",
"date": "2013-10-02 10:45:26.000000000",
"tz": 120
},
"comment": "merged: fast forward"
},
{
"old_id": "0000000000000000000000000000000000000000",
"new_id": "c271c6a7161b74f85560c5899c8c73ee89ca5e29",
"who": {
"name": "John Doe",
"email": "john.doe@example.com",
"date": "2013-09-30 19:08:44.000000000",
"tz": 120
},
"comment": ""
}
]
The get reflog endpoint also accepts a limit integer in the n
parameter. This limits the results to show the last n reflog entries.
Query the last 25 reflog entries.
GET /projects/gerrit/branches/master/reflog?n=25 HTTP/1.0
The reflog can also be filtered by timestamp by specifying the from
and to parameters. The timestamp for from and to must be given as
UTC in the following format: yyyyMMdd_HHmm.
GET /projects/gerrit/branches/master/reflog?from=20130101_0000&to=20140101_0000=25 HTTP/1.0
Child Project Endpoints
List Child Projects
'GET /projects/{project-name}/children/'
List the direct child projects of a project.
GET /projects/Public-Plugins/children/ HTTP/1.0
As result a list of ProjectInfo entries is returned that describe the child projects.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"id": "plugins%2Freplication",
"name": "plugins/replication",
"parent": "Public-Plugins",
"description": "Copies to other servers using the Git protocol"
},
{
"id": "plugins%2Freviewnotes",
"name": "plugins/reviewnotes",
"parent": "Public-Plugins",
"description": "Annotates merged commits using notes on refs/notes/review."
},
{
"id": "plugins%2Fsingleusergroup",
"name": "plugins/singleusergroup",
"parent": "Public-Plugins",
"description": "GroupBackend enabling users to be directly added to access rules"
}
]
To resolve the child projects of a project recursively the parameter
recursive can be set.
Child projects that are not visible to the calling user are ignored and are not resolved further.
GET /projects/Public-Projects/children/?recursive HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"id": "gerrit",
"name": "gerrit",
"parent": "Public-Projects",
"description": "Gerrit Code Review"
},
{
"id": "plugins%2Freplication",
"name": "plugins/replication",
"parent": "Public-Plugins",
"description": "Copies to other servers using the Git protocol"
},
{
"id": "plugins%2Freviewnotes",
"name": "plugins/reviewnotes",
"parent": "Public-Plugins",
"description": "Annotates merged commits using notes on refs/notes/review."
},
{
"id": "plugins%2Fsingleusergroup",
"name": "plugins/singleusergroup",
"parent": "Public-Plugins",
"description": "GroupBackend enabling users to be directly added to access rules"
},
{
"id": "Public-Plugins",
"name": "Public-Plugins",
"parent": "Public-Projects",
"description": "Parent project for plugins/*"
}
]
Get Child Project
'GET /projects/{project-name}/children/{project-name}'
Retrieves a child project. If a non-direct child project should be
retrieved the parameter recursive must be set.
GET /projects/Public-Plugins/children/plugins%2Freplication HTTP/1.0
As response a ProjectInfo entity is returned that describes the child project.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "plugins%2Freplication",
"name": "plugins/replication",
"parent": "Public-Plugins",
"description": "Copies to other servers using the Git protocol"
}
Tag Endpoints
Create Tag
'PUT /projects/{project-name}/tags/{tag-id}'
Create a new tag on the project.
In the request body additional data for the tag can be provided as TagInput.
If a message is provided in the input, the tag is created as an annotated tag with the current user as tagger. Signed tags are not supported.
PUT /projects/MyProject/tags/v1.0 HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"message": "annotation",
"revision": "c83117624b5b5d8a7f86093824e2f9c1ed309d63"
}
As response a TagInfo entity is returned that describes the created tag.
HTTP/1.1 201 Created
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
"object": "d48d304adc4b6674e11dc2c018ea05fcbdda32fd",
"message": "annotation",
"tagger": {
"name": "David Pursehouse",
"email": "dpursehouse@collab.net",
"date": "2016-06-06 01:22:03.000000000",
"tz": 540
},
"ref": "refs/tags/v1.0",
"revision": "c83117624b5b5d8a7f86093824e2f9c1ed309d63"
}
List Tags
'GET /projects/{project-name}/tags/'
List the tags of a project.
As result a list of TagInfo entries is returned.
Only includes tags under the refs/tags/ namespace.
GET /projects/work%2Fmy-project/tags/ HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"ref": "refs/tags/v1.0",
"revision": "49ce77fdcfd3398dc0dedbe016d1a425fd52d666",
"object": "1624f5af8ae89148d1a3730df8c290413e3dcf30",
"message": "Annotated tag",
"tagger": {
"name": "David Pursehouse",
"email": "david.pursehouse@sonymobile.com",
"date": "2014-10-06 07:35:03.000000000",
"tz": 540
}
},
{
"ref": "refs/tags/v2.0",
"revision": "1624f5af8ae89148d1a3730df8c290413e3dcf30"
},
{
"ref": "refs/tags/v3.0",
"revision": "c628685b3c5a3614571ecb5c8fceb85db9112313",
"object": "1624f5af8ae89148d1a3730df8c290413e3dcf30",
"message": "Signed tag\n-----BEGIN PGP SIGNATURE-----\nVersion: GnuPG v1.4.11 (GNU/Linux)\n\niQEcBAABAgAGBQJUMlqYAAoJEPI2qVPgglptp7MH/j+KFcittFbxfSnZjUl8n5IZ\nveZo7wE+syjD9sUbMH4EGv0WYeVjphNTyViBof+stGTNkB0VQzLWI8+uWmOeiJ4a\nzj0LsbDOxodOEMI5tifo02L7r4Lzj++EbqtKv8IUq2kzYoQ2xjhKfFiGjeYOn008\n9PGnhNblEHZgCHguGR6GsfN8bfA2XNl9B5Ysl5ybX1kAVs/TuLZR4oDMZ/pW2S75\nhuyNnSgcgq7vl2gLGefuPs9lxkg5Fj3GZr7XPZk4pt/x1oiH7yXxV4UzrUwg2CC1\nfHrBlNbQ4uJNY8TFcwof52Z0cagM5Qb/ZSLglHbqEDGA68HPqbwf5z2hQyU2/U4\u003d\n\u003dZtUX\n-----END PGP SIGNATURE-----",
"tagger": {
"name": "David Pursehouse",
"email": "david.pursehouse@sonymobile.com",
"date": "2014-10-06 09:02:16.000000000",
"tz": 540
}
}
]
Tag Options
- Limit(n)
-
Limit the number of tags to be included in the results.
RequestGET /projects/work%2Fmy-project/tags?n=2 HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "ref": "refs/tags/v1.0", "revision": "49ce77fdcfd3398dc0dedbe016d1a425fd52d666", "object": "1624f5af8ae89148d1a3730df8c290413e3dcf30", "message": "Annotated tag", "tagger": { "name": "David Pursehouse", "email": "david.pursehouse@sonymobile.com", "date": "2014-10-06 07:35:03.000000000", "tz": 540 } }, { "ref": "refs/tags/v2.0", "revision": "1624f5af8ae89148d1a3730df8c290413e3dcf30" } ] - Skip(S)
-
Skip the given number of tags from the beginning of the list.
RequestGET /projects/work%2Fmy-project/tags?n=2&s=1 HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "ref": "refs/tags/v2.0", "revision": "1624f5af8ae89148d1a3730df8c290413e3dcf30" }, { "ref": "refs/tags/v3.0", "revision": "c628685b3c5a3614571ecb5c8fceb85db9112313", "object": "1624f5af8ae89148d1a3730df8c290413e3dcf30", "message": "Signed tag\n-----BEGIN PGP SIGNATURE-----\nVersion: GnuPG v1.4.11 (GNU/Linux)\n\niQEcBAABAgAGBQJUMlqYAAoJEPI2qVPgglptp7MH/j+KFcittFbxfSnZjUl8n5IZ\nveZo7wE+syjD9sUbMH4EGv0WYeVjphNTyViBof+stGTNkB0VQzLWI8+uWmOeiJ4a\nzj0LsbDOxodOEMI5tifo02L7r4Lzj++EbqtKv8IUq2kzYoQ2xjhKfFiGjeYOn008\n9PGnhNblEHZgCHguGR6GsfN8bfA2XNl9B5Ysl5ybX1kAVs/TuLZR4oDMZ/pW2S75\nhuyNnSgcgq7vl2gLGefuPs9lxkg5Fj3GZr7XPZk4pt/x1oiH7yXxV4UzrUwg2CC1\nfHrBlNbQ4uJNY8TFcwof52Z0cagM5Qb/ZSLglHbqEDGA68HPqbwf5z2hQyU2/U4\u003d\n\u003dZtUX\n-----END PGP SIGNATURE-----", "tagger": { "name": "David Pursehouse", "email": "david.pursehouse@sonymobile.com", "date": "2014-10-06 09:02:16.000000000", "tz": 540 } } ] - Substring(m)
-
Limit the results to those tags that match the specified substring.
The match is case insensitive. May not be used together with
r.List all tags that match substring
v2:RequestGET /projects/testproject/tags?m=v2 HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "ref": "refs/tags/v2.0", "revision": "1624f5af8ae89148d1a3730df8c290413e3dcf30" }, ] - Regex(r)
-
Limit the results to those tags that match the specified regex. Boundary matchers '^' and '$' are implicit. For example: the regex 't*' will match any tags that start with 't' and regex '*t' will match any tags that end with 't'.
The match is case sensitive. May not be used together with
m.List all tags that match regex
v.*0:RequestGET /projects/testproject/tags?r=v.*0 HTTP/1.0
ResponseHTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "ref": "refs/tags/v1.0", "revision": "49ce77fdcfd3398dc0dedbe016d1a425fd52d666", "object": "1624f5af8ae89148d1a3730df8c290413e3dcf30", "message": "Annotated tag", "tagger": { "name": "David Pursehouse", "email": "david.pursehouse@sonymobile.com", "date": "2014-10-06 07:35:03.000000000", "tz": 540 } }, { "ref": "refs/tags/v2.0", "revision": "1624f5af8ae89148d1a3730df8c290413e3dcf30" }, { "ref": "refs/tags/v3.0", "revision": "c628685b3c5a3614571ecb5c8fceb85db9112313", "object": "1624f5af8ae89148d1a3730df8c290413e3dcf30", "message": "Signed tag\n-----BEGIN PGP SIGNATURE-----\nVersion: GnuPG v1.4.11 (GNU/Linux)\n\niQEcBAABAgAGBQJUMlqYAAoJEPI2qVPgglptp7MH/j+KFcittFbxfSnZjUl8n5IZ\nveZo7wE+syjD9sUbMH4EGv0WYeVjphNTyViBof+stGTNkB0VQzLWI8+uWmOeiJ4a\nzj0LsbDOxodOEMI5tifo02L7r4Lzj++EbqtKv8IUq2kzYoQ2xjhKfFiGjeYOn008\n9PGnhNblEHZgCHguGR6GsfN8bfA2XNl9B5Ysl5ybX1kAVs/TuLZR4oDMZ/pW2S75\nhuyNnSgcgq7vl2gLGefuPs9lxkg5Fj3GZr7XPZk4pt/x1oiH7yXxV4UzrUwg2CC1\nfHrBlNbQ4uJNY8TFcwof52Z0cagM5Qb/ZSLglHbqEDGA68HPqbwf5z2hQyU2/U4\u003d\n\u003dZtUX\n-----END PGP SIGNATURE-----", "tagger": { "name": "David Pursehouse", "email": "david.pursehouse@sonymobile.com", "date": "2014-10-06 09:02:16.000000000", "tz": 540 } } ]
Get Tag
'GET /projects/{project-name}/tags/{tag-id}'
Retrieves a tag of a project.
GET /projects/work%2Fmy-project/tags/v1.0 HTTP/1.0
As response a TagInfo entity is returned that describes the tag.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"ref": "refs/tags/v1.0",
"revision": "49ce77fdcfd3398dc0dedbe016d1a425fd52d666",
"object": "1624f5af8ae89148d1a3730df8c290413e3dcf30",
"message": "Annotated tag",
"tagger": {
"name": "David Pursehouse",
"email": "david.pursehouse@sonymobile.com",
"date": "2014-10-06 07:35:03.000000000",
"tz": 540
}
}
Delete Tag
'DELETE /projects/{project-name}/tags/{tag-id}'
Deletes a tag.
DELETE /projects/MyProject/tags/v1.0 HTTP/1.0
HTTP/1.1 204 No Content
Delete Tags
'POST /projects/{project-name}/tags:delete'
Delete one or more tags.
The tags to be deleted must be provided in the request body as a DeleteTagsInput entity.
POST /projects/MyProject/tags:delete HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"tags": [
"v1.0",
"v2.0"
]
}
HTTP/1.1 204 No Content
If some tags could not be deleted, the response is “409 Conflict” and the error message is contained in the response body.
Commit Endpoints
Get Commit
'GET /projects/{project-name}/commits/{commit-id}'
Retrieves a commit of a project.
The commit must be visible to the caller.
GET /projects/work%2Fmy-project/commits/a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96 HTTP/1.0
As response a CommitInfo entity is returned that describes the commit.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"commit": "184ebe53805e102605d11f6b143486d15c23a09c",
"parents": [
{
"commit": "1eee2c9d8f352483781e772f35dc586a69ff5646",
"subject": "Migrate contributor agreements to All-Projects."
}
],
"author": {
"name": "Shawn O. Pearce",
"email": "sop@google.com",
"date": "2012-04-24 18:08:08.000000000",
"tz": -420
},
"committer": {
"name": "Shawn O. Pearce",
"email": "sop@google.com",
"date": "2012-04-24 18:08:08.000000000",
"tz": -420
},
"subject": "Use an EventBus to manage star icons",
"message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..."
}
Get Included In
'GET /projects/{project-name}/commits/{commit-id}/in'
Retrieves the branches and tags in which a change is included. As result an IncludedInInfo entity is returned.
Branches that are not visible to the calling user according to the project’s read permissions are filtered out from the result.
GET /projects/work%2Fmy-project/commits/a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96/in HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"branches": [
"master"
],
"tags": []
}
Get Content
'GET /projects/{project-name}/commits/{commit-id}/files/{file-id}/content'
Gets the content of a file from a certain commit.
GET /projects/work%2Fmy-project/commits/a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/content HTTP/1.0
The content is returned as base64 encoded string.
HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: text/plain; charset=UTF-8 Ly8gQ29weXJpZ2h0IChDKSAyMDEwIFRoZSBBbmRyb2lkIE9wZW4gU291cmNlIFByb2plY...
Cherry Pick Commit
'POST /projects/{project-name}/commits/{commit-id}/cherrypick'
Cherry-picks a commit of a project to a destination branch.
If one of the secondary emails associated with the user performing the operation was used as the committer email in the original commit, the same email will be used as the committer email in the new patch set; otherwise, the user’s preferred email will be used.
To cherry pick a change revision, see CherryPick.
The destination branch must be provided in the request body inside a CherryPickInput entity. If the commit message is not set, the commit message of the source commit will be used.
When cherry-picking a commit into a branch that already contains the Change-Id that we want to cherry-pick, the cherry-pick will create a new patch-set on the destination’s branch’s appropriate Change-Id. If the change is closed on the destination branch, the cherry-pick will fail.
POST /projects/work%2Fmy-project/commits/a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96/cherrypick HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"message" : "Implementing Feature X",
"destination" : "release-branch"
}
As response a ChangeInfo entity is returned that describes the resulting cherry-picked change.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941",
"project": "myProject",
"branch": "release-branch",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941",
"subject": "Implementing Feature X",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": true,
"insertions": 12,
"deletions": 11,
"_number": 3965,
"owner": {
"name": "John Doe"
}
}
List Files
'GET /projects/{project-name}/commits/{commit-id}/files/'
Lists the files that were modified, added or deleted in a commit.
GET /projects/work%2Fmy-project/commits/a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96/files/ HTTP/1.0
As result a map is returned that maps the file path to a FileInfo entry. The entries in the map are sorted by file path.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"/COMMIT_MSG": {
"status": "A",
"lines_inserted": 7,
"size_delta": 551,
"size": 551
},
"gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": {
"lines_inserted": 5,
"lines_deleted": 3,
"size_delta": 98,
"size": 23348
}
}
The integer-valued request parameter parent changes the response to return a
list of the files which are different in this commit compared to the given
parent commit. This is useful for supporting review of merge commits. The value
is the 1-based index of the parent’s position in the commit object. If the
value 0 is used for parent, the default base commit will be used, which is
the only parent for commits having one parent or the auto-merge commit
otherwise.
Dashboard Endpoints
List Dashboards
'GET /projects/{project-name}/dashboards/'
List custom dashboards for a project.
As result a list of DashboardInfo entries is returned.
List all dashboards for the work/my-project project:
GET /projects/work%2Fmy-project/dashboards/ HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"id": "main:closed",
"ref": "main",
"path": "closed",
"description": "Merged and abandoned changes in last 7 weeks",
"url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
"is_default": true,
"title": "Closed changes",
"sections": [
{
"name": "Merged",
"query": "status:merged age:7w"
},
{
"name": "Abandoned",
"query": "status:abandoned age:7w"
}
]
}
]
Get Dashboard
'GET /projects/{project-name}/dashboards/{dashboard-id}'
Retrieves a project dashboard. The dashboard can be defined on that project or be inherited from a parent project.
GET /projects/work%2Fmy-project/dashboards/main:closed HTTP/1.0
As response a DashboardInfo entity is returned that describes the dashboard.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "main:closed",
"ref": "main",
"path": "closed",
"description": "Merged and abandoned changes in last 7 weeks",
"url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
"is_default": true,
"title": "Closed changes",
"sections": [
{
"name": "Merged",
"query": "status:merged age:7w"
},
{
"name": "Abandoned",
"query": "status:abandoned age:7w"
}
]
}
To retrieve the default dashboard of a project use default as
dashboard-id.
GET /projects/work%2Fmy-project/dashboards/default HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "main:closed",
"ref": "main",
"path": "closed",
"description": "Merged and abandoned changes in last 7 weeks",
"url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
"is_default": true,
"title": "Closed changes",
"sections": [
{
"name": "Merged",
"query": "status:merged age:7w"
},
{
"name": "Abandoned",
"query": "status:abandoned age:7w"
}
]
}
Create Dashboard
'PUT /projects/{project-name}/dashboards/{dashboard-id}'
Creates a project dashboard, if a project dashboard with the given dashboard ID doesn’t exist yet.
Currently only supported for the default dashboard.
The creation information for the dashboard must be provided in the request body as a DashboardInput entity.
PUT /projects/work%2Fmy-project/dashboards/default HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"id": "main:closed",
"commit_message": "Define the default dashboard"
}
As response the new dashboard is returned as a DashboardInfo entity.
HTTP/1.1 201 Created
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "main:closed",
"ref": "main",
"path": "closed",
"description": "Merged and abandoned changes in last 7 weeks",
"url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
"is_default": true,
"title": "Closed changes",
"sections": [
{
"name": "Merged",
"query": "status:merged age:7w"
},
{
"name": "Abandoned",
"query": "status:abandoned age:7w"
}
]
}
Update Dashboard
'PUT /projects/{project-name}/dashboards/{dashboard-id}'
Updates a project dashboard, if a project dashboard with the given dashboard ID already exists.
Currently only supported for the default dashboard.
The update information for the dashboard must be provided in the request body as a DashboardInput entity.
PUT /projects/work%2Fmy-project/dashboards/default HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"id": "main:closed",
"commit_message": "Update the default dashboard"
}
As response the updated dashboard is returned as a DashboardInfo entity.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "main:closed",
"ref": "main",
"path": "closed",
"description": "Merged and abandoned changes in last 7 weeks",
"url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
"is_default": true,
"title": "Closed changes",
"sections": [
{
"name": "Merged",
"query": "status:merged age:7w"
},
{
"name": "Abandoned",
"query": "status:abandoned age:7w"
}
]
}
Delete Dashboard
'DELETE /projects/{project-name}/dashboards/{dashboard-id}'
Deletes a project dashboard.
Currently only supported for the default dashboard.
The request body does not need to include a DashboardInput entity if no commit message is specified.
Please note that some proxies prohibit request bodies for DELETE requests.
DELETE /projects/work%2Fmy-project/dashboards/default HTTP/1.0
HTTP/1.1 204 No Content
Label Endpoints
List Labels
'GET /projects/{project-name}/labels/'
Lists the labels that are defined in this project.
The calling user must have read access to the refs/meta/config branch of the
project.
GET /projects/All-Projects/labels/ HTTP/1.0
As result a list of LabelDefinitionInfo entities
is returned that describe the labels that are defined in this project
(inherited labels are not returned unless the inherited parameter is set, see
below). The returned labels are sorted by
label name.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"name": "Code-Review",
"project": "All-Projects",
"function": "MaxWithBlock",
"values": {
" 0": "No score",
"-1": "I would prefer this is not submitted as is",
"-2": "This shall not be submitted",
"+1": "Looks good to me, but someone else must approve",
"+2": "Looks good to me, approved"
},
"default_value": 0,
"can_override": true,
"copy_condition": "changekind:NO_CHANGE OR changekind:TRIVIAL_REBASE or is:MIN",
"allow_post_submit": true
}
]
To include inherited labels from all parent projects the parameter inherited
can be set.
The calling user must have read access to the refs/meta/config branch of the
project and all its parent projects.
GET /projects/My-Project/labels/?inherited HTTP/1.0
As result a list of LabelDefinitionInfo entities
is returned that describe the labels that are defined in this project and in
all its parent projects. The returned labels are sorted by parent projects
in-order from All-Projects through the project hierarchy to this project.
Labels that belong to the same project are sorted by label name.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"name": "Code-Review",
"project": "All-Projects",
"function": "MaxWithBlock",
"values": {
" 0": "No score",
"-1": "I would prefer this is not submitted as is",
"-2": "This shall not be submitted",
"+1": "Looks good to me, but someone else must approve",
"+2": "Looks good to me, approved"
},
"default_value": 0,
"can_override": true,
"copy_condition": "changekind:NO_CHANGE OR changekind:TRIVIAL_REBASE or is:MIN",
"allow_post_submit": true
},
{
"name": "Foo-Review",
"project": "My-Project",
"function": "MaxWithBlock",
"values": {
" 0": "No score",
"-1": "I would prefer this is not submitted as is",
"-2": "This shall not be submitted",
"+1": "Looks good to me, but someone else must approve",
"+2": "Looks good to me, approved"
},
"default_value": 0,
"can_override": true,
"copy_condition": "is:ANY",
"allow_post_submit": true
}
]
Get Label
'GET /projects/{project-name}/labels/{label-name}'
Retrieves the definition of a label that is defined in this project.
The calling user must have read access to the refs/meta/config branch of the
project.
GET /projects/All-Projects/labels/Code-Review HTTP/1.0
As response a LabelDefinitionInfo entity is returned that describes the label.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"name": "Code-Review",
"project": "All-Projects",
"function": "MaxWithBlock",
"values": {
" 0": "No score",
"-1": "I would prefer this is not submitted as is",
"-2": "This shall not be submitted",
"+1": "Looks good to me, but someone else must approve",
"+2": "Looks good to me, approved"
},
"default_value": 0,
"can_override": true,
"copy_condition": "changekind:NO_CHANGE OR changekind:TRIVIAL_REBASE OR is:MIN",
"allow_post_submit": true
}
Create Label
'PUT /projects/{project-name}/labels/{label-name}'
Creates a new label definition in this project.
The calling user must have write access to the refs/meta/config branch of the
project.
If a label with this name is already defined in this project, this label definition is updated (see Set Label).
PUT /projects/My-Project/labels/Foo HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"commit_message": "Create Foo Label",
"values": {
" 0": "No score",
"-1": "I would prefer this is not submitted as is",
"-2": "This shall not be submitted",
"+1": "Looks good to me, but someone else must approve",
"+2": "Looks good to me, approved"
}
}
As response a LabelDefinitionInfo entity is returned that describes the created label.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"name": "Foo",
"project_name": "My-Project",
"function": "MaxWithBlock",
"values": {
" 0": "No score",
"-1": "I would prefer this is not submitted as is",
"-2": "This shall not be submitted",
"+1": "Looks good to me, but someone else must approve",
"+2": "Looks good to me, approved"
},
"default_value": 0,
"can_override": true,
"copy_condition": "changekind:NO_CHANGE",
"allow_post_submit": true
}
Set Label
'PUT /projects/{project-name}/labels/{label-name}'
Updates the definition of a label that is defined in this project.
The calling user must have write access to the refs/meta/config branch of the
project.
Properties which are not set in the input entity are not modified.
PUT /projects/All-Projects/labels/Code-Review HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"commit_message": "Ignore self approvals for Code-Review label",
"ignore_self_approval": true
}
As response a LabelDefinitionInfo entity is returned that describes the updated label.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"name": "Code-Review",
"project": "All-Projects",
"function": "MaxWithBlock",
"values": {
" 0": "No score",
"-1": "I would prefer this is not submitted as is",
"-2": "This shall not be submitted",
"+1": "Looks good to me, but someone else must approve",
"+2": "Looks good to me, approved"
},
"default_value": 0,
"can_override": true,
"copy_condition": "changekind:NO_CHANGE OR changekind:TRIVIAL_REBASE OR is:MIN",
"allow_post_submit": true,
"ignore_self_approval": true
}
Delete Label
'DELETE /projects/{project-name}/labels/{label-name}'
Deletes the definition of a label that is defined in this project.
The calling user must have write access to the refs/meta/config branch of the
project.
The request body does not need to include a DeleteLabelInput entity if no commit message is specified.
DELETE /projects/My-Project/labels/Foo-Review HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"commit_message": "Delete Foo-Review label",
}
If a label was deleted the response is “204 No Content”.
HTTP/1.1 204 No Content
Batch Update Labels
'POST /projects/{project-name}/labels/'
Creates/updates/deletes multiple label definitions in this project at once.
The calling user must have write access to the refs/meta/config branch of the
project.
The updates must be specified in the request body as BatchLabelInput entity.
The updates are processed in the following order:
-
label deletions
-
label creations
-
label updates
POST /projects/My-Project/labels/ HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"commit_message": "Update Labels",
"delete": [
"Old-Review",
"Unused-Review"
],
"create": [
{
"name": "Foo-Review",
"values": {
" 0": "No score",
"-1": "I would prefer this is not submitted as is",
"-2": "This shall not be submitted",
"+1": "Looks good to me, but someone else must approve",
"+2": "Looks good to me, approved"
}
],
"update:" {
"Bar-Review": {
"function": "MaxWithBlock"
},
"Baz-Review": {
"copy_condition": "is:MIN"
}
}
}
If the label updates were done successfully the response is “200 OK”.
HTTP/1.1 200 OK
Submit Requirement Endpoints
Create Submit Requirement
'PUT /projects/{project-name}/submit_requirements/{submit-requirement-name}'
Creates a new submit requirement definition in this project.
The calling user must have write access to the refs/meta/config branch of the
project.
If a submit requirement with this name is already defined in this project, this submit requirement definition is updated (see Update Submit Requirement).
The submit requirement data must be provided in the request body as SubmitRequirementInput.
PUT /projects/My-Project/submit_requirements/Code-Review HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"name": "Code-Review",
"description": "At least one maximum vote for the Code-Review label is required",
"submittability_expression": "label:Code-Review=+2"
}
As response a SubmitRequirementInfo entity is returned that describes the created submit requirement.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"name": "Code-Review",
"description": "At least one maximum vote for the Code-Review label is required",
"submittability_expression": "label:Code-Review=+2",
"allow_override_in_child_projects": false
}
Update Submit Requirement
'PUT /projects/{project-name}/submit_requirements/{submit-requirement-name}'
Updates the definition of a submit requirement that is defined in this project.
The calling user must have write access to the refs/meta/config branch of the
project.
The new submit requirement will overwrite the existing submit requirement. That is, unspecified attributes will be set to their defaults.
PUT /projects/My-Project/submit_requirements/Code-Review HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"name": "Code-Review",
"description": "At least one maximum vote for the Code-Review label is required",
"submittability_expression": "label:Code-Review=+2"
}
As response a SubmitRequirementInfo entity is returned that describes the created submit requirement.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"name": "Code-Review",
"description": "At least one maximum vote for the Code-Review label is required",
"submittability_expression": "label:Code-Review=+2",
"allow_override_in_child_projects": false
}
Get Submit Requirement
'GET /projects/{project-name}/submit_requirements/{submit-requirement-name}'
Retrieves the definition of a submit requirement that is defined in this project.
The calling user must have read access to the refs/meta/config branch of the
project.
GET /projects/All-Projects/submit-requirement/Code-Review HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"name": "Code-Review",
"description": "At least one maximum vote for the Code-Review label is required",
"submittability_expression": "label:Code-Review=+2",
"allow_override_in_child_projects": false
}
List Submit Requirements
'GET /projects/{project-name}/submit_requirements'
Retrieves a list of all submit requirements for this project. The inherited
parameter can be supplied to also list submit requirements from parent projects.
The calling user must have read access to the refs/meta/config branch of the
project. If the inherited option is used, the caller must have read access to
the refs/meta/config branch of all parent projects as well.
As response a list of SubmitRequirementInfo entities is returned.
GET /projects/All-Projects/submit-requirements HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"name": "Code-Review",
"description": "At least one maximum vote for the Code-Review label is required",
"submittability_expression": "label:Code-Review=+2",
"allow_override_in_child_projects": false
}
]
Delete Submit Requirement
'DELETE /projects/{project-name}/submit_requirements/{submit-requirement-name}'
Deletes the definition of a submit requirement that is defined in this project.
The calling user must have write access to the refs/meta/config branch of the
project. The request would fail with 404 Not Found if there is no submit
requirement with this name for this project.
No request body is needed.
DELETE /projects/My-Project/submit_requirements/Foo-Review HTTP/1.0 Content-Type: application/json; charset=UTF-8
If a submit requirement was deleted the response is “204 No Content”.
HTTP/1.1 204 No Content
IDs
{branch-id}
The name of a branch or HEAD. The prefix refs/heads/ can be
omitted.
{commit-id}
Commit ID.
{tag-id}
The name of a tag. The prefix refs/tags/ can be omitted.
{dashboard-id}
The ID of a dashboard in the format '<ref>:<path>'.
A special dashboard ID is default which represents the default
dashboard of a project.
{label-name}
The name of a review label.
{submit-requirement-name}
The name of a submit requirement.
{project-name}
The name of the project.
If the name ends with .git, the suffix will be automatically removed.
JSON Entities
AccessCheckInfo
The AccessCheckInfo entity is the result of an access check.
| Field Name | Description | |
|---|---|---|
|
The HTTP status code for the access. 200 means success and 403 means denied. |
|
|
optional |
A clarifying message if |
|
optional |
Debug logs that may help to understand why a permission is denied or allowed. |
AutoCloseableChangesCheckInput
The AutoCloseableChangesCheckInput entity contains options for running
the AutoCloseableChangesCheck.
| Field Name | Description | |
|---|---|---|
|
optional |
Whether auto-closeable changes should be closed automatically. |
|
The branch for which the AutoCloseableChangesCheck should be performed. The 'refs/heads/' prefix for the branch name can be omitted. |
|
|
optional |
Number of commits that should be skipped when walking the commits of the branch. |
|
optional |
Maximum number of commits to walk. If not specified this defaults to 10,000 commits. 10,000 is also the maximum that can be set. Auto-closing changes is an expensive operation and the more commits are walked the slower it gets. This is why you should avoid walking too many commits. |
AutoCloseableChangesCheckResult
The AutoCloseableChangesCheckResult entity contains the results of
running the AutoCloseableChangesCheck
on a project.
| Field Name | Description |
|---|---|
|
Changes that can be auto-closed as list of
ChangeInfo entities. For each
returned ChangeInfo entity the
|
BanInput
The BanInput entity contains information for banning commits in a
project.
| Field Name | Description | |
|---|---|---|
|
List of commits to be banned. |
|
|
optional |
Reason for banning the commits. |
BanResultInfo
The BanResultInfo entity describes the result of banning commits.
| Field Name | Description | |
|---|---|---|
|
optional |
List of newly banned commits. |
|
optional |
List of commits that were already banned. |
|
optional |
List of object IDs that were ignored. |
BranchInfo
The BranchInfo entity contains information about a branch.
| Field Name | Description | |
|---|---|---|
|
The ref of the branch. |
|
|
The revision to which the branch points. |
|
|
not set if |
Whether the calling user can delete this branch. |
|
optional |
Links to the branch in external sites as a list of WebLinkInfo entries. |
BranchInput
The BranchInput entity contains information for the creation of
a new branch.
| Field Name | Description | |
|---|---|---|
|
optional |
The name of the branch. The prefix |
|
optional |
The base revision of the new branch. |
|
optional |
Map with key-value pairs that are forwarded as options to the ref operation validation listeners (e.g. can be used to skip certain validations). Which validation options are supported depends on the installed ref operation validation listeners. Gerrit core doesn’t support any validation options, but ref operation validation listeners that are implemented in plugins may. Please refer to the documentation of the installed plugins to learn whether they support validation options. Unknown validation options are silently ignored. |
CheckProjectInput
The CheckProjectInput entity contains information about which
consistency checks should be run on a project.
| Field Name | Description | |
|---|---|---|
|
optional |
Parameters for the AutoCloseableChangesCheck as AutoCloseableChangesCheckInput entity. |
CheckProjectResultInfo
The CheckProjectResultInfo entity contains results for consistency
checks that have been run on a project.
| Field Name | Description | |
|---|---|---|
|
optional |
Results for the AutoCloseableChangesCheck as AutoCloseableChangesCheckResult entity. |
CommentLinkInfo
The CommentLinkInfo entity describes a
commentlink.
| Field Name | Description | |
|---|---|---|
|
A JavaScript regular expression to match positions to be replaced with a hyperlink, as documented in commentlink.name.match. |
|
|
The URL to direct the user to whenever the regular expression is matched, as documented in commentlink.name.link. |
|
|
optional |
Text inserted before the link. |
|
optional |
Text inserted after the link. |
|
optional |
Text of the link. |
|
optional |
Whether the commentlink is enabled, as documented in commentlink.name.enabled. If not set the commentlink is enabled. |
CommentLinkInput
The CommentLinkInput entity describes the input for a
commentlink.
| Field Name | Description | |
|---|---|---|
|
A JavaScript regular expression to match positions to be replaced with a hyperlink, as documented in commentlink.name.match. |
|
|
The URL to direct the user to whenever the regular expression is matched, as documented in commentlink.name.link. |
|
|
optional |
Text inserted before the link. |
|
optional |
Text inserted after the link. |
|
optional |
Text of the link. |
|
optional |
Whether the commentlink is enabled, as documented in commentlink.name.enabled. If not set the commentlink is enabled. |
ConfigInfo
The ConfigInfo entity contains information about the effective project
configuration.
| Field Name | Description | |
|---|---|---|
|
optional |
The description of the project. |
|
optional |
InheritedBooleanInfo that tells whether authors must complete a contributor agreement on the site before pushing any commits or changes to this project. |
|
optional |
InheritedBooleanInfo that tells whether Gerrit will try to perform a 3-way merge of text file content when a file has been modified by both the destination branch and the change being submitted. This option only takes effect if submit type is not FAST_FORWARD_ONLY. |
|
optional |
InheritedBooleanInfo that tells whether each change must contain a Signed-off-by line from either the author or the uploader in the commit message. |
|
optional |
InheritedBooleanInfo that tells whether a new change is created for every commit not in target branch. |
|
optional |
InheritedBooleanInfo that tells whether a valid Change-Id footer in any commit uploaded for review is required. This does not apply to commits pushed directly to a branch or tag. This property is deprecated and will be removed in a future release. |
|
optional, not set if signed push is disabled |
InheritedBooleanInfo that tells whether signed push validation is enabled on the project. |
|
optional, not set if signed push is disabled |
InheritedBooleanInfo that tells whether signed push validation is required on the project. |
|
optional |
InheritedBooleanInfo that tells whether implicit merges should be rejected on changes pushed to the project. |
|
InheritedBooleanInfo that tells whether all new changes are set as private by default. |
|
|
InheritedBooleanInfo that tells whether all new changes are set as work-in-progress by default. |
|
|
The max object size limit of this project as a MaxObjectSizeLimitInfo entity. |
|
|
SubmitTypeInfo that describes the default submit type of the project, when not overridden at the change level. |
|
|
Deprecated; equivalent to |
|
|
optional |
InheritedBooleanInfo that indicates whether a change’s author date will be changed to match its submitter date upon submit. |
|
optional |
The state of the project, can be |
|
Map with the comment link configurations of the project. The name of the comment link configuration is mapped to a CommentlinkInfo entity. |
|
|
optional |
Plugin configuration as map which maps the plugin name to a map of
parameter names to ConfigParameterInfo
entities. Only filled for users who have read access to |
|
optional |
Actions the caller might be able to perform on this project. The information is a map of view names to |
|
optional |
InheritedBooleanInfo that tells whether empty commits should be rejected when a change is merged. ActionInfo entities. |
|
optional |
Whether to skip adding the Git commit author and committer as reviewers for a new change. |
ConfigInput
The ConfigInput entity describes a new project configuration.
| Field Name | Description | |
|---|---|---|
|
optional |
The new description of the project. |
|
optional |
Whether authors must complete a contributor agreement on the site
before pushing any commits or changes to this project. |
|
optional |
Whether Gerrit will try to perform a 3-way merge of text file content
when a file has been modified by both the destination branch and the
change being submitted. This option only takes effect if submit type is
not FAST_FORWARD_ONLY. |
|
optional |
Whether each change must contain a Signed-off-by line from either the
author or the uploader in the commit message. |
|
optional |
Whether a new change will be created for every commit not in target
branch. |
|
optional |
Whether a valid Change-Id footer in any commit
uploaded for review is required. This does not apply to commits pushed
directly to a branch or tag. |
|
optional |
Whether a check for implicit merges will be performed when changes
are pushed for review. |
|
optional |
The max object size
limit of this project as a
MaxObjectSizeLimitInfo entity. |
|
optional |
The default submit type of the project, can be |
|
optional |
The state of the project, can be |
|
optional |
Plugin configuration values as map which maps the plugin name to a map of parameter names to values. |
|
optional |
Whether empty commits should be rejected when a change is merged.
Can be |
commentlinks |
optional |
Map of commentlink names to CommentLinkInput entities to add or update on the project. If the given commentlink already exists, it will be updated with the given values, otherwise it will be created. If the value is null, that entry is deleted. |
ConfigParameterInfo
The ConfigParameterInfo entity describes a project configuration
parameter.
| Field Name | Description | |
|---|---|---|
|
optional |
The display name of the configuration parameter. |
|
optional |
The description of the configuration parameter. |
|
optional |
Warning message for the configuration parameter. |
|
The type of the configuration parameter. Can be |
|
|
optional |
The value of the configuration parameter as string. If the parameter
is inheritable this is the effective value which is deduced from
|
|
optional |
The list of values. Only set if the |
|
|
Whether the value is editable. |
|
optional |
The list of permitted values. Only set if the |
|
|
Whether the configuration parameter can be inherited. |
|
optional |
The value of the configuration parameter that is configured on this
project, only set if |
|
optional |
The inherited value of the configuration parameter, only set if
|
DashboardInfo
The DashboardInfo entity contains information about a project
dashboard.
| Field Name | Description | |
|---|---|---|
|
The ID of the dashboard. The ID has the format '<ref>:<path>', where ref and path are URL encoded. |
|
|
The name of the project for which this dashboard is returned. |
|
|
The name of the project in which this dashboard is defined.
This is different from |
|
|
The name of the ref in which the dashboard is defined, without the
|
|
|
The path of the file in which the dashboard is defined. |
|
|
optional |
The description of the dashboard. |
|
optional |
Subquery that applies to all sections in the dashboard. |
|
The URL under which the dashboard can be opened in the Gerrit Web UI. |
|
|
not set if |
Whether this is the default dashboard of the project. |
|
optional |
The title of the dashboard. |
|
The list of sections in the dashboard. |
DashboardInput
The DashboardInput entity contains information to create/update a
project dashboard.
| Field Name | Description | |
|---|---|---|
|
optional |
URL encoded ID of a dashboard to which this dashboard should link to. |
|
optional |
Message that should be used to commit the change of the dashboard. |
DashboardSectionInfo
The DashboardSectionInfo entity contains information about a section
in a dashboard.
| Field Name | Description |
|---|---|
|
The title of the section. |
|
The query of the section. |
DeleteLabelInput
The DeleteLabelInput entity contains information for deleting a label
definition in a project.
| Field Name | Description | |
|---|---|---|
|
optional |
Message that should be used to commit the deletion of the label in the
|
DeleteBranchesInput
The DeleteBranchesInput entity contains information about branches that should
be deleted.
| Field Name | Description |
|---|---|
|
A list of branch names that identify the branches that should be deleted. |
DeleteTagsInput
The DeleteTagsInput entity contains information about tags that should
be deleted.
| Field Name | Description |
|---|---|
|
A list of tag names that identify the tags that should be deleted. |
GCInput
The GCInput entity contains information to run the Git garbage
collection.
| Field Name | Description | |
|---|---|---|
|
|
Whether progress information should be shown. |
|
|
Whether an aggressive garbage collection should be done. |
|
|
Whether the garbage collection should run asynchronously. |
HeadInput
The HeadInput entity contains information for setting HEAD for a
project.
| Field Name | Description |
|---|---|
|
The ref to which |
IndexProjectInput
The IndexProjectInput contains parameters for indexing a project.
| Field Name | Description | |
|---|---|---|
|
If children should be indexed recursively. |
|
|
If projects should be indexed asynchronously. |
InheritedBooleanInfo
A boolean value that can also be inherited.
| Field Name | Description | |
|---|---|---|
|
The effective boolean value. |
|
|
The configured value, can be |
|
|
optional |
The boolean value inherited from the parent. |
LabelDefinitionInfo
The LabelDefinitionInfo entity describes a
review label.
| Field Name | Description | |
|---|---|---|
|
The name of the label. |
|
|
optional |
The description of the label. |
|
The name of the project in which this label is defined. |
|
|
The function of the label (can be
|
|
|
The values of the label as a map of label value to value description. The label values are formatted strings, e.g. "+1" instead of "1", " 0" instead of "0". |
|
|
The default value of the label (as integer). |
|
|
optional |
A list of branches for which the label applies. A branch can be a ref, a ref pattern or a regular expression. If not set, the label applies for all branches. |
|
|
Whether this label can be overridden by child projects. |
|
optional |
See copyCondition. |
|
|
Whether allowPostSubmit is set on the label. |
|
|
Whether ignoreSelfApproval is set on the label. |
LabelDefinitionInput
The LabelDefinitionInput entity describes a
review label.
| Field Name | Description | |
|---|---|---|
|
optional |
Message that should be used to commit the change of the label in the
|
|
optional |
The new name of the label.+
For label creation the name is required if this |
|
optional |
The new description for the label. |
|
optional |
The new function of the label (can be
|
|
optional |
The new values of the label as a map of label value to value description. The label values are formatted strings, e.g. "+1" instead of "1", " 0" instead of "0". |
|
optional |
The new default value of the label (as integer). |
|
optional |
The new branches for which the label applies as a list of branches. A branch can be a ref, a ref pattern or a regular expression. If not set, the label applies for all branches. |
|
optional |
Whether this label can be overridden by child projects. |
|
optional |
See copyCondition. |
|
optional |
If true, clears the value stored in |
|
optional |
Whether allowPostSubmit is set on the label. |
|
optional |
Whether ignoreSelfApproval is set on the label. |
LabelTypeInfo
The LabelTypeInfo entity contains metadata about the labels that a
project has.
| Field Name | Description | |
|---|---|---|
|
Map of the available values to their description. |
|
|
The default value of this label. |
MaxObjectSizeLimitInfo
The MaxObjectSizeLimitInfo entity contains information about the
max object size
limit of a project.
| Field Name | Description | |
|---|---|---|
|
optional |
The effective value in bytes of the max object size limit. |
|
optional |
The max object size limit that is configured on the project as a
formatted string. |
|
optional |
A string describing whether the value was inherited or overridden from
the parent project or global config. |
BatchLabelInput
The BatchLabelInput entity contains information for batch updating label
definitions in a project.
| Field Name | Description | |
|---|---|---|
|
optional |
Message that should be used to commit the label updates in the
|
|
optional |
List of labels that should be deleted. |
|
optional |
List of LabelDefinitionInput entities that describe labels that should be created. |
|
optional |
Map of label names to LabelDefinitionInput entities that describe the updates that should be done for the labels. |
ProjectAccessInput
The ProjectAccessInput describes changes that should be applied to a project
access config.
| Field Name | Description | |
|---|---|---|
|
optional |
A list of deductions to be applied to the project access as ProjectAccessInfo entities. |
|
optional |
A list of additions to be applied to the project access as ProjectAccessInfo entities. |
|
optional |
A commit message for this change. |
|
optional |
A new parent for the project to inherit from. Changing the parent project requires administrative privileges. |
ProjectDescriptionInput
The ProjectDescriptionInput entity contains information for setting a
project description.
| Field Name | Description | |
|---|---|---|
|
optional |
The project description. |
|
optional |
Message that should be used to commit the change of the project
description in the |
ProjectInfo
The ProjectInfo entity contains information about a project.
| Field Name | Description | |
|---|---|---|
|
The URL encoded project name. |
|
|
not set if returned in a map where the project name is used as map key |
The name of the project. |
|
optional |
The name of the parent project. |
|
optional |
The description of the project. |
|
optional |
|
|
optional |
Map of branch names to HEAD revisions. |
|
optional |
Map of label names to LabelTypeInfo entries. This field is filled for Create Project and Get Project calls. |
|
optional |
Links to the project in external sites as a list of WebLinkInfo entries. |
|
optional, not set if |
Whether the query would deliver more results if not limited. |
ProjectInput
The ProjectInput entity contains information for the creation of
a new project.
| Field Name | Description | |
|---|---|---|
|
optional |
The name of the project (not encoded). |
|
optional |
The name of the parent project. |
|
optional |
The description of the project. |
|
|
Whether a permission-only project should be created. |
|
|
Whether an empty initial commit should be created. |
|
optional |
The submit type that should be set for the project
( |
|
optional |
A list of branches that should be initially created. |
|
optional |
A list of groups that should be assigned as project owner. |
|
|
Whether contributor agreements should be used for the project ( |
|
|
Whether the usage of 'Signed-Off-By' footers is required for the
project ( |
|
|
Whether a new change is created for every commit not in target branch
for the project ( |
|
|
Whether content merge should be enabled for the project ( |
|
|
Whether the usage of Change-Ids is required for the project ( |
|
|
Whether signed push validation is enabled on the project ( |
|
|
Whether signed push validation is required on the project ( |
|
optional |
Max allowed Git object size for this project. Common unit suffixes of 'k', 'm', or 'g' are supported. |
|
optional |
Plugin configuration values as map which maps the plugin name to a map of parameter names to values. |
|
optional |
Whether empty commits should be rejected when a change is merged
( |
ProjectParentInput
The ProjectParentInput entity contains information for setting a
project parent.
| Field Name | Description | |
|---|---|---|
|
The name of the parent project. |
|
|
optional |
Message that should be used to commit the change of the project parent
in the |
ReflogEntryInfo
The ReflogEntryInfo entity describes an entry in a reflog.
| Field Name | Description |
|---|---|
|
The old commit ID. |
|
The new commit ID. |
|
The user performing the change as a GitPersonInfo entity. |
|
Comment of the reflog entry. |
RepositoryStatisticsInfo
The RepositoryStatisticsInfo entity contains information about
statistics of a Git repository.
| Field Name | Description |
|---|---|
|
Number of loose objects. |
|
Number of loose refs. |
|
Number of pack files. |
|
Number of packed objects. |
|
Number of packed refs. |
|
Size of loose objects in bytes. |
|
Size of packed objects in bytes. |
SubmitRequirementInfo
The SubmitRequirementInfo entity describes a submit requirement.
| Field Name | Description | |
|---|---|---|
|
The submit requirement name. |
|
|
optional |
Description of the submit requirement. |
|
optional |
Query expression that can be evaluated on any change. If evaluated to true on a change, the submit requirement is then applicable for this change. If not specified, the submit requirement is applicable for all changes. |
|
Query expression that can be evaluated on any change. If evaluated to true on a change, the submit requirement is fulfilled and not blocking change submission. |
|
|
optional |
Query expression that can be evaluated on any change. If evaluated to true on a change, the submit requirement is overridden and not blocking change submission. |
|
Whether this submit requirement can be overridden in child projects. |
SubmitRequirementInput
The SubmitRequirementInput entity describes a submit requirement.
| Field Name | Description | |
|---|---|---|
|
The submit requirement name. |
|
|
optional |
Description of the submit requirement. |
|
optional |
Query expression that can be evaluated on any change. If evaluated to true on a change, the submit requirement is then applicable for this change. If not specified, the submit requirement is applicable for all changes. |
|
Query expression that can be evaluated on any change. If evaluated to true on a change, the submit requirement is fulfilled and not blocking change submission. |
|
|
optional |
Query expression that can be evaluated on any change. If evaluated to true on a change, the submit requirement is overridden and not blocking change submission. |
|
optional |
Whether this submit requirement can be overridden in child projects. Default is
|
SubmitTypeInfo
Information about the default submit type of a project, taking into account project inheritance.
Valid values for each field are MERGE_IF_NECESSARY, FAST_FORWARD_ONLY,
REBASE_IF_NECESSARY, REBASE_ALWAYS, MERGE_ALWAYS or CHERRY_PICK, plus
INHERIT where applicable.
| Field Name | Description |
|---|---|
|
The effective submit type value. Never |
|
The configured value, can be one of the submit types, or |
|
The effective value that would be inherited from the parent. Never |
TagInfo
The TagInfo entity contains information about a tag.
| Field Name | Description | |
|---|---|---|
|
The ref of the tag. |
|
|
For lightweight tags, the revision of the commit to which the tag points. For annotated tags, the revision of the tag object. |
|
|
Only set for annotated tags. |
The revision of the object to which the tag points. |
|
Only set for annotated tags. |
The tag message. For signed tags, includes the signature. |
|
Only set for annotated tags, if present in the tag. |
The tagger as a GitPersonInfo entity. |
|
optional |
The timestamp of when the tag
was created. For annotated and signed tags, this is the timestamp of the tag object
and is the same as the |
|
not set if |
Whether the calling user can delete this tag. |
|
optional |
Links to the tag in external sites as a list of WebLinkInfo entries. |
TagInput
The TagInput entity contains information for creating a tag.
| Field Name | Description | |
|---|---|---|
|
The name of the tag. The leading |
|
|
optional |
The revision to which the tag should point. If not
specified, the project’s |
|
optional |
The tag message. When set, the tag will be created as an annotated tag. |
Part of Gerrit Code Review