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]. Endpoints --------- [[project-endpoints]] Project Endpoints ----------------- [[list-projects]] List Projects ~~~~~~~~~~~~~ [verse] '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": { "kind": "gerritcodereview#project", "id": "external%2Fbison", "description": "GNU parser generator" }, "external/gcc": { "kind": "gerritcodereview#project", "id": "external%2Fgcc", }, "external/openssl": { "kind": "gerritcodereview#project", "id": "external%2Fopenssl", "description": "encryption\ncrypto routines" }, "test": { "kind": "gerritcodereview#project", "id": "test", "description": "\u003chtml\u003e is escaped" } } ---- .Get all projects with their description **** get::/projects/?d **** [[suggest-projects]] The `/projects/` URL also accepts a prefix string in the `p` parameter. This limits 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": { "kind": "gerritcodereview#project", "id": "platform%2Fdrivers", }, "platform/tools": { "kind": "gerritcodereview#project", "id": "platform%2Ftools", } } ---- E.g. this feature can be used by suggestion client UI's to limit results. [[get-project]] Get Project ~~~~~~~~~~~ [verse] '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 )]}' { "kind": "gerritcodereview#project", "id": "plugins%2Freplication", "name": "plugins/replication", "parent": "Public-Plugins", "description": "Copies to other servers using the Git protocol" } ---- [[create-project]] Create Project ~~~~~~~~~~~~~~ [verse] '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 )]}' { "kind": "gerritcodereview#project", "id": "MyProject", "name": "MyProject", "parent": "All-Projects", "description": "This is a demo project." } ---- [[get-project-description]] Get Project Description ~~~~~~~~~~~~~~~~~~~~~~~ [verse] '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 ~~~~~~~~~~~~~~~~~~~~~~~ [verse] '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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ [verse] '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 ~~~~~~~~~~~~~~~~~~ [verse] '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 ~~~~~~~~~~~~~~~~~~ [verse] '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 ~~~~~~~~ [verse] '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 ~~~~~~~~ [verse] '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 ~~~~~~~~~~~~~~~~~~~~~~~~~ [verse] '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 ~~~~~~~~~~ [verse] '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 )]}' { "kind": "gerritcodereview#project_config", "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 }, "require_change_id": { "value": false, "configured_value": "FALSE", "inherited_value": true } "commentlinks": {} } ---- [[run-gc]] Run GC ~~~~~~ [verse] 'POST /projects/link:#project-name[\{project-name\}]/gc' Run the Git garbage collection for the repository of a project. .Request ---- POST /projects/plugins%2Freplication/gc HTTP/1.0 ---- 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. ---- [[dashboard-endpoints]] Dashboard Endpoints ------------------- [[list-dashboards]] List Dashboards ~~~~~~~~~~~~~~~ [verse] '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 )]}' [ { "kind": "gerritcodereview#dashboard", "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 ~~~~~~~~~~~~~ [verse] '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 )]}' { "kind": "gerritcodereview#dashboard", "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 )]}' { "kind": "gerritcodereview#dashboard", "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 ~~~~~~~~~~~~~ [verse] '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 )]}' { "kind": "gerritcodereview#dashboard", "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 ~~~~~~~~~~~~~~~~ [verse] '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 --- [[dashboard-id]] \{dashboard-id\} ~~~~~~~~~~~~~~~~ The ID of a dashboard in the format ':'. A special dashboard ID is `default` which represents the default dashboard of a project. [[project-name]] \{project-name\} ~~~~~~~~~~~~~~~~ The name of the project. [[json-entities]] JSON Entities ------------- [[config-info]] ConfigInfo ~~~~~~~~~~ The `ConfigInfo` entity contains information about the effective project configuration. Fields marked with * are only visible to users who have read access to `refs/meta/config`. [options="header",width="50%",cols="1,6"] |====================================== |Field Name |Description |`use_contributor_agreements*`| 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*`| 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*`| 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. |`require_change_id*`| 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. |`commentlinks`| Comment link configuration for the project. Has the same format as the link:config-gerrit.html#_a_id_commentlink_a_section_commentlink[commentlink section] of `gerrit.config`. |====================================== [[dashboard-info]] DashboardInfo ~~~~~~~~~~~~~ The `DashboardInfo` entity contains information about a project dashboard. [options="header",width="50%",cols="1,^2,4"] |=============================== |Field Name ||Description |`kind` ||`gerritcodereview#dashboard` |`id` || The ID of the dashboard. The ID has the format ':', 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 WebUI. + 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",width="50%",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",width="50%",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. |=========================== [[head-input]] HeadInput ~~~~~~~~~ The `HeadInput` entity contains information for setting `HEAD` for a project. [options="header",width="50%",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",width="50%",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. |================================ [[project-description-input]] ProjectDescriptionInput ~~~~~~~~~~~~~~~~~~~~~~~ The `ProjectDescriptionInput` entity contains information for setting a project description. [options="header",width="50%",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",width="50%",cols="1,^2,4"] |=========================== |Field Name ||Description |`kind` ||`gerritcodereview#project` |`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. + `?-` if the parent project is not visible (`` is a number which is increased for each non-visible project). |`description` |optional|The description of the project. |`branches` |optional|Map of branch names to HEAD revisions. |=========================== [[project-input]] ProjectInput ~~~~~~~~~~~~ The `ProjectInput` entity contains information for the creation of a new project. [options="header",width="50%",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. |`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. |`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`). |`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`). |========================================= [[project-parent-input]] ProjectParentInput ~~~~~~~~~~~~~~~~~~ The `ProjectParentInput` entity contains information for setting a project parent. [options="header",width="50%",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. |============================= [[repository-statistics-info]] RepositoryStatisticsInfo ~~~~~~~~~~~~~~~~~~~~~~~~ The `RepositoryStatisticsInfo` entity contains information about statistics of a Git repository. [options="header",width="50%",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. |====================================== GERRIT ------ Part of link:index.html[Gerrit Code Review]