BigW Consortium Gitlab

commits.md 15.9 KB
Newer Older
1 2 3 4 5 6 7 8 9 10
# Commits API

## List repository commits

Get a list of repository commits in a project.

```
GET /projects/:id/repository/commits
```

11 12
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
13
| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
14
| `ref_name` | string | no | The name of a repository branch or tag or if not given the default branch |
15 16
| `since` | string | no | Only commits after or on this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ |
| `until` | string | no | Only commits before or on this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ |
17

18
```bash
19
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/commits"
20 21 22
```

Example response:
23 24 25 26 27 28 29 30 31

```json
[
  {
    "id": "ed899a2f4b50b4370feeea94676502b42383c746",
    "short_id": "ed899a2f4b5",
    "title": "Replace sanitize with escape once",
    "author_name": "Dmitriy Zaporozhets",
    "author_email": "dzaporozhets@sphereconsultinginc.com",
32
    "authored_date": "2012-09-20T11:50:22+03:00",
33 34
    "committer_name": "Administrator",
    "committer_email": "admin@example.com",
35
    "committed_date": "2012-09-20T11:50:22+03:00",
36
    "created_at": "2012-09-20T11:50:22+03:00",
37
    "message": "Replace sanitize with escape once",
38 39 40
    "parent_ids": [
      "6104942438c14ec7bd21c6cd5bd995272b3faff6"
    ]
41 42 43 44 45 46 47
  },
  {
    "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
    "short_id": "6104942438c",
    "title": "Sanitize for network graph",
    "author_name": "randx",
    "author_email": "dmitriy.zaporozhets@gmail.com",
48 49
    "committer_name": "Dmitriy",
    "committer_email": "dmitriy.zaporozhets@gmail.com",
50
    "created_at": "2012-09-20T09:06:12+03:00",
51
    "message": "Sanitize for network graph",
52 53 54
    "parent_ids": [
      "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
    ]
55 56 57 58
  }
]
```

Marc Siegfriedt committed
59 60 61 62 63 64 65 66 67 68 69 70
## Create a commit with multiple files and actions

> [Introduced][ce-6096] in GitLab 8.13.

Create a commit by posting a JSON payload

```
POST /projects/:id/repository/commits
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
71
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
72
| `branch` | string | yes | Name of the branch to commit into. To create a new branch, also provide `start_branch`. |
Marc Siegfriedt committed
73
| `commit_message` | string | yes | Commit message |
74
| `start_branch` | string | no | Name of the branch to start the new commit from |
Marc Siegfriedt committed
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
| `actions[]` | array | yes | An array of action hashes to commit as a batch. See the next table for what attributes it can take. |
| `author_email` | string | no | Specify the commit author's email address |
| `author_name` | string | no | Specify the commit author's name |


| `actions[]` Attribute | Type | Required | Description |
| --------------------- | ---- | -------- | ----------- |
| `action` | string | yes | The action to perform, `create`, `delete`, `move`, `update` |
| `file_path` | string | yes | Full path to the file. Ex. `lib/class.rb` |
| `previous_path` | string | no | Original full path to the file being moved. Ex. `lib/class1.rb` |
| `content` | string | no | File content, required for all except `delete`. Optional for `move` |
| `encoding` | string | no | `text` or `base64`. `text` is default. |

```bash
PAYLOAD=$(cat << 'JSON'
{
91
  "branch": "master",
Marc Siegfriedt committed
92 93 94 95 96 97 98 99 100
  "commit_message": "some commit message",
  "actions": [
    {
      "action": "create",
      "file_path": "foo/bar",
      "content": "some content"
    },
    {
      "action": "delete",
101
      "file_path": "foo/bar2"
Marc Siegfriedt committed
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
    },
    {
      "action": "move",
      "file_path": "foo/bar3",
      "previous_path": "foo/bar4",
      "content": "some content"
    },
    {
      "action": "update",
      "file_path": "foo/bar5",
      "content": "new content"
    }
  ]
}
JSON
)
118
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "Content-Type: application/json" --data "$PAYLOAD" https://gitlab.example.com/api/v4/projects/1/repository/commits
Marc Siegfriedt committed
119 120 121 122 123 124 125 126 127 128
```

Example response:
```json
{
  "id": "ed899a2f4b50b4370feeea94676502b42383c746",
  "short_id": "ed899a2f4b5",
  "title": "some commit message",
  "author_name": "Dmitriy Zaporozhets",
  "author_email": "dzaporozhets@sphereconsultinginc.com",
129 130
  "committer_name": "Dmitriy Zaporozhets",
  "committer_email": "dzaporozhets@sphereconsultinginc.com",
Marc Siegfriedt committed
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146
  "created_at": "2016-09-20T09:26:24.000-07:00",
  "message": "some commit message",
  "parent_ids": [
    "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
  ],
  "committed_date": "2016-09-20T09:26:24.000-07:00",
  "authored_date": "2016-09-20T09:26:24.000-07:00",
  "stats": {
    "additions": 2,
    "deletions": 2,
    "total": 4
  },
  "status": null
}
```

147 148 149 150 151 152 153 154 155 156
## Get a single commit

Get a specific commit identified by the commit hash or name of a branch or tag.

```
GET /projects/:id/repository/commits/:sha
```

Parameters:

157 158
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
159
| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
160 161 162
| `sha` | string | yes | The commit hash or name of a repository branch or tag |

```bash
163
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master
164 165 166
```

Example response:
167 168 169 170 171 172 173 174

```json
{
  "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
  "short_id": "6104942438c",
  "title": "Sanitize for network graph",
  "author_name": "randx",
  "author_email": "dmitriy.zaporozhets@gmail.com",
175 176
  "committer_name": "Dmitriy",
  "committer_email": "dmitriy.zaporozhets@gmail.com",
177
  "created_at": "2012-09-20T09:06:12+03:00",
178
  "message": "Sanitize for network graph",
179 180
  "committed_date": "2012-09-20T09:06:12+03:00",
  "authored_date": "2012-09-20T09:06:12+03:00",
181 182
  "parent_ids": [
    "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
183
  ],
184 185 186 187 188
  "stats": {
    "additions": 15,
    "deletions": 10,
    "total": 25
  },
189
  "status": "running"
190 191 192
}
```

193 194 195 196 197 198 199 200 201 202 203 204 205 206
## Cherry pick a commit

> [Introduced][ce-8047] in GitLab 8.15.

Cherry picks a commit to a given branch.

```
POST /projects/:id/repository/commits/:sha/cherry_pick
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
207
| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
208 209 210 211
| `sha` | string | yes | The commit hash  |
| `branch` | string | yes | The name of the branch  |

```bash
212
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "branch=master" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/cherry_pick"
213 214 215 216 217 218 219 220 221 222 223
```

Example response:

```json
{
  "id": "8b090c1b79a14f2bd9e8a738f717824ff53aebad",
  "short_id": "8b090c1b",
  "title": "Feature added",
  "author_name": "Dmitriy Zaporozhets",
  "author_email": "dmitriy.zaporozhets@gmail.com",
224
  "authored_date": "2016-12-12T20:10:39.000+01:00",
225 226 227
  "created_at": "2016-12-12T20:10:39.000+01:00",
  "committer_name": "Administrator",
  "committer_email": "admin@example.com",
228 229 230 231 232 233
  "committed_date": "2016-12-12T20:10:39.000+01:00",
  "title": "Feature added",
  "message": "Feature added\n\nSigned-off-by: Dmitriy Zaporozhets <dmitriy.zaporozhets@gmail.com>\n",
  "parent_ids": [
    "a738f717824ff53aebad8b090c1b79a14f2bd9e8"
  ]
234 235 236
}
```

237 238 239 240 241 242 243 244 245 246
## Get the diff of a commit

Get the diff of a commit in a project.

```
GET /projects/:id/repository/commits/:sha/diff
```

Parameters:

247 248
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
249
| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
250 251 252
| `sha` | string | yes | The commit hash or name of a repository branch or tag |

```bash
253
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/diff"
254 255 256
```

Example response:
257 258 259 260

```json
[
  {
261
    "diff": "--- a/doc/update/5.4-to-6.0.md\n+++ b/doc/update/5.4-to-6.0.md\n@@ -71,6 +71,8 @@\n sudo -u git -H bundle exec rake migrate_keys RAILS_ENV=production\n sudo -u git -H bundle exec rake migrate_inline_notes RAILS_ENV=production\n \n+sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production\n+\n ```\n \n ### 6. Update config files",
262 263 264 265 266 267 268 269 270 271
    "new_path": "doc/update/5.4-to-6.0.md",
    "old_path": "doc/update/5.4-to-6.0.md",
    "a_mode": null,
    "b_mode": "100644",
    "new_file": false,
    "renamed_file": false,
    "deleted_file": false
  }
]
```
272 273 274 275 276 277 278 279 280 281 282

## Get the comments of a commit

Get the comments of a commit in a project.

```
GET /projects/:id/repository/commits/:sha/comments
```

Parameters:

283 284
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
285
| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
286 287 288
| `sha` | string | yes | The commit hash or name of a repository branch or tag |

```bash
289
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/comments"
290 291 292
```

Example response:
293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311

```json
[
  {
    "note": "this code is really nice",
    "author": {
      "id": 11,
      "username": "admin",
      "email": "admin@local.host",
      "name": "Administrator",
      "state": "active",
      "created_at": "2014-03-06T08:17:35.000Z"
    }
  }
]
```

## Post comment to commit

312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
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`.
327 328 329 330 331

```
POST /projects/:id/repository/commits/:sha/comments
```

332 333
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
334
| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
335 336
| `sha`       | string  | yes | The commit SHA or name of a repository branch or tag |
| `note`      | string  | yes | The text of the comment |
337
| `path`      | string  | no  | The file path relative to the repository |
338
| `line`      | integer | no  | The line number where the comment should be placed |
339 340 341
| `line_type` | string  | no  | The line type. Takes `new` or `old` as arguments |

```bash
342
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "note=Nice picture man\!" --form "path=dudeism.md" --form "line=11" --form "line_type=new" https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments
343
```
344

345
Example response:
346 347 348

```json
{
349
   "author" : {
350
      "web_url" : "https://gitlab.example.com/thedude",
351 352 353 354 355 356 357 358 359 360 361
      "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!"
362 363
}
```
364

365 366
## Commit status

367
Since GitLab 8.1, this is the new commit status API.
368 369

### Get the status of a commit
370 371 372 373 374 375 376

Get the statuses of a commit in a project.

```
GET /projects/:id/repository/commits/:sha/statuses
```

377 378
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
379
| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
380
| `sha`     | string  | yes | The commit SHA
381
| `ref`     | string  | no  | The name of a repository branch or tag or, if not given, the default branch
382 383 384
| `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
385

386
```bash
387
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses
388 389 390
```

Example response:
391 392 393

```json
[
394 395 396 397 398 399 400 401 402 403 404
   ...

   {
      "status" : "pending",
      "created_at" : "2016-01-19T08:40:25.934Z",
      "started_at" : null,
      "name" : "bundler:audit",
      "allow_failure" : true,
      "author" : {
         "username" : "thedude",
         "state" : "active",
405
         "web_url" : "https://gitlab.example.com/thedude",
406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431
         "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",
432
         "web_url" : "https://gitlab.example.com/thedude",
433 434 435 436 437 438 439
         "state" : "active",
         "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png"
      },
      "description" : null
   },

   ...
440 441 442
]
```

443
### Post the build status to a commit
444

445
Adds or updates a build status of a commit.
446 447 448 449 450

```
POST /projects/:id/statuses/:sha
```

451 452
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
453
| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
454 455 456 457 458 459
| `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
460
| `coverage` | float  | no    | The total code coverage
461 462

```bash
463
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success"
464 465 466
```

Example response:
467 468 469

```json
{
470
   "author" : {
471
      "web_url" : "https://gitlab.example.com/thedude",
472 473 474 475 476 477 478 479 480
      "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",
481
   "coverage": 100.0,
482 483 484 485 486 487 488 489
   "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"
490 491
}
```
Marc Siegfriedt committed
492 493

[ce-6096]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6096 "Multi-file commit"
494
[ce-8047]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8047