Skip to content

G
gitlab-ce
Commit 060e5383 authored by Amy Qualls's avatar Amy Qualls Committed by Craig Norris
Browse files
Options

Fix line wrapping, and redact discussion IDs

parent 3d823895
Hide whitespace changes
Inline Side-by-side
Showing with 113 additions and 69 deletions
doc/api/discussions.md
View file @ 060e5383
......@@ -15,7 +15,9 @@ Discussions are a set of related notes on:
- Merge requests
- Commits
This includes system notes, which are notes about changes to the object (for example, when a milestone changes, a corresponding system note is added). Label notes are not part of this API, but recorded as separate events in [resource label events](resource_label_events.md).
This includes system notes, which are notes about changes to the object (for example,
when a milestone changes, a corresponding system note is added). Label notes are
not part of this API, but recorded as separate events in [resource label events](resource_label_events.md).
## Discussions pagination
......@@ -118,7 +120,8 @@ GET /projects/:id/issues/:issue_iid/discussions
```
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions"
curl --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/issues/11/discussions"
```
### Get single issue discussion item
......@@ -138,7 +141,8 @@ Parameters:
| `discussion_id` | integer | yes | The ID of a discussion item |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7"
curl --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/<discussion_id>"
```
### Create new issue thread
......@@ -159,7 +163,8 @@ Parameters:
| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment"
```
### Add note to existing issue thread
......@@ -185,7 +190,8 @@ Parameters:
| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/<discussion_id>/notes?body=comment"
```
### Modify existing issue thread note
......@@ -207,7 +213,8 @@ Parameters:
| `body` | string | yes | The content of the note/reply |
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/<discussion_id>/notes/1108?body=comment"
```
### Delete an issue thread note
......@@ -228,7 +235,8 @@ Parameters:
| `note_id` | integer | yes | The ID of a discussion note |
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636"
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636"
```
## Snippets
......@@ -326,7 +334,8 @@ GET /projects/:id/snippets/:snippet_id/discussions
```
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions"
curl --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions"
```
### Get single snippet discussion item
......@@ -346,7 +355,8 @@ Parameters:
| `discussion_id` | integer | yes | The ID of a discussion item |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/<discussion_id>"
```
### Create new snippet thread
......@@ -368,7 +378,8 @@ Parameters:
| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment"
```
### Add note to existing snippet thread
......@@ -391,7 +402,8 @@ Parameters:
| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/<discussion_id>/notes?body=comment"
```
### Modify existing snippet thread note
......@@ -413,7 +425,8 @@ Parameters:
| `body` | string | yes | The content of the note/reply |
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/<discussion_id>/notes/1108?body=comment"
```
### Delete a snippet thread note
......@@ -434,7 +447,8 @@ Parameters:
| `note_id` | integer | yes | The ID of a discussion note |
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636"
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636"
```
## Epics **(ULTIMATE)**
......@@ -533,7 +547,8 @@ GET /groups/:id/epics/:epic_id/discussions
```
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions"
curl --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/groups/5/epics/11/discussions"
```
### Get single epic discussion item
......@@ -553,7 +568,8 @@ Parameters:
| `discussion_id` | integer | yes | The ID of a discussion item |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/<discussion_id>"
```
### Create new epic thread
......@@ -575,7 +591,8 @@ Parameters:
| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions?body=comment"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/groups/5/epics/11/discussions?body=comment"
```
### Add note to existing epic thread
......@@ -599,7 +616,8 @@ Parameters:
| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/<discussion_id>/notes?body=comment"
```
### Modify existing epic thread note
......@@ -621,7 +639,8 @@ Parameters:
| `body` | string | yes | The content of note/reply |
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/<discussion_id>/notes/1108?body=comment"
```
### Delete an epic thread note
......@@ -642,7 +661,8 @@ Parameters:
| `note_id` | integer | yes | The ID of a thread note |
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/636"
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/636"
```
## Merge requests
......@@ -805,7 +825,8 @@ Diff comments also contain position:
```
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions"
curl --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions"
```
### Get single merge request discussion item
......@@ -825,7 +846,8 @@ Parameters:
| `discussion_id` | integer | yes | The ID of a discussion item |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
curl --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>"
```
### Create new merge request thread
......@@ -866,57 +888,67 @@ Parameters for all comments:
#### Create a new thread on the overview page
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment"
```
#### Create a new thread in the merge request diff
- Both `position[old_path]` and `position[new_path]` are required and must refer to the file path before and after the change.
- To create a thread on an added line (highlighted in green in the merge request diff), use `position[new_line]` and don't include `position[old_line]`.
- To create a thread on a removed line (highlighted in red in the merge request diff), use `position[old_line]` and don't include `position[new_line]`.
- To create a thread on an unchanged line, include both `position[new_line]` and `position[old_line]` for the line. These positions might not be the same if earlier changes in the file changed the line number. This is a bug that we plan to fix in [GraphQL `createDiffNote` forces clients to compute redundant information (#325161)](https://gitlab.com/gitlab-org/gitlab/-/issues/325161).
- If you specify incorrect `base`/`head`/`start` `SHA` parameters, you might run into the following bug: [Merge request comments receive "download" link instead of inline code (#296829)](https://gitlab.com/gitlab-org/gitlab/-/issues/296829).
- Both `position[old_path]` and `position[new_path]` are required and must refer
to the file path before and after the change.
- To create a thread on an added line (highlighted in green in the merge request diff),
use `position[new_line]` and don't include `position[old_line]`.
- To create a thread on a removed line (highlighted in red in the merge request diff),
use `position[old_line]` and don't include `position[new_line]`.
- To create a thread on an unchanged line, include both `position[new_line]` and
`position[old_line]` for the line. These positions might not be the same if earlier
changes in the file changed the line number. This is a bug that we plan to fix in
[GraphQL `createDiffNote` forces clients to compute redundant information (#325161)](https://gitlab.com/gitlab-org/gitlab/-/issues/325161).
- If you specify incorrect `base`/`head`/`start` `SHA` parameters, you might run
into the following bug:
[Merge request comments receive "download" link instead of inline code (#296829)](https://gitlab.com/gitlab-org/gitlab/-/issues/296829).
To create a new thread:
1. [Get the latest merge request version](merge_requests.md#get-mr-diff-versions):
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/versions"
````
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/merge_requests/11/versions"
```
1. Note the details of the latest version, which is listed first in the response array.
```json
[
{
"id": 164560414,
"head_commit_sha": "f9ce7e16e56c162edbc9e480108041cf6b0291fe",
"base_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80",
"start_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80",
"created_at": "2021-03-30T09:18:27.351Z",
"merge_request_id": 93958054,
"state": "collected",
"real_size": "2"
},
"previous versions are here"
]
```
```json
[
{
"id": 164560414,
"head_commit_sha": "f9ce7e16e56c162edbc9e480108041cf6b0291fe",
"base_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80",
"start_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80",
"created_at": "2021-03-30T09:18:27.351Z",
"merge_request_id": 93958054,
"state": "collected",
"real_size": "2"
},
"previous versions are here"
]
```
1. Create a new diff thread. This example creates a thread on an added line:
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
--form 'position[position_type]=text'\
--form 'position[base_sha]=<use base_commit_sha from the versions response>'\
--form 'position[head_sha]=<use head_commit_sha from the versions response>'\
--form 'position[start_sha]=<use start_commit_sha from the versions response>'\
--form 'position[new_path]=file.js'\
--form 'position[old_path]=file.js'\
--form 'position[new_line]=18'\
--form 'body=test comment body'\
"https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions"
```
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
--form 'position[position_type]=text'\
--form 'position[base_sha]=<use base_commit_sha from the versions response>'\
--form 'position[head_sha]=<use head_commit_sha from the versions response>'\
--form 'position[start_sha]=<use start_commit_sha from the versions response>'\
--form 'position[new_path]=file.js'\
--form 'position[old_path]=file.js'\
--form 'position[new_line]=18'\
--form 'body=test comment body'\
"https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions"
```
#### Parameters for multiline comments
......@@ -960,7 +992,8 @@ Parameters:
| `resolved` | boolean | yes | Resolve/unresolve the discussion |
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7?resolved=true"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>?resolved=true"
```
### Add note to existing merge request thread
......@@ -984,7 +1017,8 @@ Parameters:
| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>/notes?body=comment"
```
### Modify an existing merge request thread note
......@@ -1007,13 +1041,15 @@ Parameters:
| `resolved` | boolean | no | Resolve/unresolve the note (exactly one of `body` or `resolved` must be set |
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>/notes/1108?body=comment"
```
Resolving a note:
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>/notes/1108?resolved=true"
```
### Delete a merge request thread note
......@@ -1034,7 +1070,8 @@ Parameters:
| `note_id` | integer | yes | The ID of a thread note |
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636"
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636"
```
## Commits
......@@ -1177,7 +1214,8 @@ Diff comments contain also position:
```
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions"
curl --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/commits/11/discussions"
```
### Get single commit discussion item
......@@ -1197,7 +1235,8 @@ Parameters:
| `discussion_id` | integer | yes | The ID of a discussion item |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7"
curl --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/<discussion_id>"
```
### Create new commit thread
......@@ -1232,7 +1271,8 @@ Parameters:
| `position[y]` | integer | no | Y coordinate (for `image` diff notes) |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment"
```
The rules for creating the API request are the same as when
......@@ -1259,7 +1299,8 @@ Parameters:
| `created_at` | string | no | Date time string, ISO 8601 formatted, such `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/<discussion_id>/notes?body=comment
```
### Modify an existing commit thread note
......@@ -1281,13 +1322,15 @@ Parameters:
| `body` | string | no | The content of a note |
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/<discussion_id>/notes/1108?body=comment"
```
Resolving a note:
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/<discussion_id>/notes/1108?resolved=true"
```
### Delete a commit thread note
......@@ -1308,5 +1351,6 @@ Parameters:
| `note_id` | integer | yes | The ID of a thread note |
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/636"
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\
"https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/636"
```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7