| = 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" | |
| } | |
| } | |
| ---- | |
| [[suggest-projects]] | |
| Prefix(p):: | |
| Limit the results to those projects that start with the specified | |
| prefix. | |
| + | |
| 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'. | |
| + | |
| 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. | |
| + | |
| 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. | |
| + | |
| 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" | |
| } | |
| } | |
| ---- | |
| [[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" | |
| } | |
| ---- | |
| [[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": "CHERRY_PICK", | |
| "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." | |
| } | |
| ---- | |
| [[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. | |
| The request body does not need to include a | |
| link:#project-description-input[ProjectDescriptionInput] entity if no | |
| commit message is specified. | |
| Please note that some proxies prohibit request bodies for DELETE | |
| requests. In this case, if you want to specify a commit message, use | |
| link:#set-project-description[PUT] to delete the description. | |
| .Request | |
| ---- | |
| DELETE /projects/plugins%2Freplication/description HTTP/1.0 | |
| ---- | |
| .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": "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", | |
| "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:#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, | |
| "config_visible": true | |
| } | |
| ---- | |
| [[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:#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, | |
| "config_visible": true | |
| } | |
| ---- | |
| [[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. | |
| .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", | |
| "can_delete": false | |
| } | |
| ] | |
| ---- | |
| 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", | |
| "can_delete": false | |
| } | |
| ] | |
| ---- | |
| Substring(m):: | |
| Limit the results to those projects that match the specified substring. | |
| + | |
| List all projects 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 'test' and regex '*t' will match any | |
| branches that end with 'test'. | |
| + | |
| 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 | |
| } | |
| ] | |
| ---- | |
| [[get-branch]] | |
| === Get Branch | |
| -- | |
| 'GET /projects/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{branch-id\}]' | |
| -- | |
| Retrieves a branch of a project. | |
| .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]. | |
| .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... | |
| ---- | |
| [[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, 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 | |
| } | |
| } | |
| ] | |
| ---- | |
| [[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 | |
| } | |
| } | |
| ---- | |
| [[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-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... | |
| ---- | |
| [[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", | |
| "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", | |
| "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", | |
| "default": true, | |
| "title": "Closed changes", | |
| "sections": [ | |
| { | |
| "name": "Merged", | |
| "query": "status:merged age:7w" | |
| }, | |
| { | |
| "name": "Abandoned", | |
| "query": "status:abandoned age:7w" | |
| } | |
| ] | |
| } | |
| ---- | |
| [[set-dashboard]] | |
| === Set Dashboard | |
| -- | |
| 'PUT /projects/link:#project-name[\{project-name\}]/dashboards/link:#dashboard-id[\{dashboard-id\}]' | |
| -- | |
| Updates/Creates a project dashboard. | |
| Currently only supported for the `default` dashboard. | |
| The creation/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": "Define the default dashboard" | |
| } | |
| ---- | |
| As response the new/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", | |
| "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 | |
| ---- | |
| [[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. | |
| [[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 | |
| [[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`|`false` if not set| | |
| 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. | |
| |======================= | |
| [[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. | |
| |`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. | |
| |`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. | |
| |`submit_type` || | |
| The default submit type of the project, can be `MERGE_IF_NECESSARY`, | |
| `FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `MERGE_ALWAYS` or | |
| `CHERRY_PICK`. | |
| |`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 the comment link | |
| configuration, which has the same format as the | |
| link:config-gerrit.html#_a_id_commentlink_a_section_commentlink[ | |
| commentlink section] of `gerrit.config`. | |
| |`theme` |optional| | |
| The theme that is configured for the project as a link:#theme-info[ | |
| ThemeInfo] 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. | |
| |`actions` |optional| | |
| Actions the caller might be able to perform on this project. The | |
| information is a map of view names to | |
| link:rest-api-changes.html#action-info[ActionInfo] entities. | |
| |======================================================= | |
| [[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. | |
| |`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`, `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. | |
| |====================================================== | |
| [[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. | |
| |`permitted_values` |optional| | |
| The list of permitted values, only set if the `type` is `LIST`. | |
| |=============================== | |
| [[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. | |
| |`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-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. | |
| |========================== | |
| [[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. | |
| |============================ | |
| [[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 `INHERITED`. | |
| |`inherited_value` |optional| | |
| The boolean value inherited from the parent. + | |
| Not set if there is no parent. | |
| |================================ | |
| [[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 of the max object size limit as a formatted string. + | |
| 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. | |
| |`inherited_value` |optional| | |
| The max object size limit that is inherited as a formatted string. + | |
| Not set if there is no global limit for the object size. | |
| |=============================== | |
| [[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. | |
| |`web_links` |optional| | |
| Links to the project in external sites as a list of | |
| link:rest-api-changes.html#web-link-info[WebLinkInfo] entries. | |
| |=========================== | |
| [[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`, `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. | |
| |`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`). | |
| |`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. | |
| |========================================= | |
| [[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. | |
| |====================================== | |
| [[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. | |
| |========================= | |
| [[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. | |
| |========================= | |
| [[theme-info]] | |
| === ThemeInfo | |
| The `ThemeInfo` entity describes a theme. | |
| [options="header",cols="1,^2,4"] | |
| |============================= | |
| |Field Name ||Description | |
| |`css` |optional| | |
| The path to the `GerritSite.css` file. | |
| |`header` |optional| | |
| The path to the `GerritSiteHeader.html` file. | |
| |`footer` |optional| | |
| The path to the `GerritSiteFooter.html` file. | |
| |============================= | |
| ---- | |
| GERRIT | |
| ------ | |
| Part of link:index.html[Gerrit Code Review] | |
| SEARCHBOX | |
| --------- |