diff options
Diffstat (limited to 'doc/api/issues.md')
| -rw-r--r-- | doc/api/issues.md | 176 |
1 files changed, 151 insertions, 25 deletions
diff --git a/doc/api/issues.md b/doc/api/issues.md index ad5990f4a37..f6bab9ce676 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Issues API @@ -16,11 +16,11 @@ are paginated. Read more on [pagination](README.md#pagination). -DANGER: **Deprecated:** +WARNING: The `reference` attribute in responses is deprecated in favor of `references`. Introduced in [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354). -NOTE: **Note:** +NOTE: The `references.relative` attribute is relative to the group or project of the issue being requested. When an issue is fetched from its project, the `relative` format is the same as the `short` format, and when requested across groups or projects it's expected to be the same as the `full` format. @@ -197,11 +197,11 @@ the `health_status` parameter: ] ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +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. @@ -375,10 +375,10 @@ the `health_status` parameter: ] ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +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. @@ -558,10 +558,10 @@ the `health_status` parameter: ] ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +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. @@ -678,6 +678,7 @@ Example response: }, "subscribed": true, "moved_to_id": null, + "service_desk_reply_to": "service.desk@gitlab.com", "epic_iid": null, "epic": null } @@ -715,15 +716,15 @@ the `epic` property: } ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -DANGER: **Deprecated:** +WARNING: The `epic_iid` attribute is deprecated, and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). Please use `iid` of the `epic` attribute instead. -NOTE: **Note:** +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. @@ -877,14 +878,14 @@ property: ] ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -DANGER: **Deprecated:** +WARNING: The `epic_iid` attribute is deprecated and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). Please use `iid` of the `epic` attribute instead. -NOTE: **Note:** +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. @@ -1005,10 +1006,10 @@ the `health_status` parameter: ] ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +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. @@ -1158,11 +1159,11 @@ the `health_status` parameter: ] ``` -NOTE: **Note:** +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. -DANGER: **Deprecated:** +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 @@ -1323,10 +1324,10 @@ the `health_status` parameter: ] ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +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. @@ -1432,10 +1433,10 @@ the `weight` parameter: } ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +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. @@ -1622,13 +1623,68 @@ Example response: } ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +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. +## Promote an issue to an epic **(PREMIUM)** + +Promotes an issue to an epic by adding a comment with the `/promote` +[quick action](../user/project/quick_actions.md). + +To learn more about promoting issues to epics, visit [Manage epics](../user/group/epics/manage_epics.md#promote-an-issue-to-an-epic). + +```plaintext +POST /projects/:id/issues/:issue_iid/notes +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +| :---------- | :------------- | :------- | :---------- | +| `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 | +| `body` | String | yes | The content of a note. Must contain `/promote` at the start of a new line. | + +Example request: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=Lets%20promote%20this%20to%20an%20epic%0A%0A%2Fpromote" +``` + +Example response: + +```json +{ + "id":699, + "type":null, + "body":"Lets promote this to an epic", + "attachment":null, + "author": { + "id":1, + "name":"Alexandra Bashirian", + "username":"eileen.lowe", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url":"https://gitlab.example.com/eileen.lowe" + }, + "created_at":"2020-12-03T12:27:17.844Z", + "updated_at":"2020-12-03T12:27:17.844Z", + "system":false, + "noteable_id":461, + "noteable_type":"Issue", + "resolvable":false, + "confidential":false, + "noteable_iid":33, + "commands_changes": { + "promote_to_epic":true + } +} +``` + ## Set a time estimate for an issue Sets an estimated time of work for this issue. @@ -2085,3 +2141,73 @@ Example response: To track which state was set, who did it, and when it happened, check out [Resource state events API](resource_state_events.md#issues). + +## Upload metric image + +Available only for Incident issues. + +```plaintext +POST /projects/:id/issues/:issue_iid/metric_images +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|--------------------------------------| +| `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 | +| `file` | file | yes | The image file to be uploaded | +| `url` | string | no | The URL to view more metric information | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" --form 'file=@/path/to/file.png' \ +--form 'url=http://example.com' "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" +``` + +Example response: + +```json +{ + "id": 23, + "created_at": "2020-11-13T00:06:18.084Z", + "filename": "file.png", + "file_path": "/uploads/-/system/issuable_metric_image/file/23/file.png", + "url": "http://example.com" +} +``` + +## List metric images + +Available only for Incident issues. + +```plaintext +GET /projects/:id/issues/:issue_iid/metric_images +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|--------------------------------------| +| `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 | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" +``` + +Example response: + +```json +[ + { + "id": 17, + "created_at": "2020-11-12T20:07:58.156Z", + "filename": "sample_2054", + "file_path": "/uploads/-/system/issuable_metric_image/file/17/sample_2054.png", + "url": "example.com/metric" + }, + { + "id": 18, + "created_at": "2020-11-12T20:14:26.441Z", + "filename": "sample_2054", + "file_path": "/uploads/-/system/issuable_metric_image/file/18/sample_2054.png", + "url": "example.com/metric" + } +] +``` |