diff options
Diffstat (limited to 'doc/api/issues.md')
| -rw-r--r-- | doc/api/issues.md | 456 |
1 files changed, 325 insertions, 131 deletions
diff --git a/doc/api/issues.md b/doc/api/issues.md index 23028b44169..acfca50cb5e 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -27,6 +27,8 @@ When requested across groups or projects, it's expected to be the same as the `f ## List issues +> The `weight` property moved to GitLab Premium in 13.9. + Get all issues the authenticated user has access to. By default it returns only issues created by the current user. To get all issues, use parameter `scope=all`. @@ -60,6 +62,7 @@ GET /issues?state=opened | `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | +| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _(Introduced in [GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/260375))_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | @@ -75,7 +78,7 @@ GET /issues?state=opened | `state` | string | no | Return `all` issues or just those that are `opened` or `closed` | | `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | | `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413)| ```shell @@ -125,6 +128,7 @@ Example response: "avatar_url" : null, "username" : "root" }, + "type" : "ISSUE", "updated_at" : "2016-01-04T15:31:51.081Z", "closed_at" : null, "closed_by" : null, @@ -155,6 +159,7 @@ Example response: "task_status": "10 of 15 tasks completed", "confidential": false, "discussion_locked": false, + "issue_type": "issue", "_links":{ "self":"http://gitlab.example.com/api/v4/projects/1/issues/76", "notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes", @@ -169,8 +174,7 @@ Example response: ] ``` -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see -the `weight` parameter: +Issues created by users on GitLab Premium or higher include the `weight` property: ```json [ @@ -183,8 +187,25 @@ the `weight` parameter: ] ``` -Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see -the `health_status` parameter: +Issues created by users on GitLab Premium or higher include the `epic` property: + +```json +{ + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute + "epic": { + "id" : 42, + "iid" : 5, + "title": "My epic epic", + "url" : "/groups/h5bp/-/epics/5", + "group_id": 8 + }, + ... +} +``` + +Issues created by users on GitLab Ultimate include the `health_status` property: ```json [ @@ -201,6 +222,10 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. +WARNING: +The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +Please use `iid` of the `epic` attribute instead. + NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account @@ -208,6 +233,8 @@ that closed the issue still exists. ## List group issues +> The `weight` property moved to GitLab Premium in 13.9. + Get a list of a group's issues. If the group is private, credentials need to be provided for authorization. @@ -242,6 +269,9 @@ GET /groups/:id/issues?state=opened | `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | +| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _(Introduced in [GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/260375))_ | +| `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | +| `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | @@ -254,7 +284,7 @@ GET /groups/:id/issues?state=opened | `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | | `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | ```shell @@ -305,6 +335,7 @@ Example response: "id" : 9, "name" : "Dr. Luella Kovacek" }, + "type" : "ISSUE", "labels" : ["foo", "bar"], "upvotes": 4, "downvotes": 0, @@ -333,6 +364,7 @@ Example response: "task_status": "10 of 15 tasks completed", "confidential": false, "discussion_locked": false, + "issue_type": "issue", "_links":{ "self":"http://gitlab.example.com/api/v4/projects/4/issues/41", "notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes", @@ -347,8 +379,7 @@ Example response: ] ``` -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see -the `weight` parameter: +Issues created by users on GitLab Premium or higher include the `weight` property: ```json [ @@ -361,8 +392,25 @@ the `weight` parameter: ] ``` -Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see -the `health_status` parameter: +Issues created by users on GitLab Premium or higher include the `epic` property: + +```json +{ + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute + "epic": { + "id" : 42, + "iid" : 5, + "title": "My epic epic", + "url" : "/groups/h5bp/-/epics/5", + "group_id": 8 + }, + ... +} +``` + +Issues created by users on GitLab Ultimate include the `health_status` property: ```json [ @@ -378,6 +426,10 @@ the `health_status` parameter: WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. +WARNING: +The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +Please use `iid` of the `epic` attribute instead. + NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed @@ -385,6 +437,8 @@ the issue still exists. ## List project issues +> The `weight` property moved to GitLab Premium in 13.9. + Get a list of a project's issues. If the project is private, you need to provide credentials to authorize. @@ -419,6 +473,9 @@ GET /projects/:id/issues?state=opened | `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | +| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _(Introduced in [GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/260375))_ | +| `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | +| `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | @@ -430,7 +487,7 @@ GET /projects/:id/issues?state=opened | `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | | `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. `description_html` was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | ```shell @@ -481,6 +538,7 @@ Example response: "id" : 9, "name" : "Dr. Luella Kovacek" }, + "type" : "ISSUE", "labels" : ["foo", "bar"], "upvotes": 4, "downvotes": 0, @@ -516,6 +574,7 @@ Example response: "task_status": "10 of 15 tasks completed", "confidential": false, "discussion_locked": false, + "issue_type": "issue", "_links":{ "self":"http://gitlab.example.com/api/v4/projects/4/issues/41", "notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes", @@ -530,8 +589,7 @@ Example response: ] ``` -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see -the `weight` parameter: +Issues created by users on GitLab Premium or higher include the `weight` property: ```json [ @@ -544,8 +602,25 @@ the `weight` parameter: ] ``` -Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see -the `health_status` parameter: +Issues created by users on GitLab Premium or higher include the `epic` property: + +```json +{ + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute + "epic": { + "id" : 42, + "iid" : 5, + "title": "My epic epic", + "url" : "/groups/h5bp/-/epics/5", + "group_id": 8 + }, + ... +} +``` + +Issues created by users on GitLab Ultimate include the `health_status` property: ```json [ @@ -561,6 +636,10 @@ the `health_status` parameter: WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. +WARNING: +The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +Please use `iid` of the `epic` attribute instead. + NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -587,83 +666,81 @@ Example response: ```json { - "id" : 1, - "milestone" : { - "due_date" : null, - "project_id" : 4, - "state" : "closed", - "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.", - "iid" : 3, - "id" : 11, - "title" : "v3.0", - "created_at" : "2016-01-04T15:31:39.788Z", - "updated_at" : "2016-01-04T15:31:39.788Z", - "closed_at" : "2016-01-05T15:31:46.176Z" - }, - "author" : { - "state" : "active", - "web_url" : "https://gitlab.example.com/root", - "avatar_url" : null, - "username" : "root", - "id" : 1, - "name" : "Administrator" - }, - "description" : "Omnis vero earum sunt corporis dolor et placeat.", - "state" : "closed", - "iid" : 1, - "assignees" : [{ - "avatar_url" : null, - "web_url" : "https://gitlab.example.com/lennie", - "state" : "active", - "username" : "lennie", - "id" : 9, - "name" : "Dr. Luella Kovacek" - }], - "assignee" : { - "avatar_url" : null, - "web_url" : "https://gitlab.example.com/lennie", - "state" : "active", - "username" : "lennie", - "id" : 9, - "name" : "Dr. Luella Kovacek" - }, - "labels" : [], - "upvotes": 4, - "downvotes": 0, - "merge_requests_count": 0, - "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", - "updated_at" : "2016-01-04T15:31:46.176Z", - "created_at" : "2016-01-04T15:31:46.176Z", - "closed_at" : null, - "closed_by" : null, - "subscribed": false, - "user_notes_count": 1, - "due_date": null, - "web_url": "http://example.com/my-group/my-project/issues/1", - "references": { - "short": "#1", - "relative": "#1", - "full": "my-group/my-project#1" - }, - "time_stats": { - "time_estimate": 0, - "total_time_spent": 0, - "human_time_estimate": null, - "human_total_time_spent": null - }, - "confidential": false, - "discussion_locked": false, - "_links": { - "self": "http://example.com/api/v4/projects/1/issues/2", - "notes": "http://example.com/api/v4/projects/1/issues/2/notes", - "award_emoji": "http://example.com/api/v4/projects/1/issues/2/award_emoji", - "project": "http://example.com/api/v4/projects/1" - }, - "task_completion_status":{ - "count":0, - "completed_count":0 - }, - "weight": null, + "id": 1, + "milestone": { + "due_date": null, + "project_id": 4, + "state": "closed", + "description": "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.", + "iid": 3, + "id": 11, + "title": "v3.0", + "created_at": "2016-01-04T15:31:39.788Z", + "updated_at": "2016-01-04T15:31:39.788Z", + "closed_at": "2016-01-05T15:31:46.176Z" + }, + "author": { + "state": "active", + "web_url": "https://gitlab.example.com/root", + "avatar_url": null, + "username": "root", + "id": 1, + "name": "Administrator" + }, + "description": "Omnis vero earum sunt corporis dolor et placeat.", + "state": "closed", + "iid": 1, + "assignees": [ + { + "avatar_url": null, + "web_url": "https://gitlab.example.com/lennie", + "state": "active", + "username": "lennie", + "id": 9, + "name": "Dr. Luella Kovacek" + } + ], + "assignee": { + "avatar_url": null, + "web_url": "https://gitlab.example.com/lennie", + "state": "active", + "username": "lennie", + "id": 9, + "name": "Dr. Luella Kovacek" + }, + "type": "ISSUE", + "labels": [], + "upvotes": 4, + "downvotes": 0, + "merge_requests_count": 0, + "title": "Ut commodi ullam eos dolores perferendis nihil sunt.", + "updated_at": "2016-01-04T15:31:46.176Z", + "created_at": "2016-01-04T15:31:46.176Z", + "closed_at": null, + "closed_by": null, + "subscribed": false, + "user_notes_count": 1, + "due_date": null, + "web_url": "http://example.com/my-group/my-project/issues/1", + "references": { + "short": "#1", + "relative": "#1", + "full": "my-group/my-project#1" + }, + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, + "confidential": false, + "discussion_locked": false, + "issue_type": "issue", + "task_completion_status": { + "count": 0, + "completed_count": 0 + }, + "weight": null, "has_tasks": false, "_links": { "self": "http://gitlab.example:3000/api/v4/projects/1/issues/1", @@ -671,21 +748,12 @@ Example response: "award_emoji": "http://gitlab.example:3000/api/v4/projects/1/issues/1/award_emoji", "project": "http://gitlab.example:3000/api/v4/projects/1" }, - "references": { - "short": "#1", - "relative": "#1", - "full": "gitlab-org/gitlab-test#1" - }, - "subscribed": true, "moved_to_id": null, - "service_desk_reply_to": "service.desk@gitlab.com", - "epic_iid": null, - "epic": null + "service_desk_reply_to": "service.desk@gitlab.com" } ``` -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see -the `weight` parameter: +Issues created by users on GitLab Premium or higher include the `weight` property: ```json { @@ -696,10 +764,9 @@ the `weight` parameter: } ``` -Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see -the `epic` property: +Issues created by users on GitLab Premium or higher include the `epic` property: -```javascript +```json { "project_id" : 4, "description" : "Omnis vero earum sunt corporis dolor et placeat.", @@ -712,10 +779,24 @@ the `epic` property: "url" : "/groups/h5bp/-/epics/5", "group_id": 8 }, - // ... + ... } ``` +Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` +property: + +```json +[ + { + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "health_status": "on_track", + ... + } +] +``` + WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. @@ -793,6 +874,7 @@ Example response: "id" : 9, "name" : "Dr. Luella Kovacek" }, + "type" : "ISSUE", "labels" : [], "upvotes": 4, "downvotes": 0, @@ -820,6 +902,7 @@ Example response: }, "confidential": false, "discussion_locked": false, + "issue_type": "issue", "_links": { "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", @@ -833,8 +916,7 @@ Example response: } ``` -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see -the `weight` parameter: +Issues created by users on GitLab Premium or higher include the `weight` property: ```json { @@ -845,10 +927,9 @@ the `weight` parameter: } ``` -Users of [GitLab Premium](https://about.gitlab.com/pricing/) can also see -the `epic` property: +Issues created by users on GitLab Premium or higher include the `epic` property: -```javascript +```json { "project_id" : 4, "description" : "Omnis vero earum sunt corporis dolor et placeat.", @@ -860,7 +941,7 @@ the `epic` property: "url" : "/groups/h5bp/-/epics/5", "group_id": 8 }, - // ... + ... } ``` @@ -891,6 +972,8 @@ the issue still exists. ## New issue +> The `weight` property moved to GitLab Premium in 13.9. + Creates a new project issue. ```plaintext @@ -899,7 +982,8 @@ POST /projects/:id/issues | Attribute | Type | Required | Description | |-------------------------------------------|----------------|----------|--------------| -| `assignee_ids` | integer array | no | The ID of the user(s) to assign the issue to. | +| `assignee_id` | integer | no | The ID of the user to assign the issue to. Only appears on GitLab Free. | +| `assignee_ids` **(PREMIUM)** | integer array | no | The IDs of the users to assign the issue to. | | `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | | `created_at` | string | no | When the issue was created. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. | | `description` | string | no | The description of an issue. Limited to 1,048,576 characters. | @@ -909,11 +993,12 @@ POST /projects/:id/issues | `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157)) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `iid` | integer/string | no | The internal ID of the project's issue (requires administrator or project owner rights) | +| `issue_type` | string | no | The type of issue. One of `issue`, `incident`, or `test_case`. Default is `issue`. | | `labels` | string | no | Comma-separated label names for an issue | | `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This fills out the issue with a default description and mark all discussions as resolved. When passing a description or title, these values take precedence over the default values.| | `milestone_id` | integer | no | The global ID of a milestone to assign issue | | `title` | string | yes | The title of an issue | -| `weight` **(STARTER)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. | +| `weight` **(PREMIUM)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug" @@ -931,6 +1016,7 @@ Example response: "state" : "opened", "assignees" : [], "assignee" : null, + "type" : "ISSUE", "labels" : [ "bug" ], @@ -967,6 +1053,7 @@ Example response: }, "confidential": false, "discussion_locked": false, + "issue_type": "issue", "_links": { "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", @@ -980,8 +1067,7 @@ Example response: } ``` -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see -the `weight` parameter: +Issues created by users on GitLab Premium or higher include the `weight` property: ```json { @@ -992,8 +1078,25 @@ the `weight` parameter: } ``` -Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see -the `health_status` parameter: +Issues created by users on GitLab Premium or higher include the `epic` property: + +```json +{ + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute + "epic": { + "id" : 42, + "iid" : 5, + "title": "My epic epic", + "url" : "/groups/h5bp/-/epics/5", + "group_id": 8 + }, + ... +} +``` + +Issues created by users on GitLab Ultimate include the `health_status` property: ```json [ @@ -1009,6 +1112,10 @@ the `health_status` parameter: WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. +WARNING: +The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +Please use `iid` of the `epic` attribute instead. + NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -1020,6 +1127,8 @@ See [Issues rate limits](../user/admin_area/settings/rate_limit_on_issues_creati ## Edit issue +> The `weight` property moved to GitLab Premium in 13.9. + Updates an existing project issue. This call is also used to mark an issue as closed. @@ -1032,6 +1141,7 @@ At least one of the following parameters is required for the request to be succe - `:description` - `:discussion_locked` - `:due_date` +- `:issue_type` - `:labels` - `:milestone_id` - `:state_event` @@ -1053,13 +1163,14 @@ PUT /projects/:id/issues/:issue_iid | `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157)) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | +| `issue_type` | string | no | Updates the type of issue. One of `issue`, `incident`, or `test_case`. | | `labels` | string | no | Comma-separated label names for an issue. Set to an empty string to unassign all labels. | | `milestone_id` | integer | no | The global ID of a milestone to assign the issue to. Set to `0` or provide an empty value to unassign a milestone.| | `remove_labels`| string | no | Comma-separated label names to remove from an issue. | | `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it | | `title` | string | no | The title of an issue | | `updated_at` | string | no | When the issue was updated. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` (requires administrator or project owner rights). Empty string or null values are not accepted.| -| `weight` **(STARTER)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. 0 | +| `weight` **(PREMIUM)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. 0 | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close" @@ -1120,6 +1231,7 @@ Example response: }, "confidential": false, "discussion_locked": false, + "issue_type": "issue", "_links": { "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", @@ -1133,8 +1245,7 @@ Example response: } ``` -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see -the `weight` parameter: +Issues created by users on GitLab Premium or higher include the `weight` property: ```json { @@ -1145,8 +1256,25 @@ the `weight` parameter: } ``` -Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see -the `health_status` parameter: +Issues created by users on GitLab Premium or higher include the `epic` property: + +```json +{ + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute + "epic": { + "id" : 42, + "iid" : 5, + "title": "My epic epic", + "url" : "/groups/h5bp/-/epics/5", + "group_id": 8 + }, + ... +} +``` + +Issues created by users on GitLab Ultimate include the `health_status` property: ```json [ @@ -1164,6 +1292,10 @@ The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/git the issue still exists. WARNING: +The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +Please use `iid` of the `epic` attribute instead. + +WARNING: `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. ## Delete an issue @@ -1262,6 +1394,7 @@ Example response: "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", "web_url": "https://gitlab.example.com/axel.block" }, + "type" : "ISSUE", "author": { "name": "Kris Steuber", "username": "solon.cremin", @@ -1285,6 +1418,7 @@ Example response: }, "confidential": false, "discussion_locked": false, + "issue_type": "issue", "_links": { "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", @@ -1298,8 +1432,7 @@ Example response: } ``` -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see -the `weight` parameter: +Issues created by users on GitLab Premium or higher include the `weight` property: ```json { @@ -1310,8 +1443,25 @@ the `weight` parameter: } ``` -Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see -the `health_status` parameter: +Issues created by users on GitLab Premium or higher include the `epic` property: + +```json +{ + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute + "epic": { + "id" : 42, + "iid" : 5, + "title": "My epic epic", + "url" : "/groups/h5bp/-/epics/5", + "group_id": 8 + }, + ... +} +``` + +Issues created by users on GitLab Ultimate include the `health_status` property: ```json [ @@ -1327,6 +1477,10 @@ the `health_status` parameter: WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. +WARNING: +The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +Please use `iid` of the `epic` attribute instead. + NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -1385,6 +1539,7 @@ Example response: "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", "web_url": "https://gitlab.example.com/axel.block" }, + "type" : "ISSUE", "author": { "name": "Kris Steuber", "username": "solon.cremin", @@ -1408,6 +1563,7 @@ Example response: }, "confidential": false, "discussion_locked": false, + "issue_type": "issue", "_links": { "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", @@ -1421,8 +1577,7 @@ Example response: } ``` -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see -the `weight` parameter: +Issues created by users on GitLab Premium or higher include the `weight` property: ```json { @@ -1433,9 +1588,44 @@ the `weight` parameter: } ``` +Issues created by users on GitLab Premium or higher include the `epic` property: + +```json +{ + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute + "epic": { + "id" : 42, + "iid" : 5, + "title": "My epic epic", + "url" : "/groups/h5bp/-/epics/5", + "group_id": 8 + }, + ... +} +``` + +Issues created by users on GitLab Ultimate include the `health_status` property: + +```json +[ + { + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "health_status": "on_track", + ... + } +] +``` + WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. +WARNING: +The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +Please use `iid` of the `epic` attribute instead. + NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -1484,6 +1674,7 @@ Example response: "avatar_url": "http://www.gravatar.com/avatar/3e6f06a86cf27fa8b56f3f74f7615987?s=80&d=identicon", "web_url": "https://gitlab.example.com/keyon" }, + "type" : "ISSUE", "closed_at": null, "closed_by": null, "author": { @@ -1504,6 +1695,7 @@ Example response: }, "confidential": false, "discussion_locked": false, + "issue_type": "issue", "task_completion_status":{ "count":0, "completed_count":0 @@ -1589,6 +1781,7 @@ Example response: "avatar_url": "http://www.gravatar.com/avatar/a7fa515d53450023c83d62986d0658a8?s=80&d=identicon", "web_url": "https://gitlab.example.com/francisca" }, + "type" : "ISSUE", "author": { "name": "Maxie Medhurst", "username": "craig_rutherford", @@ -1611,6 +1804,7 @@ Example response: }, "confidential": false, "discussion_locked": false, + "issue_type": "issue", "task_completion_status":{ "count":0, "completed_count":0 @@ -1836,7 +2030,7 @@ If the project is private or the issue is confidential, you need to provide cred The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). ```plaintext -GET /projects/:id/issues/:issue_id/related_merge_requests +GET /projects/:id/issues/:issue_iid/related_merge_requests ``` | Attribute | Type | Required | Description | |