Skip to content

G
gitlab-ce
Commit 3e65fa54 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Merge branch 'doc_refactor_commits_api' into 'master' 

Refactor commits API documentation

Blocked by https://gitlab.com/gitlab-org/gitlab-ce/issues/10960 which needs to be fixed or documented.

Closes #4217 

See merge request !2465
parents 8be4e545 373b277f
Show whitespace changes
Inline Side-by-side
Showing with 188 additions and 84 deletions
doc/api/commits.md
View file @ 3e65fa54
...@@ -8,10 +8,16 @@ Get a list of repository commits in a project. ...@@ -8,10 +8,16 @@ Get a list of repository commits in a project.
GET /projects/:id/repository/commits GET /projects/:id/repository/commits
``` ```
Parameters: | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `ref_name` | string | no | The name of a repository branch or tag or if not given the default branch |
```bash
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits"
```
- `id` (required) - The ID of a project Example response:
- `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch
```json ```json
[ [
...@@ -48,8 +54,16 @@ GET /projects/:id/repository/commits/:sha ...@@ -48,8 +54,16 @@ GET /projects/:id/repository/commits/:sha
Parameters: Parameters:
- `id` (required) - The ID of a project | Attribute | Type | Required | Description |
- `sha` (required) - The commit hash or name of a repository branch or tag | --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `sha` | string | yes | The commit hash or name of a repository branch or tag |
```bash
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master
```
Example response:
```json ```json
{ {
...@@ -79,8 +93,16 @@ GET /projects/:id/repository/commits/:sha/diff ...@@ -79,8 +93,16 @@ GET /projects/:id/repository/commits/:sha/diff
Parameters: Parameters:
- `id` (required) - The ID of a project | Attribute | Type | Required | Description |
- `sha` (required) - The name of a repository branch or tag or if not given the default branch | --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `sha` | string | yes | The commit hash or name of a repository branch or tag |
```bash
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master/diff"
```
Example response:
```json ```json
[ [
...@@ -107,8 +129,16 @@ GET /projects/:id/repository/commits/:sha/comments ...@@ -107,8 +129,16 @@ GET /projects/:id/repository/commits/:sha/comments
Parameters: Parameters:
- `id` (required) - The ID of a project | Attribute | Type | Required | Description |
- `sha` (required) - The name of a repository branch or tag or if not given the default branch | --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `sha` | string | yes | The commit hash or name of a repository branch or tag |
```bash
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master/comments"
```
Example response:
```json ```json
[ [
...@@ -128,39 +158,65 @@ Parameters: ...@@ -128,39 +158,65 @@ Parameters:
## Post comment to commit ## Post comment to commit
Adds a comment to a commit. Optionally you can post comments on a specific line of a commit. Therefor both `path`, `line_new` and `line_old` are required. Adds a comment to a commit.
In order to post a comment in a particular line of a particular file, you must
specify the full commit SHA, the `path`, the `line` and `line_type` should be
`new`.
The comment will be added at the end of the last commit if at least one of the
cases below is valid:
- the `sha` is instead a branch or a tag and the `line` or `path` are invalid
- the `line` number is invalid (does not exist)
- the `path` is invalid (does not exist)
In any of the above cases, the response of `line`, `line_type` and `path` is
set to `null`.
``` ```
POST /projects/:id/repository/commits/:sha/comments POST /projects/:id/repository/commits/:sha/comments
``` ```
Parameters: | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `sha` | string | yes | The commit SHA or name of a repository branch or tag |
| `note` | string | yes | The text of the comment |
| `path` | string | no | The file path relative to the repository |
| `line` | integer | no | The line number where the comment should be placed |
| `line_type` | string | no | The line type. Takes `new` or `old` as arguments |
```bash
curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -F "note=Nice picture man\!" -F "path=dudeism.md" -F "line=11" -F "line_type=new" https://gitlab.example.com/api/v3/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments
```
- `id` (required) - The ID of a project Example response:
- `sha` (required) - The name of a repository branch or tag or if not given the default branch
- `note` (required) - Text of comment
- `path` (optional) - The file path
- `line` (optional) - The line number
- `line_type` (optional) - The line type (new or old)
```json ```json
{ {
"author": { "author" : {
"id": 1, "web_url" : "https://gitlab.example.com/u/thedude",
"username": "admin", "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
"email": "admin@local.host", "username" : "thedude",
"name": "Administrator", "state" : "active",
"blocked": false, "name" : "Jeff Lebowski",
"created_at": "2012-04-29T08:46:00Z" "id" : 28
}, },
"note": "text1", "created_at" : "2016-01-19T09:44:55.600Z",
"path": "example.rb", "line_type" : "new",
"line": 5, "path" : "dudeism.md",
"line_type": "new" "line" : 11,
"note" : "Nice picture man!"
} }
``` ```
## Get the status of a commit ## Commit status
Since GitLab 8.1, this is the new commit status API. The documentation in
[ci/api/commits](../ci/api/commits.md) is deprecated.
### Get the status of a commit
Get the statuses of a commit in a project. Get the statuses of a commit in a project.
...@@ -168,75 +224,116 @@ Get the statuses of a commit in a project. ...@@ -168,75 +224,116 @@ Get the statuses of a commit in a project.
GET /projects/:id/repository/commits/:sha/statuses GET /projects/:id/repository/commits/:sha/statuses
``` ```
Parameters: | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project
| `sha` | string | yes | The commit SHA
| `ref_name`| string | no | The name of a repository branch or tag or, if not given, the default branch
| `stage` | string | no | Filter by [build stage](../ci/yaml/README.md#stages), e.g., `test`
| `name` | string | no | Filter by [job name](../ci/yaml/README.md#jobs), e.g., `bundler:audit`
| `all` | boolean | no | Return all statuses, not only the latest ones
```bash
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses
```
- `id` (required) - The ID of a project Example response:
- `sha` (required) - The commit SHA
- `ref` (optional) - Filter by ref name, it can be branch or tag
- `stage` (optional) - Filter by stage
- `name` (optional) - Filer by status name, eg. jenkins
- `all` (optional) - The flag to return all statuses, not only latest ones
```json ```json
[ [
...
{ {
"id": 13, "status" : "pending",
"sha": "b0b3a907f41409829b307a28b82fdbd552ee5a27", "created_at" : "2016-01-19T08:40:25.934Z",
"ref": "test", "started_at" : null,
"status": "success", "name" : "bundler:audit",
"name": "ci/jenkins", "allow_failure" : true,
"target_url": "http://jenkins/project/url", "author" : {
"description": "Jenkins success", "username" : "thedude",
"created_at": "2015-10-12T09:47:16.250Z", "state" : "active",
"started_at": "2015-10-12T09:47:16.250Z", "web_url" : "https://gitlab.example.com/u/thedude",
"finished_at": "2015-10-12T09:47:16.262Z", "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
"author": { "id" : 28,
"id": 1, "name" : "Jeff Lebowski"
"username": "admin", },
"email": "admin@local.host", "description" : null,
"name": "Administrator", "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
"blocked": false, "target_url" : "https://gitlab.example.com/thedude/gitlab-ce/builds/91",
"created_at": "2012-04-29T08:46:00Z" "finished_at" : null,
} "id" : 91,
} "ref" : "master"
},
{
"started_at" : null,
"name" : "flay",
"allow_failure" : false,
"status" : "pending",
"created_at" : "2016-01-19T08:40:25.832Z",
"target_url" : "https://gitlab.example.com/thedude/gitlab-ce/builds/90",
"id" : 90,
"finished_at" : null,
"ref" : "master",
"sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
"author" : {
"id" : 28,
"name" : "Jeff Lebowski",
"username" : "thedude",
"web_url" : "https://gitlab.example.com/u/thedude",
"state" : "active",
"avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png"
},
"description" : null
},
...
] ]
``` ```
## Post the status to commit ### Post the build status to a commit
Adds or updates a status of a commit. Adds or updates a build status of a commit.
``` ```
POST /projects/:id/statuses/:sha POST /projects/:id/statuses/:sha
``` ```
- `id` (required) - The ID of a project | Attribute | Type | Required | Description |
- `sha` (required) - The commit SHA | --------- | ---- | -------- | ----------- |
- `state` (required) - The state of the status. Can be: pending, running, success, failed, canceled | `id` | integer | yes | The ID of a project
- `ref` (optional) - The ref (branch or tag) to which the status refers | `sha` | string | yes | The commit SHA
- `name` or `context` (optional) - The label to differentiate this status from the status of other systems. Default: "default" | `state` | string | yes | The state of the status. Can be one of the following: `pending`, `running`, `success`, `failed`, `canceled`
- `target_url` (optional) - The target URL to associate with this status | `ref` | string | no | The `ref` (branch or tag) to which the status refers
- `description` (optional) - The short description of the status | `name` or `context` | string | no | The label to differentiate this status from the status of other systems. Default value is `default`
| `target_url` | string | no | The target URL to associate with this status
| `description` | string | no | The short description of the status
```bash
curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success"
```
Example response:
```json ```json
{ {
"id": 13, "author" : {
"sha": "b0b3a907f41409829b307a28b82fdbd552ee5a27", "web_url" : "https://gitlab.example.com/u/thedude",
"ref": "test", "name" : "Jeff Lebowski",
"status": "success", "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
"name": "ci/jenkins", "username" : "thedude",
"target_url": "http://jenkins/project/url", "state" : "active",
"description": "Jenkins success", "id" : 28
"created_at": "2015-10-12T09:47:16.250Z", },
"started_at": "2015-10-12T09:47:16.250Z", "name" : "default",
"finished_at": "2015-10-12T09:47:16.262Z", "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
"author": { "status" : "success",
"id": 1, "description" : null,
"username": "admin", "id" : 93,
"email": "admin@local.host", "target_url" : null,
"name": "Administrator", "ref" : null,
"blocked": false, "started_at" : null,
"created_at": "2012-04-29T08:46:00Z" "created_at" : "2016-01-19T09:05:50.355Z",
} "allow_failure" : false,
"finished_at" : "2016-01-19T09:05:50.365Z"
} }
``` ```
doc/ci/api/commits.md
View file @ 3e65fa54
# Commits API # Commits API
**DEPRECATED**
Since GitLab 8.1, there is a new commit status API. Please see the [revised
documentation](../../api/commits.md#commit-status).
---
__Authentication is done by GitLab CI project token__ __Authentication is done by GitLab CI project token__
## Commits ## Commits
......
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