| :linkattrs: |
| = Gerrit Code Review - /projects/ REST API |
| |
| This page describes the project related REST endpoints. |
| Please also take note of the general information on the |
| link:rest-api.html[REST API]. |
| |
| [[project-endpoints]] |
| == Project Endpoints |
| |
| [[list-projects]] |
| === List Projects |
| -- |
| 'GET /projects/' |
| -- |
| |
| Lists the projects accessible by the caller. This is the same as |
| using the link:cmd-ls-projects.html[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 |
| link:#project-info[ProjectInfo] entries. The entries in the map are sorted |
| by project name. |
| |
| .Request |
| ---- |
| GET /projects/?d HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| 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]] |
| ==== 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: |
| + |
| .Request |
| ---- |
| GET /projects/?b=master HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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: |
| + |
| .Request |
| ---- |
| GET /projects/?d HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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: |
| + |
| .Request |
| ---- |
| GET /projects/?n=1 HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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. |
| |
| |
| [[suggest-projects]] |
| 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 `m` or `r`. |
| + |
| List all projects that start with `platform/`: |
| + |
| .Request |
| ---- |
| GET /projects/?p=platform%2F HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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 `m` or `p`. |
| + |
| List all projects that match regex `test.*project`: |
| + |
| .Request |
| ---- |
| GET /projects/?r=test.*project HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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: |
| + |
| .Request |
| ---- |
| GET /projects/?n=1&S=1 HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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 `r` or `p`. |
| + |
| List all projects that match substring `test/`: |
| + |
| .Request |
| ---- |
| GET /projects/?m=test%2F HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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': |
| + |
| .Request |
| ---- |
| GET /projects/?type=PERMISSIONS HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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 `state` option. |
| + |
| .Request |
| ---- |
| GET /projects/?all HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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 |
| `all` option. |
| + |
| .Request |
| ---- |
| GET /projects/?state=HIDDEN HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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]] |
| === Query Projects |
| -- |
| 'GET /projects/?query=<query>' |
| -- |
| |
| Queries projects visible to the caller. The |
| link:user-search-projects.html#_search_operators[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 link:#project-info[ProjectInfo] entities is returned. |
| |
| .Request |
| ---- |
| GET /projects/?query=name:test HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "id": "test", |
| "description": "\u003chtml\u003e is escaped" |
| } |
| ] |
| ---- |
| |
| [[project-query-limit]] |
| ==== 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-query-options]] |
| ==== 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 link:#project-options[List Projects] |
| REST endpoint. |
| |
| [[get-project]] |
| === Get Project |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]' |
| -- |
| |
| Retrieves a project. |
| |
| .Request |
| ---- |
| GET /projects/plugins%2Freplication HTTP/1.0 |
| ---- |
| |
| As response a link:#project-info[ProjectInfo] entity is returned that |
| describes the project. |
| |
| .Response |
| ---- |
| 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]] |
| === Create Project |
| -- |
| 'PUT /projects/link:#project-name[\{project-name\}]' |
| -- |
| |
| Creates a new project. |
| |
| In the request body additional data for the project can be provided as |
| link:#project-input[ProjectInput]. |
| |
| .Request |
| ---- |
| 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 link:#project-info[ProjectInfo] entity is returned that |
| describes the created project. |
| |
| .Response |
| ---- |
| 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 Project Description |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/description' |
| -- |
| |
| Retrieves the description of a project. |
| |
| .Request |
| ---- |
| GET /projects/plugins%2Freplication/description HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| 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]] |
| === Set Project Description |
| -- |
| 'PUT /projects/link:#project-name[\{project-name\}]/description' |
| -- |
| |
| Sets the description of a project. |
| |
| The new project description must be provided in the request body inside |
| a link:#project-description-input[ProjectDescriptionInput] entity. |
| |
| .Request |
| ---- |
| 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. |
| |
| .Response |
| ---- |
| 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 Project Description |
| -- |
| 'DELETE /projects/link:#project-name[\{project-name\}]/description' |
| -- |
| |
| Deletes the description of a project. |
| |
| .Request |
| ---- |
| DELETE /projects/plugins%2Freplication/description HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| A commit message can be provided in the request body as a |
| link:#project-description-input[ProjectDescriptionInput] entity. |
| Historically, this method allowed a body in the DELETE, but that behavior is |
| link:https://www.gerritcodereview.com/releases/2.16.md[deprecated,role=external,window=_blank]. |
| In this case, use link:#set-project-description[PUT] instead. |
| |
| .Request |
| ---- |
| PUT /projects/plugins%2Freplication/description HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "commit_message": "Update the project description" |
| } |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[get-project-parent]] |
| === Get Project Parent |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/parent' |
| -- |
| |
| Retrieves the name of a project's parent project. For the |
| `All-Projects` root project an empty string is returned. |
| |
| .Request |
| ---- |
| GET /projects/plugins%2Freplication/parent HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "All-Projects" |
| ---- |
| |
| [[set-project-parent]] |
| === Set Project Parent |
| -- |
| 'PUT /projects/link:#project-name[\{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 link:#project-parent-input[ProjectParentInput] entity. |
| |
| .Request |
| ---- |
| 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. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "Public-Plugins" |
| ---- |
| |
| [[get-head]] |
| === Get HEAD |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/HEAD' |
| -- |
| |
| Retrieves for a project the name of the branch to which `HEAD` points. |
| |
| .Request |
| ---- |
| GET /projects/plugins%2Freplication/HEAD HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "refs/heads/master" |
| ---- |
| |
| [[set-head]] |
| === Set HEAD |
| -- |
| 'PUT /projects/link:#project-name[\{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 link:#head-input[HeadInput] entity. |
| |
| .Request |
| ---- |
| 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. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "refs/heads/stable" |
| ---- |
| |
| [[get-repository-statistics]] |
| === Get Repository Statistics |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/statistics.git' |
| -- |
| |
| Return statistics for the repository of a project. |
| |
| .Request |
| ---- |
| GET /projects/plugins%2Freplication/statistics.git HTTP/1.0 |
| ---- |
| |
| The repository statistics are returned as a |
| link:#repository-statistics-info[RepositoryStatisticsInfo] entity. |
| |
| .Response |
| ---- |
| 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 Config |
| -- |
| 'GET /projects/link:#project-name[\{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. |
| |
| .Request |
| ---- |
| GET /projects/myproject/config |
| ---- |
| |
| A link:#config-info[ConfigInfo] entity is returned that describes the |
| project configuration. Some fields are only visible to users that have |
| read access to `refs/meta/config`. |
| |
| .Response |
| ---- |
| 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]] |
| === Set Config |
| -- |
| 'PUT /projects/link:#project-name[\{project-name\}]/config' |
| -- |
| |
| Sets the configuration of a project. |
| |
| The new configuration must be provided in the request body as a |
| link:#config-input[ConfigInput] entity. |
| |
| .Request |
| ---- |
| 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 link:#config-info[ |
| ConfigInfo] entity. |
| |
| .Response |
| ---- |
| 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]] |
| === Run GC |
| -- |
| 'POST /projects/link:#project-name[\{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 link:#gc-input[GCInput] entity. |
| |
| .Request |
| ---- |
| 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. |
| |
| .Response |
| ---- |
| 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 link:rest-api-config.html#get-task[background task] |
| which allows to inspect the progress of its execution. In case of asynchronous |
| execution the `show_progress` option is ignored. |
| |
| .Request |
| ---- |
| POST /projects/plugins%2Freplication/gc HTTP/1.0 |
| Content-Type: application/json;charset=UTF-8 |
| |
| { |
| "async": true |
| } |
| ---- |
| |
| The response is empty. |
| |
| .Response |
| ---- |
| HTTP/1.1 202 Accepted |
| Content-Disposition: attachment |
| Location: https:<host>/a/config/server/tasks/383a0602 |
| ---- |
| |
| [[ban-commit]] |
| === Ban Commit |
| -- |
| 'PUT /projects/link:#project-name[\{project-name\}]/ban' |
| -- |
| |
| Marks commits as banned for the project. If a commit is banned Gerrit |
| rejects every push that includes this commit with |
| link:error-contains-banned-commit.html[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 |
| link:#ban-input[BanInput] entity. |
| |
| The caller must be project owner. |
| |
| .Request |
| ---- |
| PUT /projects/plugins%2Freplication/ban HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "commits": [ |
| "a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96", |
| "cf5b56541f84b8b57e16810b18daca9c3adc377b" |
| ], |
| "reason": "Violates IP" |
| } |
| ---- |
| |
| As response a link:#ban-result-info[BanResultInfo] entity is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "newly_banned": [ |
| "a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96", |
| "cf5b56541f84b8b57e16810b18daca9c3adc377b" |
| ] |
| } |
| ---- |
| |
| [[get-access]] |
| === List Access Rights for Project |
| -- |
| 'GET /projects/link:rest-api-projects.html#project-name[\{project-name\}]/access' |
| -- |
| |
| Lists the access rights for a single project. |
| |
| As result a |
| link:rest-api-access.html#project-access-info[ProjectAccessInfo] |
| entity is returned. |
| |
| .Request |
| ---- |
| GET /projects/MyProject/access HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| 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" |
| } |
| } |
| } |
| ---- |
| |
| [[set-access]] |
| === Add, Update and Delete Access Rights for Project |
| -- |
| 'POST /projects/link:rest-api-projects.html#project-name[\{project-name\}]/access' |
| -- |
| |
| Sets access rights for the project using the diff schema provided by |
| link:#project-access-input[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 |
| link:rest-api-access.html#project-access-info[ProjectAccessInfo] |
| entity is returned. |
| |
| .Request |
| ---- |
| POST /projects/MyProject/access HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "remove": { |
| "refs/*": { |
| "permissions": { |
| "read": { |
| "rules": { |
| "c2ce4749a32ceb82cd6adcce65b8216e12afb41c": { |
| "action": "ALLOW" |
| } |
| } |
| } |
| } |
| } |
| } |
| } |
| ---- |
| |
| .Response |
| ---- |
| 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]] |
| === Create Change for review. |
| |
| This endpoint is functionally equivalent to |
| link:rest-api-changes.html#create-change[create change in the change |
| API], but it has the project name in the URL, which is easier to route |
| in sharded deployments. |
| |
| .Request |
| ---- |
| 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 link:#change-info[ChangeInfo] entity is returned that describes |
| the resulting change. |
| |
| .Response |
| ---- |
| 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-change]] |
| === Create Access Rights Change for review. |
| -- |
| 'PUT /projects/link:rest-api-projects.html#project-name[\{project-name\}]/access:review |
| -- |
| |
| Sets access rights for the project using the diff schema provided by |
| link:#project-access-input[ProjectAccessInput] |
| |
| This takes the same input as link:#set-access[Update Access Rights], but creates a pending |
| change for review. Like link:#create-change[Create Change], it returns |
| a link:#change-info[ChangeInfo] entity describing the resulting change. |
| |
| .Request |
| ---- |
| 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 |
| } |
| } |
| } |
| } |
| } |
| } |
| } |
| ---- |
| |
| .Response |
| ---- |
| 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]] |
| === 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 |
| link:access-control.html#capability_viewAccess[View Access] global |
| capability. |
| |
| The result is a link:#access-check-info[AccessCheckInfo] entity |
| detailing the access of the given user for the given project, |
| project-ref, or project-permission-ref combination. |
| |
| .Response |
| ---- |
| 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]] |
| ==== 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 `perm` is specified. |
| |
| [[index]] |
| === 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 link:#index-project-input[IndexProjectInput] entity can be provided. |
| |
| .Request |
| ---- |
| POST /projects/MyProject/index HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "index_children": "true" |
| "async": "true" |
| } |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 202 Accepted |
| Content-Disposition: attachment |
| ---- |
| |
| [[index.changes]] |
| === 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. |
| |
| .Request |
| ---- |
| POST /projects/MyProject/index.changes HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 202 Accepted |
| Content-Disposition: attachment |
| ---- |
| |
| [[check]] |
| === Check project consistency |
| |
| Performs consistency checks on the project. |
| |
| Which consistency checks should be performed is controlled by the |
| link:#check-project-input[CheckProjectInput] entity in the request |
| body. |
| |
| The following consistency checks are supported: |
| |
| [[auto-closeable-changes-check]] |
| -- |
| * 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 |
| link:access-control.html#capability_administrateServer[Administrate Server] |
| global capability. |
| |
| .Request |
| ---- |
| 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 link:#check-project-result-info[CheckProjectResultInfo] |
| entity is returned that results for the consistency checks. |
| |
| .Response |
| ---- |
| 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" |
| } |
| ] |
| } |
| ] |
| } |
| } |
| } |
| ---- |
| |
| [[commits-included-in]] |
| === Get Commits Included In Refs |
| -- |
| 'GET /projects/link:#project-name[\{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. |
| |
| .Request |
| ---- |
| GET /projects/work%2Fmy-project/commits:in?commit=a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96&commit=6d2a3adb10e844c33617fc948dbeb88e868d396e&ref=refs/heads/master&ref=refs/heads/branch1 HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| 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]] |
| == Branch Endpoints |
| |
| [[list-branches]] |
| === List Branches |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/branches/' |
| -- |
| |
| List the branches of a project. |
| |
| As result a list of link:#branch-info[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. |
| |
| .Request |
| ---- |
| GET /projects/work%2Fmy-project/branches/ HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| 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]] |
| ==== Branch Options |
| |
| Limit(n):: |
| Limit the number of branches to be included in the results. |
| + |
| .Request |
| ---- |
| GET /projects/testproject/branches?n=1 HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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. |
| + |
| .Request |
| ---- |
| GET /projects/testproject/branches?n=1&s=0 HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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`: |
| + |
| .Request |
| ---- |
| GET /projects/testproject/branches?m=test HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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`: |
| + |
| .Request |
| ---- |
| GET /projects/testproject/branches?r=t.*1 HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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 `Skip` |
| parameter, and also must be set to an exact token received by the server in a |
| previous call, otherwise the request would fail with `400 Bad Request`. |
| |
| [[get-branch]] |
| === Get Branch |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{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. |
| |
| .Request |
| ---- |
| GET /projects/work%2Fmy-project/branches/master HTTP/1.0 |
| ---- |
| |
| As response a link:#branch-info[BranchInfo] entity is returned that |
| describes the branch. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "ref": "refs/heads/master", |
| "revision": "67ebf73496383c6777035e374d2d664009e2aa5c" |
| } |
| ---- |
| |
| [[create-branch]] |
| === Create Branch |
| -- |
| 'PUT /projects/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{branch-id\}]' |
| -- |
| |
| Creates a new branch. |
| |
| In the request body additional data for the branch can be provided as |
| link:#branch-input[BranchInput]. The link:#branch-id[\{branch-id\}] in the URL |
| should exactly match with the `ref` field of link:#branch-input[BranchInput], or |
| otherwise the request would fail with `400 Bad Request`. |
| |
| .Request |
| ---- |
| PUT /projects/MyProject/branches/stable HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "revision": "76016386a0d8ecc7b6be212424978bb45959d668" |
| } |
| ---- |
| |
| As response a link:#branch-info[BranchInfo] entity is returned that |
| describes the created branch. |
| |
| .Response |
| ---- |
| 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 Branch |
| -- |
| 'DELETE /projects/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{branch-id\}]' |
| -- |
| |
| Deletes a branch. |
| |
| .Request |
| ---- |
| DELETE /projects/MyProject/branches/stable HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[delete-branches]] |
| === Delete Branches |
| -- |
| 'POST /projects/link:#project-name[\{project-name\}]/branches:delete' |
| -- |
| |
| Delete one or more branches. |
| |
| The branches to be deleted must be provided in the request body as a |
| link:#delete-branches-input[DeleteBranchesInput] entity. |
| |
| .Request |
| ---- |
| POST /projects/MyProject/branches:delete HTTP/1.0 |
| Content-Type: application/json;charset=UTF-8 |
| |
| { |
| "branches": [ |
| "stable-1.0", |
| "stable-2.0" |
| ] |
| } |
| ---- |
| |
| .Response |
| ---- |
| 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 Content |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{branch-id\}]/files/link:rest-api-changes.html#file-id[\{file-id\}]/content' |
| -- |
| |
| Gets the content of a file from the HEAD revision of a certain branch. |
| |
| .Request |
| ---- |
| 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. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: text/plain; charset=UTF-8 |
| |
| Ly8gQ29weXJpZ2h0IChDKSAyMDEwIFRoZSBBbmRyb2lkIE9wZW4gU291cmNlIFByb2plY... |
| ---- |
| |
| [[suggest-reviewers]] |
| === Suggest Reviewers |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{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 |
| link:config.html#suggest.skipServiceUsers[skipServiceUsers] is set to `false`) |
| |
| Groups can be excluded from the results by specifying the 'exclude-groups' |
| request parameter: |
| |
| -- |
| 'GET /changes/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{branch-id\}]/suggest_reviewers?q=J&n=5&exclude-groups' |
| -- |
| |
| As result a list of link:#suggested-reviewer-info[SuggestedReviewerInfo] entries is returned. |
| |
| .Request |
| ---- |
| GET /projects/myProject/branches/myBranch/suggest_reviewers?q=J HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| 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/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{branch-id\}]/suggest_reviewers?q=J&reviewer-state=CC' |
| -- |
| |
| |
| [[get-mergeable-info]] |
| === Get Mergeable Information |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{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 |
| link:rest-api-changes.html#merge-input[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. |
| |
| .Request |
| ---- |
| GET /projects/test/branches/master/mergeable?source=testbranch&strategy=recursive HTTP/1.0 |
| ---- |
| |
| As response a link:rest-api-changes.html#mergeable-info[MergeableInfo] entity is returned. |
| |
| .Response |
| ---- |
| 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. |
| |
| .Response |
| ---- |
| 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. |
| |
| .Response |
| ---- |
| 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. |
| |
| .Response |
| ---- |
| 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 Reflog |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{branch-id\}]/reflog' |
| -- |
| |
| Gets the reflog of a certain branch. |
| |
| The caller must be project owner. |
| |
| .Request |
| ---- |
| GET /projects/gerrit/branches/master/reflog HTTP/1.0 |
| ---- |
| |
| As response a list of link:#reflog-entry-info[ReflogEntryInfo] entities |
| is returned that describe the reflog entries. The reflog entries are |
| returned in reverse order. |
| |
| .Response |
| ---- |
| 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]] |
| == Child Project Endpoints |
| |
| [[list-child-projects]] |
| === List Child Projects |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/children/' |
| -- |
| |
| List the direct child projects of a project. |
| |
| .Request |
| ---- |
| GET /projects/Public-Plugins/children/ HTTP/1.0 |
| ---- |
| |
| As result a list of link:#project-info[ProjectInfo] entries is |
| returned that describe the child projects. |
| |
| .Response |
| ---- |
| 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. |
| |
| .Request |
| ---- |
| GET /projects/Public-Projects/children/?recursive HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| 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 Child Project |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/children/link:#project-name[\{project-name\}]' |
| -- |
| |
| Retrieves a child project. If a non-direct child project should be |
| retrieved the parameter `recursive` must be set. |
| |
| .Request |
| ---- |
| GET /projects/Public-Plugins/children/plugins%2Freplication HTTP/1.0 |
| ---- |
| |
| As response a link:#project-info[ProjectInfo] entity is returned that |
| describes the child project. |
| |
| .Response |
| ---- |
| 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]] |
| == Tag Endpoints |
| |
| [[create-tag]] |
| === Create Tag |
| |
| -- |
| 'PUT /projects/link:#project-name[\{project-name\}]/tags/link:#tag-id[\{tag-id\}]' |
| -- |
| |
| Create a new tag on the project. |
| |
| In the request body additional data for the tag can be provided as |
| link:#tag-input[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. |
| |
| .Request |
| ---- |
| PUT /projects/MyProject/tags/v1.0 HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "message": "annotation", |
| "revision": "c83117624b5b5d8a7f86093824e2f9c1ed309d63" |
| } |
| ---- |
| |
| As response a link:#tag-info[TagInfo] entity is returned that describes |
| the created tag. |
| |
| .Response |
| ---- |
| 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]] |
| === List Tags |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/tags/' |
| -- |
| |
| List the tags of a project. |
| |
| As result a list of link:#tag-info[TagInfo] entries is returned. |
| |
| Only includes tags under the `refs/tags/` namespace. |
| |
| .Request |
| ---- |
| GET /projects/work%2Fmy-project/tags/ HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| 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]] |
| ==== Tag Options |
| |
| Limit(n):: |
| Limit the number of tags to be included in the results. |
| + |
| .Request |
| ---- |
| GET /projects/work%2Fmy-project/tags?n=2 HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| 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" |
| } |
| ] |
| ---- |
| |
| Skip(S):: |
| Skip the given number of tags from the beginning of the list. |
| + |
| .Request |
| ---- |
| GET /projects/work%2Fmy-project/tags?n=2&s=1 HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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`: |
| |
| + |
| .Request |
| ---- |
| GET /projects/testproject/tags?m=v2 HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/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`: |
| + |
| .Request |
| ---- |
| GET /projects/testproject/tags?r=v.*0 HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| 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 |
| } |
| } |
| ] |
| ---- |
| |
| [[get-tag]] |
| === Get Tag |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/tags/link:#tag-id[\{tag-id\}]' |
| -- |
| |
| Retrieves a tag of a project. |
| |
| .Request |
| ---- |
| GET /projects/work%2Fmy-project/tags/v1.0 HTTP/1.0 |
| ---- |
| |
| As response a link:#tag-info[TagInfo] entity is returned that describes the tag. |
| |
| .Response |
| ---- |
| 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 Tag |
| -- |
| 'DELETE /projects/link:#project-name[\{project-name\}]/tags/link:#tag-id[\{tag-id\}]' |
| -- |
| |
| Deletes a tag. |
| |
| .Request |
| ---- |
| DELETE /projects/MyProject/tags/v1.0 HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[delete-tags]] |
| === Delete Tags |
| -- |
| 'POST /projects/link:#project-name[\{project-name\}]/tags:delete' |
| -- |
| |
| Delete one or more tags. |
| |
| The tags to be deleted must be provided in the request body as a |
| link:#delete-tags-input[DeleteTagsInput] entity. |
| |
| .Request |
| ---- |
| POST /projects/MyProject/tags:delete HTTP/1.0 |
| Content-Type: application/json;charset=UTF-8 |
| |
| { |
| "tags": [ |
| "v1.0", |
| "v2.0" |
| ] |
| } |
| ---- |
| |
| .Response |
| ---- |
| 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]] |
| == Commit Endpoints |
| |
| [[get-commit]] |
| === Get Commit |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/commits/link:#commit-id[\{commit-id\}]' |
| -- |
| |
| Retrieves a commit of a project. |
| |
| The commit must be visible to the caller. |
| |
| .Request |
| ---- |
| GET /projects/work%2Fmy-project/commits/a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96 HTTP/1.0 |
| ---- |
| |
| As response a link:rest-api-changes.html#commit-info[CommitInfo] entity |
| is returned that describes the commit. |
| |
| .Response |
| ---- |
| 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 Included In |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/commits/link:#commit-id[\{commit-id\}]/in' |
| -- |
| |
| Retrieves the branches and tags in which a change is included. As result |
| an link:rest-api-changes.html#included-in-info[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. |
| |
| .Request |
| ---- |
| GET /projects/work%2Fmy-project/commits/a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96/in HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "branches": [ |
| "master" |
| ], |
| "tags": [] |
| } |
| ---- |
| |
| [[get-content-from-commit]] |
| === Get Content |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/commits/link:#commit-id[\{commit-id\}]/files/link:rest-api-changes.html#file-id[\{file-id\}]/content' |
| -- |
| |
| Gets the content of a file from a certain commit. |
| |
| .Request |
| ---- |
| 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. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: text/plain; charset=UTF-8 |
| |
| Ly8gQ29weXJpZ2h0IChDKSAyMDEwIFRoZSBBbmRyb2lkIE9wZW4gU291cmNlIFByb2plY... |
| ---- |
| |
| |
| [[cherry-pick-commit]] |
| === Cherry Pick Commit |
| -- |
| 'POST /projects/link:#project-name[\{project-name\}]/commits/link:#commit-id[\{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 link:rest-api-changes.html#cherry-pick[CherryPick]. |
| |
| The destination branch must be provided in the request body inside a |
| link:rest-api-changes.html#cherrypick-input[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. |
| |
| .Request |
| ---- |
| 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 link:rest-api-changes.html#change-info[ChangeInfo] entity |
| is returned that describes the resulting cherry-picked change. |
| |
| .Response |
| ---- |
| 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]] |
| === List Files |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/commits/link:#commit-id[\{commit-id\}]/files/' |
| -- |
| |
| Lists the files that were modified, added or deleted in a commit. |
| |
| .Request |
| ---- |
| GET /projects/work%2Fmy-project/commits/a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96/files/ HTTP/1.0 |
| ---- |
| |
| As result a map is returned that maps the link:rest-api-changes.html#file-id[file path] to a |
| link:rest-api-changes.html#file-info[FileInfo] entry. The entries in the map are |
| sorted by file path. |
| |
| .Response |
| ---- |
| 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]] |
| == Dashboard Endpoints |
| |
| [[list-dashboards]] |
| === List Dashboards |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/dashboards/' |
| -- |
| |
| List custom dashboards for a project. |
| |
| As result a list of link:#dashboard-info[DashboardInfo] entries is |
| returned. |
| |
| List all dashboards for the `work/my-project` project: |
| |
| .Request |
| ---- |
| GET /projects/work%2Fmy-project/dashboards/ HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| 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 all dashboards of the 'All-Projects' project |
| **** |
| get::/projects/All-Projects/dashboards/ |
| **** |
| |
| [[get-dashboard]] |
| === Get Dashboard |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/dashboards/link:#dashboard-id[\{dashboard-id\}]' |
| -- |
| |
| Retrieves a project dashboard. The dashboard can be defined on that |
| project or be inherited from a parent project. |
| |
| .Request |
| ---- |
| GET /projects/work%2Fmy-project/dashboards/main:closed HTTP/1.0 |
| ---- |
| |
| As response a link:#dashboard-info[DashboardInfo] entity is returned |
| that describes the dashboard. |
| |
| .Response |
| ---- |
| 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. |
| |
| .Request |
| ---- |
| GET /projects/work%2Fmy-project/dashboards/default HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| 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]] |
| === Create Dashboard |
| -- |
| 'PUT /projects/link:#project-name[\{project-name\}]/dashboards/link:#dashboard-id[\{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 link:#dashboard-input[DashboardInput] entity. |
| |
| .Request |
| ---- |
| 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 link:#dashboard-info[ |
| DashboardInfo] entity. |
| |
| .Response |
| ---- |
| 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]] |
| === Update Dashboard |
| -- |
| 'PUT /projects/link:#project-name[\{project-name\}]/dashboards/link:#dashboard-id[\{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 link:#dashboard-input[DashboardInput] entity. |
| |
| .Request |
| ---- |
| 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 |
| link:#dashboard-info[DashboardInfo] entity. |
| |
| .Response |
| ---- |
| 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 Dashboard |
| -- |
| 'DELETE /projects/link:#project-name[\{project-name\}]/dashboards/link:#dashboard-id[\{dashboard-id\}]' |
| -- |
| |
| Deletes a project dashboard. |
| |
| Currently only supported for the `default` dashboard. |
| |
| The request body does not need to include a link:#dashboard-input[ |
| DashboardInput] entity if no commit message is specified. |
| |
| Please note that some proxies prohibit request bodies for DELETE |
| requests. |
| |
| .Request |
| ---- |
| DELETE /projects/work%2Fmy-project/dashboards/default HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[label-endpoints]] |
| == Label Endpoints |
| |
| [[list-labels]] |
| === List Labels |
| -- |
| 'GET /projects/link:#project-name[\{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. |
| |
| .Request |
| ---- |
| GET /projects/All-Projects/labels/ HTTP/1.0 |
| ---- |
| |
| As result a list of link:#label-definition-info[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 |
| link:#list-with-inherited-labels[below]). The returned labels are sorted by |
| label name. |
| |
| .Response |
| ---- |
| 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 |
| } |
| ] |
| ---- |
| |
| [[list-with-inherited-labels]] |
| 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. |
| |
| .Request |
| ---- |
| GET /projects/My-Project/labels/?inherited HTTP/1.0 |
| ---- |
| |
| As result a list of link:#label-definition-info[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. |
| |
| .Response |
| ---- |
| 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 Label |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/labels/link:#label-name[\{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. |
| |
| .Request |
| ---- |
| GET /projects/All-Projects/labels/Code-Review HTTP/1.0 |
| ---- |
| |
| As response a link:#label-definition-info[LabelDefinitionInfo] entity is |
| returned that describes the label. |
| |
| .Response |
| ---- |
| 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]] |
| === Create Label |
| -- |
| 'PUT /projects/link:#project-name[\{project-name\}]/labels/link:#label-name[\{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 link:#set-label[Set Label]). |
| |
| .Request |
| ---- |
| 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 link:#label-definition-info[LabelDefinitionInfo] entity is |
| returned that describes the created label. |
| |
| .Response |
| ---- |
| 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]] |
| === Set Label |
| -- |
| 'PUT /projects/link:#project-name[\{project-name\}]/labels/link:#label-name[\{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. |
| |
| .Request |
| ---- |
| 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 link:#label-definition-info[LabelDefinitionInfo] entity is |
| returned that describes the updated label. |
| |
| .Response |
| ---- |
| 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 Label |
| -- |
| 'DELETE /projects/link:#project-name[\{project-name\}]/labels/link:#label-name[\{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 link:#delete-label-input[ |
| DeleteLabelInput] entity if no commit message is specified. |
| |
| .Request |
| ---- |
| 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`". |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[batch-update-labels]] |
| === Batch Update Labels |
| -- |
| 'POST /projects/link:#project-name[\{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 |
| link:#batch-label-input[BatchLabelInput] entity. |
| |
| The updates are processed in the following order: |
| |
| 1. label deletions |
| 2. label creations |
| 3. label updates |
| |
| .Request |
| ---- |
| 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`". |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| ---- |
| |
| [[submit-requirement-endpoints]] |
| == Submit Requirement Endpoints |
| |
| [[create-submit-requirement]] |
| === Create Submit Requirement |
| |
| -- |
| 'PUT /projects/link:#project-name[\{project-name\}]/submit_requirements/link:#submit-requirement-name[\{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 link:#update-submit-requirement[Update Submit Requirement]). |
| |
| The submit requirement data must be provided in the request body as |
| link:#submit-requirement-input[SubmitRequirementInput]. |
| |
| .Request |
| ---- |
| 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 link:#submit-requirement-info[SubmitRequirementInfo] entity is |
| returned that describes the created submit requirement. |
| |
| .Response |
| ---- |
| 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]] |
| === Update Submit Requirement |
| |
| -- |
| 'PUT /projects/link:#project-name[\{project-name\}]/submit_requirements/link:#submit-requirement-name[\{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. |
| |
| .Request |
| ---- |
| 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 link:#submit-requirement-info[SubmitRequirementInfo] entity is |
| returned that describes the created submit requirement. |
| |
| .Response |
| ---- |
| 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 Submit Requirement |
| -- |
| 'GET /projects/link:#project-name[\{project-name\}]/submit_requirements/link:#submit-requirement-name[\{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. |
| |
| .Request |
| ---- |
| GET /projects/All-Projects/submit-requirement/Code-Review HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| 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]] |
| === List Submit Requirements |
| -- |
| 'GET /projects/link:#project-name[\{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 link:#submit-requirement-info[SubmitRequirementInfo] |
| entities is returned. |
| |
| .Request |
| ---- |
| GET /projects/All-Projects/submit-requirements HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| 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 Submit Requirement |
| -- |
| 'DELETE /projects/link:#project-name[\{project-name\}]/submit_requirements/link:#submit-requirement-name[\{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. |
| |
| .Request |
| ---- |
| 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`". |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[ids]] |
| == IDs |
| |
| [[branch-id]] |
| === \{branch-id\} |
| The name of a branch or `HEAD`. The prefix `refs/heads/` can be |
| omitted. |
| |
| [[commit-id]] |
| === \{commit-id\} |
| Commit ID. |
| |
| [[tag-id]] |
| === \{tag-id\} |
| The name of a tag. The prefix `refs/tags/` can be omitted. |
| |
| [[dashboard-id]] |
| === \{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]] |
| === \{label-name\} |
| The name of a review label. |
| |
| [[submit-requirement-name]] |
| === \{submit-requirement-name\} |
| The name of a submit requirement. |
| |
| |
| [[project-name]] |
| === \{project-name\} |
| The name of the project. |
| |
| If the name ends with `.git`, the suffix will be automatically removed. |
| |
| |
| [[json-entities]] |
| == JSON Entities |
| |
| [[access-check-info]] |
| === AccessCheckInfo |
| |
| The `AccessCheckInfo` entity is the result of an access check. |
| |
| [options="header",cols="1,^1,5"] |
| |========================================= |
| |Field Name ||Description |
| |`status` ||The HTTP status code for the access. |
| 200 means success and 403 means denied. |
| |`message` |optional|A clarifying message if `status` is not 200. |
| |`debug_logs` |optional| |
| Debug logs that may help to understand why a permission is denied or allowed. |
| |========================================= |
| |
| [[auto_closeable_changes_check_input]] |
| === AutoCloseableChangesCheckInput |
| The `AutoCloseableChangesCheckInput` entity contains options for running |
| the link:#auto-closeable-changes-check[AutoCloseableChangesCheck]. |
| |
| [options="header",cols="1,^2,4"] |
| |============================= |
| |Field Name ||Description |
| |`fix` |optional| |
| Whether auto-closeable changes should be closed automatically. |
| |`branch` || |
| The branch for which the link:#auto-closeable-changes-check[ |
| AutoCloseableChangesCheck] should be performed. The 'refs/heads/' |
| prefix for the branch name can be omitted. |
| |`skip_commits` |optional| |
| Number of commits that should be skipped when walking the commits of |
| the branch. |
| |`max_commits` |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. |
| |============================= |
| |
| [[auto_closeable_changes_check_result]] |
| === AutoCloseableChangesCheckResult |
| The `AutoCloseableChangesCheckResult` entity contains the results of |
| running the link:#auto-closeable-changes-check[AutoCloseableChangesCheck] |
| on a project. |
| |
| [options="header",cols="1,6"] |
| |==================================== |
| |Field Name |Description |
| |`auto_closeable_changes`| |
| Changes that can be auto-closed as list of |
| link:rest-api-changes.html#change-info[ChangeInfo] entities. For each |
| returned link:rest-api-changes.html#change-info[ChangeInfo] entity the |
| `problems` field is populated that includes details about the detected |
| issues. If `fix` in the link:#auto_closeable_changes_check_input[ |
| AutoCloseableChangesCheckInput] was set to `true`, `status` and |
| `outcome` in link:rest-api-changes.html#problem-info[ProblemInfo] are |
| populated. If the status says `FIXED` Gerrit was able to auto-close the |
| change now. |
| |==================================== |
| |
| [[ban-input]] |
| === BanInput |
| The `BanInput` entity contains information for banning commits in a |
| project. |
| |
| [options="header",cols="1,^2,4"] |
| |======================= |
| |Field Name||Description |
| |`commits` ||List of commits to be banned. |
| |`reason` |optional|Reason for banning the commits. |
| |======================= |
| |
| [[ban-result-info]] |
| === BanResultInfo |
| The `BanResultInfo` entity describes the result of banning commits. |
| |
| [options="header",cols="1,^2,4"] |
| |============================= |
| |Field Name ||Description |
| |`newly_banned` |optional|List of newly banned commits. |
| |`already_banned`|optional|List of commits that were already banned. |
| |`ignored` |optional|List of object IDs that were ignored. |
| |============================= |
| |
| [[branch-info]] |
| === BranchInfo |
| The `BranchInfo` entity contains information about a branch. |
| |
| [options="header",cols="1,^2,4"] |
| |========================= |
| |Field Name ||Description |
| |`ref` ||The ref of the branch. |
| |`revision` ||The revision to which the branch points. |
| |`can_delete`|not set if `false`| |
| Whether the calling user can delete this branch. |
| |`web_links` |optional| |
| Links to the branch in external sites as a list of |
| link:rest-api-changes.html#web-link-info[WebLinkInfo] entries. |
| |========================= |
| |
| [[branch-input]] |
| === BranchInput |
| The `BranchInput` entity contains information for the creation of |
| a new branch. |
| |
| [options="header",cols="1,^2,4"] |
| |======================= |
| |Field Name ||Description |
| |`ref` |optional| |
| The name of the branch. The prefix `refs/heads/` can be |
| omitted. + |
| If set, must match the branch ID in the URL. |
| |`revision` |optional| |
| The base revision of the new branch. + |
| If not set, `HEAD` will be used as base revision. |
| |`validation_options`|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. |
| |======================= |
| |
| [[check-project-input]] |
| === CheckProjectInput |
| The `CheckProjectInput` entity contains information about which |
| consistency checks should be run on a project. |
| |
| [options="header",cols="1,^2,4"] |
| |=========================================== |
| |Field Name ||Description |
| |`auto_closeable_changes_check`|optional| |
| Parameters for the link:#auto-closeable-changes-check[ |
| AutoCloseableChangesCheck] as |
| link:rest-api-changes.html#auto_closeable_changes_check_input[ |
| AutoCloseableChangesCheckInput] entity. |
| |=========================================== |
| |
| [[check-project-result-info]] |
| === CheckProjectResultInfo |
| The `CheckProjectResultInfo` entity contains results for consistency |
| checks that have been run on a project. |
| |
| [options="header",cols="1,^2,4"] |
| |================================================== |
| |Field Name ||Description |
| |`auto_closeable_changes_check_result`|optional| |
| Results for the link:#auto-closeable-changes-check[ |
| AutoCloseableChangesCheck] as |
| link:rest-api-changes.html#auto_closeable_changes_check_result[ |
| AutoCloseableChangesCheckResult] entity. |
| |================================================== |
| |
| [[commentlink-info]] |
| === CommentLinkInfo |
| The `CommentLinkInfo` entity describes a |
| link:config-gerrit.html#commentlink[commentlink]. |
| |
| [options="header",cols="1,^2,4"] |
| |================================================== |
| |Field Name | |Description |
| |`match` | |A JavaScript regular expression to match |
| positions to be replaced with a hyperlink, as documented in |
| link:config-gerrit.html#commentlink.name.match[commentlink.name.match]. |
| |`link` | |The URL to direct the user to whenever the |
| regular expression is matched, as documented in |
| link:config-gerrit.html#commentlink.name.link[commentlink.name.link]. |
| |`prefix` |optional|Text inserted before the link. |
| |`suffix` |optional|Text inserted after the link. |
| |`text` |optional|Text of the link. |
| |`enabled` |optional|Whether the commentlink is enabled, as documented |
| in link:config-gerrit.html#commentlink.name.enabled[ |
| commentlink.name.enabled]. If not set the commentlink is enabled. |
| |================================================== |
| |
| [[commentlink-input]] |
| === CommentLinkInput |
| The `CommentLinkInput` entity describes the input for a |
| link:config-gerrit.html#commentlink[commentlink]. |
| |
| [options="header",cols="1,^2,4"] |
| |================================================== |
| |Field Name | |Description |
| |`match` | |A JavaScript regular expression to match |
| positions to be replaced with a hyperlink, as documented in |
| link:config-gerrit.html#commentlink.name.match[commentlink.name.match]. |
| |`link` | |The URL to direct the user to whenever the |
| regular expression is matched, as documented in |
| link:config-gerrit.html#commentlink.name.link[commentlink.name.link]. |
| |`prefix` |optional|Text inserted before the link. |
| |`suffix` |optional|Text inserted after the link. |
| |`text` |optional|Text of the link. |
| |`enabled` |optional|Whether the commentlink is enabled, as documented |
| in link:config-gerrit.html#commentlink.name.enabled[ |
| commentlink.name.enabled]. If not set the commentlink is enabled. |
| |================================================== |
| |
| [[config-info]] |
| === ConfigInfo |
| The `ConfigInfo` entity contains information about the effective project |
| configuration. |
| |
| [options="header",cols="1,^2,4"] |
| |======================================================= |
| |Field Name ||Description |
| |`description` |optional| |
| The description of the project. |
| |`use_contributor_agreements` |optional| |
| link:#inherited-boolean-info[InheritedBooleanInfo] that tells whether |
| authors must complete a contributor agreement on the site before |
| pushing any commits or changes to this project. |
| |`use_content_merge` |optional| |
| link:#inherited-boolean-info[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. |
| |`use_signed_off_by` |optional| |
| link:#inherited-boolean-info[InheritedBooleanInfo] that tells whether |
| each change must contain a Signed-off-by line from either the author or |
| the uploader in the commit message. |
| |`create_new_change_for_all_not_in_target` |optional| |
| link:#inherited-boolean-info[InheritedBooleanInfo] that tells whether |
| a new change is created for every commit not in target branch. |
| |`require_change_id` |optional| |
| link:#inherited-boolean-info[InheritedBooleanInfo] that tells whether a |
| valid link:user-changeid.html[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. |
| |`enable_signed_push`|optional, not set if signed push is disabled| |
| link:#inherited-boolean-info[InheritedBooleanInfo] that tells whether |
| signed push validation is enabled on the project. |
| |`require_signed_push`|optional, not set if signed push is disabled| |
| link:#inherited-boolean-info[InheritedBooleanInfo] that tells whether |
| signed push validation is required on the project. |
| |`reject_implicit_merges`|optional| |
| link:#inherited-boolean-info[InheritedBooleanInfo] that tells whether |
| implicit merges should be rejected on changes pushed to the project. |
| |`private_by_default` || |
| link:#inherited-boolean-info[InheritedBooleanInfo] that tells whether |
| all new changes are set as private by default. |
| |`work_in_progress_by_default`|| |
| link:#inherited-boolean-info[InheritedBooleanInfo] that tells whether |
| all new changes are set as work-in-progress by default. |
| |`max_object_size_limit` || |
| The link:config-gerrit.html#receive.maxObjectSizeLimit[max object size |
| limit] of this project as a link:#max-object-size-limit-info[ |
| MaxObjectSizeLimitInfo] entity. |
| |`default_submit_type` || |
| link:#submit-type-info[SubmitTypeInfo] that describes the default submit type of |
| the project, when not overridden at the change level. |
| |`submit_type` || |
| Deprecated; equivalent to link:#submit-type-info[`value`] in |
| `default_submit_type`. |
| |`match_author_to_committer_date` |optional| |
| link:#inherited-boolean-info[InheritedBooleanInfo] that indicates whether |
| a change's author date will be changed to match its submitter date upon submit. |
| |`state` |optional| |
| The state of the project, can be `ACTIVE`, `READ_ONLY` or `HIDDEN`. + |
| Not set if the project state is `ACTIVE`. |
| |`commentlinks` || |
| Map with the comment link configurations of the project. The name of |
| the comment link configuration is mapped to a link:#commentlink-info[ |
| CommentlinkInfo] entity. |
| |`plugin_config` |optional| |
| Plugin configuration as map which maps the plugin name to a map of |
| parameter names to link:#config-parameter-info[ConfigParameterInfo] |
| entities. Only filled for users who have read access to `refs/meta/config`. |
| |`actions` |optional| |
| Actions the caller might be able to perform on this project. The |
| information is a map of view names to |
| |`reject_empty_commit` |optional| |
| link:#inherited-boolean-info[InheritedBooleanInfo] that tells whether |
| empty commits should be rejected when a change is merged. |
| link:rest-api-changes.html#action-info[ActionInfo] entities. |
| |`skip_adding_author_and_committer_as_reviewers` |optional| |
| Whether to skip adding the Git commit author and committer as reviewers for a new change. |
| |======================================================= |
| |
| [[config-input]] |
| === ConfigInput |
| The `ConfigInput` entity describes a new project configuration. |
| |
| [options="header",cols="1,^2,4"] |
| |====================================================== |
| |Field Name ||Description |
| |`description` |optional| |
| The new description of the project. + |
| If not set, the description is removed. |
| |`use_contributor_agreements` |optional| |
| Whether authors must complete a contributor agreement on the site |
| before pushing any commits or changes to this project. + |
| Can be `TRUE`, `FALSE` or `INHERIT`. + |
| If not set, this setting is not updated. |
| |`use_content_merge` |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. + |
| Can be `TRUE`, `FALSE` or `INHERIT`. + |
| If not set, this setting is not updated. |
| |`use_signed_off_by` |optional| |
| Whether each change must contain a Signed-off-by line from either the |
| author or the uploader in the commit message. + |
| Can be `TRUE`, `FALSE` or `INHERIT`. + |
| If not set, this setting is not updated. |
| |`create_new_change_for_all_not_in_target` |optional| |
| Whether a new change will be created for every commit not in target |
| branch. + |
| Can be `TRUE`, `FALSE` or `INHERIT`. + |
| If not set, this setting is not updated. |
| |`require_change_id` |optional| |
| Whether a valid link:user-changeid.html[Change-Id] footer in any commit |
| uploaded for review is required. This does not apply to commits pushed |
| directly to a branch or tag. + |
| Can be `TRUE`, `FALSE` or `INHERIT`. + |
| If not set, this setting is not updated. |
| This property is deprecated and will be removed in |
| a future release. |
| |`reject_implicit_merges` |optional| |
| Whether a check for implicit merges will be performed when changes |
| are pushed for review. + |
| Can be `TRUE`, `FALSE` or `INHERIT`. + |
| If not set, this setting is not updated. |
| |`max_object_size_limit` |optional| |
| The link:config-gerrit.html#receive.maxObjectSizeLimit[max object size |
| limit] of this project as a link:#max-object-size-limit-info[ |
| MaxObjectSizeLimitInfo] entity. + |
| If set to `0`, the max object size limit is removed. + |
| If not set, this setting is not updated. |
| |`submit_type` |optional| |
| The default submit type of the project, can be `MERGE_IF_NECESSARY`, |
| `FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `REBASE_ALWAYS`, `MERGE_ALWAYS` or |
| `CHERRY_PICK`. + |
| If not set, the submit type is not updated. |
| |`state` |optional| |
| The state of the project, can be `ACTIVE`, `READ_ONLY` or `HIDDEN`. + |
| Not set if the project state is `ACTIVE`. + |
| If not set, the project state is not updated. |
| |`plugin_config_values` |optional| |
| Plugin configuration values as map which maps the plugin name to a map |
| of parameter names to values. |
| |`reject_empty_commit` |optional| |
| Whether empty commits should be rejected when a change is merged. |
| Can be `TRUE`, `FALSE` or `INHERIT`. + |
| If not set, this setting is not updated. |
| |commentlinks |optional| |
| Map of commentlink names to link:#commentlink-input[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. |
| |====================================================== |
| |
| [[config-parameter-info]] |
| === ConfigParameterInfo |
| The `ConfigParameterInfo` entity describes a project configuration |
| parameter. |
| |
| [options="header",cols="1,^2,4"] |
| |=============================== |
| |Field Name ||Description |
| |`display_name` |optional| |
| The display name of the configuration parameter. |
| |`description` |optional| |
| The description of the configuration parameter. |
| |`warning` |optional| |
| Warning message for the configuration parameter. |
| |`type` || |
| The type of the configuration parameter. Can be `STRING`, `INT`, |
| `LONG`, `BOOLEAN`, `LIST` or `ARRAY`. |
| |`value` |optional| |
| The value of the configuration parameter as string. If the parameter |
| is inheritable this is the effective value which is deduced from |
| `configured_value` and `inherited_value`. |
| |`values` |optional| |
| The list of values. Only set if the `type` is `ARRAY`. |
| |`editable` |`false` if not set| |
| Whether the value is editable. |
| |`permitted_values`|optional| |
| The list of permitted values. Only set if the `type` is `LIST`. |
| |`inheritable` |`false` if not set| |
| Whether the configuration parameter can be inherited. |
| |`configured_value`|optional| |
| The value of the configuration parameter that is configured on this |
| project, only set if `inheritable` is true. |
| |`inherited_value` |optional| |
| The inherited value of the configuration parameter, only set if |
| `inheritable` is true. |
| |=============================== |
| |
| [[dashboard-info]] |
| === DashboardInfo |
| The `DashboardInfo` entity contains information about a project |
| dashboard. |
| |
| [options="header",cols="1,^2,4"] |
| |=============================== |
| |Field Name ||Description |
| |`id` || |
| The ID of the dashboard. The ID has the format '<ref>:<path>', |
| where ref and path are URL encoded. |
| |`project` || |
| The name of the project for which this dashboard is returned. |
| |`defining_project`|| |
| The name of the project in which this dashboard is defined. |
| This is different from `project` if the dashboard is inherited from a |
| parent project. |
| |`ref` || |
| The name of the ref in which the dashboard is defined, without the |
| `refs/meta/dashboards/` prefix, which is common for all dashboard refs. |
| |`path` || |
| The path of the file in which the dashboard is defined. |
| |`description` |optional|The description of the dashboard. |
| |`foreach` |optional| |
| Subquery that applies to all sections in the dashboard. + |
| Tokens such as `${project}` are not resolved. |
| |`url` || |
| The URL under which the dashboard can be opened in the Gerrit Web UI. + |
| The URL is relative to the canonical web URL. + |
| Tokens in the queries such as `${project}` are resolved. |
| |`is_default` |not set if `false`| |
| Whether this is the default dashboard of the project. |
| |`title` |optional|The title of the dashboard. |
| |`sections` || |
| The list of link:#dashboard-section-info[sections] in the dashboard. |
| |=============================== |
| |
| [[dashboard-input]] |
| === DashboardInput |
| The `DashboardInput` entity contains information to create/update a |
| project dashboard. |
| |
| [options="header",cols="1,^2,4"] |
| |============================= |
| |Field Name ||Description |
| |`id` |optional| |
| URL encoded ID of a dashboard to which this dashboard should link to. |
| |`commit_message`|optional| |
| Message that should be used to commit the change of the dashboard. |
| |============================= |
| |
| [[dashboard-section-info]] |
| === DashboardSectionInfo |
| The `DashboardSectionInfo` entity contains information about a section |
| in a dashboard. |
| |
| [options="header",cols="1,6"] |
| |=========================== |
| |Field Name |Description |
| |`name` |The title of the section. |
| |`query` |The query of the section. + |
| Tokens such as `${project}` are not resolved. |
| |=========================== |
| |
| [[delete-label-input]] |
| === DeleteLabelInput |
| The `DeleteLabelInput` entity contains information for deleting a label |
| definition in a project. |
| |
| [options="header",cols="1,^2,4"] |
| |============================= |
| |Field Name ||Description |
| |`commit_message`|optional| |
| Message that should be used to commit the deletion of the label in the |
| `project.config` file to the `refs/meta/config` branch. |
| |============================= |
| |
| [[delete-branches-input]] |
| === DeleteBranchesInput |
| The `DeleteBranchesInput` entity contains information about branches that should |
| be deleted. |
| |
| [options="header",width="50%",cols="1,6"] |
| |========================== |
| |Field Name |Description |
| |`branches` |A list of branch names that identify the branches that should be |
| deleted. |
| |========================== |
| |
| [[delete-tags-input]] |
| === DeleteTagsInput |
| The `DeleteTagsInput` entity contains information about tags that should |
| be deleted. |
| |
| [options="header",width="50%",cols="1,6"] |
| |========================== |
| |Field Name |Description |
| |`tags` |A list of tag names that identify the tags that should be |
| deleted. |
| |========================== |
| |
| [[gc-input]] |
| === GCInput |
| The `GCInput` entity contains information to run the Git garbage |
| collection. |
| |
| [options="header",cols="1,^2,4"] |
| |============================= |
| |Field Name ||Description |
| |`show_progress` |`false` if not set| |
| Whether progress information should be shown. |
| |`aggressive` |`false` if not set| |
| Whether an aggressive garbage collection should be done. |
| |`async` |`false` if not set| |
| Whether the garbage collection should run asynchronously. |
| |============================= |
| |
| [[head-input]] |
| === HeadInput |
| The `HeadInput` entity contains information for setting `HEAD` for a |
| project. |
| |
| [options="header",cols="1,6"] |
| |============================ |
| |Field Name |Description |
| |`ref` | |
| The ref to which `HEAD` should be set, the `refs/heads` prefix can be |
| omitted. |
| |============================ |
| |
| [[index-project-input]] |
| === IndexProjectInput |
| The `IndexProjectInput` contains parameters for indexing a project. |
| |
| [options="header",cols="1,^2,4"] |
| |================================ |
| |Field Name ||Description |
| |`index_children` || |
| If children should be indexed recursively. |
| |`async` || |
| If projects should be indexed asynchronously. |
| |================================ |
| |
| [[inherited-boolean-info]] |
| === InheritedBooleanInfo |
| A boolean value that can also be inherited. |
| |
| [options="header",cols="1,^2,4"] |
| |================================ |
| |Field Name ||Description |
| |`value` || |
| The effective boolean value. |
| |`configured_value` || |
| The configured value, can be `TRUE`, `FALSE` or `INHERIT`. |
| |`inherited_value` |optional| |
| The boolean value inherited from the parent. + |
| Not set if there is no parent. |
| |================================ |
| |
| [[label-definition-info]] |
| === LabelDefinitionInfo |
| The `LabelDefinitionInfo` entity describes a link:config-labels.html[ |
| review label]. |
| |
| [options="header",cols="1,^2,4"] |
| |============================= |
| |Field Name ||Description |
| |`name` || |
| The link:config-labels.html#label_name[name] of the label. |
| |`description` |optional| |
| The description of the label. |
| |`project_name` || |
| The name of the project in which this label is defined. |
| |`function` || |
| The link:config-labels.html#label_function[function] of the label (can be |
| `MaxWithBlock`, `AnyWithBlock`, `MaxNoBlock`, `NoBlock`, `NoOp` and `PatchSetLock`. |
| |`values` || |
| The link:config-labels.html#label_value[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". |
| |`default_value` || |
| The link:config-labels.html#label_defaultValue[default value] of the label (as |
| integer). |
| |`branches` |optional| |
| A list of link:config-labels.html#label_branch[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. |
| |`can_override` |`false` if not set| |
| Whether this label can be link:config-labels.html#label_canOverride[overridden] |
| by child projects. |
| |`copy_condition`|optional| |
| See link:config-labels.html#label_copyCondition[copyCondition]. |
| |`allow_post_submit`|`false` if not set| |
| Whether link:config-labels.html#label_allowPostSubmit[allowPostSubmit] is set |
| on the label. |
| |`ignore_self_approval`|`false` if not set| |
| Whether link:config-labels.html#label_ignoreSelfApproval[ignoreSelfApproval] is |
| set on the label. |
| |============================= |
| |
| [[label-definition-input]] |
| === LabelDefinitionInput |
| The `LabelDefinitionInput` entity describes a link:config-labels.html[ |
| review label]. |
| |
| [options="header",cols="1,^2,4"] |
| |============================= |
| |Field Name ||Description |
| |`commit_message`|optional| |
| Message that should be used to commit the change of the label in the |
| `project.config` file to the `refs/meta/config` branch.+ |
| Must not be set if this `LabelDefinitionInput` entity is contained in a |
| link:#batch-label-input[BatchLabelInput] entity. |
| |`name` |optional| |
| The new link:config-labels.html#label_name[name] of the label.+ |
| For label creation the name is required if this `LabelDefinitionInput` entity |
| is contained in a link:#batch-label-input[BatchLabelInput] |
| entity. |
| |`description` |optional| |
| The new description for the label. |
| |`function` |optional| |
| The new link:config-labels.html#label_function[function] of the label (can be |
| `MaxWithBlock`, `AnyWithBlock`, `MaxNoBlock`, `NoBlock`, `NoOp` and `PatchSetLock`. |
| |`values` |optional| |
| The new link:config-labels.html#label_value[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". |
| |`default_value` |optional| |
| The new link:config-labels.html#label_defaultValue[default value] of the label |
| (as integer). |
| |`branches` |optional| |
| The new branches for which the label applies as a list of |
| link:config-labels.html#label_branch[branches]. A branch can be a ref, a ref |
| pattern or a regular expression. If not set, the label applies for all |
| branches. |
| |`can_override` |optional| |
| Whether this label can be link:config-labels.html#label_canOverride[overridden] |
| by child projects. |
| |`copy_condition`|optional| |
| See link:config-labels.html#label_copyCondition[copyCondition]. |
| |`unset_copy_condition`|optional| |
| If true, clears the value stored in `copy_condition`. |
| |`allow_post_submit`|optional| |
| Whether link:config-labels.html#label_allowPostSubmit[allowPostSubmit] is set |
| on the label. |
| |`ignore_self_approval`|optional| |
| Whether link:config-labels.html#label_ignoreSelfApproval[ignoreSelfApproval] is |
| set on the label. |
| |============================= |
| |
| [[label-type-info]] |
| === LabelTypeInfo |
| The `LabelTypeInfo` entity contains metadata about the labels that a |
| project has. |
| |
| [options="header",cols="1,^2,4"] |
| |================================ |
| |Field Name ||Description |
| |`values` ||Map of the available values to their description. |
| |`default_value` ||The default value of this label. |
| |================================ |
| |
| [[max-object-size-limit-info]] |
| === MaxObjectSizeLimitInfo |
| The `MaxObjectSizeLimitInfo` entity contains information about the |
| link:config-gerrit.html#receive.maxObjectSizeLimit[max object size |
| limit] of a project. |
| |
| [options="header",cols="1,^2,4"] |
| |=============================== |
| |Field Name ||Description |
| |`value` |optional| |
| The effective value in bytes of the max object size limit. + |
| Not set if there is no limit for the object size. |
| |`configured_value`|optional| |
| The max object size limit that is configured on the project as a |
| formatted string. + |
| Not set if there is no limit for the object size configured on project |
| level. |
| |`summary` |optional| |
| A string describing whether the value was inherited or overridden from |
| the parent project or global config. + |
| Not set if not inherited or overridden. |
| |=============================== |
| |
| [[batch-label-input]] |
| === BatchLabelInput |
| The `BatchLabelInput` entity contains information for batch updating label |
| definitions in a project. |
| |
| [options="header",cols="1,^2,4"] |
| |============================= |
| |Field Name ||Description |
| |`commit_message`|optional| |
| Message that should be used to commit the label updates in the |
| `project.config` file to the `refs/meta/config` branch. |
| |`delete` |optional| |
| List of labels that should be deleted. |
| |`create` |optional| |
| List of link:#label-definition-input[LabelDefinitionInput] entities that |
| describe labels that should be created. |
| |`update` |optional| |
| Map of label names to link:#label-definition-input[LabelDefinitionInput] |
| entities that describe the updates that should be done for the labels. |
| |============================= |
| |
| [[project-access-input]] |
| === ProjectAccessInput |
| The `ProjectAccessInput` describes changes that should be applied to a project |
| access config. |
| |
| [options="header",cols="1,^2,4"] |
| |============================= |
| |Field Name | |Description |
| |`remove` |optional| |
| A list of deductions to be applied to the project access as |
| link:rest-api-access.html#project-access-info[ProjectAccessInfo] entities. |
| |`add` |optional| |
| A list of additions to be applied to the project access as |
| link:rest-api-access.html#project-access-info[ProjectAccessInfo] entities. |
| |`message` |optional| |
| A commit message for this change. |
| |`parent` |optional| |
| A new parent for the project to inherit from. Changing the parent project |
| requires administrative privileges. |
| |============================= |
| |
| [[project-description-input]] |
| === ProjectDescriptionInput |
| The `ProjectDescriptionInput` entity contains information for setting a |
| project description. |
| |
| [options="header",cols="1,^2,4"] |
| |============================= |
| |Field Name ||Description |
| |`description` |optional|The project description. + |
| The project description will be deleted if not set. |
| |`commit_message`|optional| |
| Message that should be used to commit the change of the project |
| description in the `project.config` file to the `refs/meta/config` |
| branch. |
| |============================= |
| |
| [[project-info]] |
| === ProjectInfo |
| The `ProjectInfo` entity contains information about a project. |
| |
| [options="header",cols="1,^2,4"] |
| |============================= |
| |Field Name ||Description |
| |`id` ||The URL encoded project name. |
| |`name` | |
| not set if returned in a map where the project name is used as map key| |
| The name of the project. |
| |`parent` |optional| |
| The name of the parent project. + |
| `?-<n>` if the parent project is not visible (`<n>` is a number which |
| is increased for each non-visible project). |
| |`description` |optional|The description of the project. |
| |`state` |optional|`ACTIVE`, `READ_ONLY` or `HIDDEN`. |
| |`branches` |optional|Map of branch names to HEAD revisions. |
| |`labels` |optional| |
| Map of label names to |
| link:#label-type-info[LabelTypeInfo] entries. |
| This field is filled for link:#create-project[Create Project] and |
| link:#get-project[Get Project] calls. |
| |`web_links` |optional| |
| Links to the project in external sites as a list of |
| link:rest-api-changes.html#web-link-info[WebLinkInfo] entries. |
| |`_more_projects`|optional, not set if `false`| |
| Whether the query would deliver more results if not limited. + |
| Only set on the last project that is returned. |
| |============================= |
| |
| [[project-input]] |
| === ProjectInput |
| The `ProjectInput` entity contains information for the creation of |
| a new project. |
| |
| [options="header",cols="1,^2,4"] |
| |========================================= |
| |Field Name ||Description |
| |`name` |optional| |
| The name of the project (not encoded). + |
| If set, must match the project name in the URL. + |
| If name ends with `.git` the suffix will be automatically removed. |
| |`parent` |optional| |
| The name of the parent project. + |
| If not set, the `All-Projects` project will be the parent project. |
| |`description` |optional|The description of the project. |
| |`permissions_only` |`false` if not set| |
| Whether a permission-only project should be created. |
| |`create_empty_commit` |`false` if not set| |
| Whether an empty initial commit should be created. |
| |`submit_type` |optional| |
| The submit type that should be set for the project |
| (`MERGE_IF_NECESSARY`, `REBASE_IF_NECESSARY`, `REBASE_ALWAYS`, |
| `FAST_FORWARD_ONLY`, `MERGE_ALWAYS`, `CHERRY_PICK`). + |
| If not set, `MERGE_IF_NECESSARY` is set as submit type unless |
| link:config-gerrit.html#repository.name.defaultSubmitType[ |
| repository.<name>.defaultSubmitType] is set to a different value. |
| |`branches` |optional| |
| A list of branches that should be initially created. + |
| For the branch names the `refs/heads/` prefix can be omitted. + |
| The first entry of the list will be the |
| link:project-configuration.html#default-branch[default branch]. + |
| If the list is empty, link:config-gerrit.html#gerrit.defaultBranch[host-level default] |
| is used. + |
| Branches in the Gerrit internal ref space are not allowed, such as |
| refs/groups/, refs/changes/, etc... |
| |`owners` |optional| |
| A list of groups that should be assigned as project owner. + |
| Each group in the list must be specified as |
| link:rest-api-groups.html#group-id[group-id]. + |
| If not set, the link:config-gerrit.html#repository.name.ownerGroup[ |
| groups that are configured as default owners] are set as project |
| owners. |
| |`use_contributor_agreements` |`INHERIT` if not set| |
| Whether contributor agreements should be used for the project (`TRUE`, |
| `FALSE`, `INHERIT`). |
| |`use_signed_off_by` |`INHERIT` if not set| |
| Whether the usage of 'Signed-Off-By' footers is required for the |
| project (`TRUE`, `FALSE`, `INHERIT`). |
| |`create_new_change_for_all_not_in_target` |`INHERIT` if not set| |
| Whether a new change is created for every commit not in target branch |
| for the project (`TRUE`, `FALSE`, `INHERIT`). |
| |`use_content_merge` |`INHERIT` if not set| |
| Whether content merge should be enabled for the project (`TRUE`, |
| `FALSE`, `INHERIT`). + |
| `FALSE`, if the `submit_type` is `FAST_FORWARD_ONLY`. |
| |`require_change_id` |`INHERIT` if not set| |
| Whether the usage of Change-Ids is required for the project (`TRUE`, |
| `FALSE`, `INHERIT`). |
| This property is deprecated and will be removed in |
| a future release. |
| |`enable_signed_push` |`INHERIT` if not set| |
| Whether signed push validation is enabled on the project (`TRUE`, |
| `FALSE`, `INHERIT`). |
| |`require_signed_push` |`INHERIT` if not set| |
| Whether signed push validation is required on the project (`TRUE`, |
| `FALSE`, `INHERIT`). |
| |`max_object_size_limit` |optional| |
| Max allowed Git object size for this project. |
| Common unit suffixes of 'k', 'm', or 'g' are supported. |
| |`plugin_config_values` |optional| |
| Plugin configuration values as map which maps the plugin name to a map |
| of parameter names to values. |
| |`reject_empty_commit` |optional| |
| Whether empty commits should be rejected when a change is merged |
| (`TRUE`, `FALSE`, `INHERIT`). |
| |========================================= |
| |
| [[project-parent-input]] |
| === ProjectParentInput |
| The `ProjectParentInput` entity contains information for setting a |
| project parent. |
| |
| [options="header",cols="1,^2,4"] |
| |============================= |
| |Field Name ||Description |
| |`parent` ||The name of the parent project. |
| |`commit_message`|optional| |
| Message that should be used to commit the change of the project parent |
| in the `project.config` file to the `refs/meta/config` branch. |
| |============================= |
| |
| [[reflog-entry-info]] |
| === ReflogEntryInfo |
| The `ReflogEntryInfo` entity describes an entry in a reflog. |
| |
| [options="header",cols="1,6"] |
| |============================ |
| |Field Name |Description |
| |`old_id` |The old commit ID. |
| |`new_id` |The new commit ID. |
| |`who` | |
| The user performing the change as a |
| link:rest-api-changes.html#git-person-info[GitPersonInfo] entity. |
| |`comment` |Comment of the reflog entry. |
| |============================ |
| |
| [[repository-statistics-info]] |
| === RepositoryStatisticsInfo |
| The `RepositoryStatisticsInfo` entity contains information about |
| statistics of a Git repository. |
| |
| [options="header",cols="1,6"] |
| |====================================== |
| |Field Name |Description |
| |`number_of_loose_objects` |Number of loose objects. |
| |`number_of_loose_refs` |Number of loose refs. |
| |`number_of_pack_files` |Number of pack files. |
| |`number_of_packed_objects`|Number of packed objects. |
| |`number_of_packed_refs` |Number of packed refs. |
| |`size_of_loose_objects` |Size of loose objects in bytes. |
| |`size_of_packed_objects` |Size of packed objects in bytes. |
| |====================================== |
| |
| [[submit-requirement-info]] |
| === SubmitRequirementInfo |
| The `SubmitRequirementInfo` entity describes a submit requirement. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`name`|| |
| The submit requirement name. |
| |`description`|optional| |
| Description of the submit requirement. |
| |`applicability_expression`|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. |
| |`submittability_expression`|| |
| 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. |
| |`override_expression`|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. |
| |`allow_override_in_child_projects`|| |
| Whether this submit requirement can be overridden in child projects. |
| |=========================== |
| |
| [[submit-requirement-input]] |
| === SubmitRequirementInput |
| The `SubmitRequirementInput` entity describes a submit requirement. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`name`|| |
| The submit requirement name. |
| |`description`|optional| |
| Description of the submit requirement. |
| |`applicability_expression`|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. |
| |`submittability_expression`|| |
| 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. |
| |`override_expression`|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. |
| |`allow_override_in_child_projects`|optional| |
| Whether this submit requirement can be overridden in child projects. Default is |
| `false`. |
| |=========================== |
| |
| [[submit-type-info]] |
| === SubmitTypeInfo |
| Information about the link:config-project-config.html#submit-type[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. |
| |
| [options="header",cols="1,6"] |
| |=============================== |
| |Field Name |Description |
| |`value` | |
| The effective submit type value. Never `INHERIT`. |
| |`configured_value` | |
| The configured value, can be one of the submit types, or `INHERIT` to inherit |
| from the parent project. |
| |`inherited_value` | |
| The effective value that would be inherited from the parent. Never `INHERIT`. |
| |=============================== |
| |
| [[tag-info]] |
| === TagInfo |
| The `TagInfo` entity contains information about a tag. |
| |
| [options="header",cols="1,^2,4"] |
| |========================= |
| |Field Name ||Description |
| |`ref` ||The ref of the tag. |
| |`revision` ||For lightweight tags, the revision of the commit to which the tag |
| points. For annotated tags, the revision of the tag object. |
| |`object`|Only set for annotated tags.|The revision of the object to which the |
| tag points. |
| |`message`|Only set for annotated tags.|The tag message. For signed tags, includes |
| the signature. |
| |`tagger`|Only set for annotated tags, if present in the tag.|The tagger as a |
| link:rest-api-changes.html#git-person-info[GitPersonInfo] entity. |
| |`created`|optional|The link:rest-api.html#timestamp[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 `date` field in the `tagger`. For lightweight tags, it is |
| the commit timestamp of the commit to which the tag points, when the object is a |
| commit. It is not set when the object is any other type. |
| |`can_delete`|not set if `false`| |
| Whether the calling user can delete this tag. |
| |`web_links` |optional| |
| Links to the tag in external sites as a list of |
| link:rest-api-changes.html#web-link-info[WebLinkInfo] entries. |
| |========================= |
| |
| [[tag-input]] |
| === TagInput |
| |
| The `TagInput` entity contains information for creating a tag. |
| |
| [options="header",cols="1,^2,4"] |
| |========================= |
| |Field Name ||Description |
| |`ref` ||The name of the tag. The leading `refs/tags/` is optional. |
| |`revision` |optional|The revision to which the tag should point. If not |
| specified, the project's `HEAD` will be used. |
| |`message` |optional|The tag message. When set, the tag will be created |
| as an annotated tag. |
| |========================= |
| |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |
