diff options
Diffstat (limited to 'doc/api/commits.md')
| -rw-r--r-- | doc/api/commits.md | 265 |
1 files changed, 181 insertions, 84 deletions
diff --git a/doc/api/commits.md b/doc/api/commits.md index 93d62b751e6..e4d436b8e52 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -8,10 +8,16 @@ Get a list of repository commits in a project. 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 -- `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch +Example response: ```json [ @@ -48,8 +54,16 @@ GET /projects/:id/repository/commits/:sha Parameters: -- `id` (required) - The ID of a project -- `sha` (required) - The commit hash or name of a repository branch or tag +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `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 { @@ -79,8 +93,16 @@ GET /projects/:id/repository/commits/:sha/diff Parameters: -- `id` (required) - The ID of a project -- `sha` (required) - The name of a repository branch or tag or if not given the default branch +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `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 [ @@ -107,8 +129,16 @@ GET /projects/:id/repository/commits/:sha/comments Parameters: -- `id` (required) - The ID of a project -- `sha` (required) - The name of a repository branch or tag or if not given the default branch +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `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 [ @@ -128,39 +158,65 @@ Parameters: ## 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 ``` -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 -- `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) +Example response: ```json { - "author": { - "id": 1, - "username": "admin", - "email": "admin@local.host", - "name": "Administrator", - "blocked": false, - "created_at": "2012-04-29T08:46:00Z" - }, - "note": "text1", - "path": "example.rb", - "line": 5, - "line_type": "new" + "author" : { + "web_url" : "https://gitlab.example.com/u/thedude", + "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png", + "username" : "thedude", + "state" : "active", + "name" : "Jeff Lebowski", + "id" : 28 + }, + "created_at" : "2016-01-19T09:44:55.600Z", + "line_type" : "new", + "path" : "dudeism.md", + "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. @@ -168,75 +224,116 @@ Get the statuses of a commit in a project. 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 -- `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 +Example response: ```json [ - { - "id": 13, - "sha": "b0b3a907f41409829b307a28b82fdbd552ee5a27", - "ref": "test", - "status": "success", - "name": "ci/jenkins", - "target_url": "http://jenkins/project/url", - "description": "Jenkins success", - "created_at": "2015-10-12T09:47:16.250Z", - "started_at": "2015-10-12T09:47:16.250Z", - "finished_at": "2015-10-12T09:47:16.262Z", - "author": { - "id": 1, - "username": "admin", - "email": "admin@local.host", - "name": "Administrator", - "blocked": false, - "created_at": "2012-04-29T08:46:00Z" - } - } + ... + + { + "status" : "pending", + "created_at" : "2016-01-19T08:40:25.934Z", + "started_at" : null, + "name" : "bundler:audit", + "allow_failure" : true, + "author" : { + "username" : "thedude", + "state" : "active", + "web_url" : "https://gitlab.example.com/u/thedude", + "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png", + "id" : 28, + "name" : "Jeff Lebowski" + }, + "description" : null, + "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8", + "target_url" : "https://gitlab.example.com/thedude/gitlab-ce/builds/91", + "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 ``` -- `id` (required) - The ID of a project -- `sha` (required) - The commit SHA -- `state` (required) - The state of the status. Can be: pending, running, success, failed, canceled -- `ref` (optional) - The ref (branch or tag) to which the status refers -- `name` or `context` (optional) - The label to differentiate this status from the status of other systems. Default: "default" -- `target_url` (optional) - The target URL to associate with this status -- `description` (optional) - The short description of the status +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project +| `sha` | string | yes | The commit SHA +| `state` | string | yes | The state of the status. Can be one of the following: `pending`, `running`, `success`, `failed`, `canceled` +| `ref` | string | no | The `ref` (branch or tag) to which the status refers +| `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 { - "id": 13, - "sha": "b0b3a907f41409829b307a28b82fdbd552ee5a27", - "ref": "test", - "status": "success", - "name": "ci/jenkins", - "target_url": "http://jenkins/project/url", - "description": "Jenkins success", - "created_at": "2015-10-12T09:47:16.250Z", - "started_at": "2015-10-12T09:47:16.250Z", - "finished_at": "2015-10-12T09:47:16.262Z", - "author": { - "id": 1, - "username": "admin", - "email": "admin@local.host", - "name": "Administrator", - "blocked": false, - "created_at": "2012-04-29T08:46:00Z" - } + "author" : { + "web_url" : "https://gitlab.example.com/u/thedude", + "name" : "Jeff Lebowski", + "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png", + "username" : "thedude", + "state" : "active", + "id" : 28 + }, + "name" : "default", + "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8", + "status" : "success", + "description" : null, + "id" : 93, + "target_url" : null, + "ref" : null, + "started_at" : null, + "created_at" : "2016-01-19T09:05:50.355Z", + "allow_failure" : false, + "finished_at" : "2016-01-19T09:05:50.365Z" } ``` |