gitlab-org--gitlab-foss/doc/api/builds.md

422 lines
12 KiB
Markdown
Raw Normal View History

2016-01-05 10:36:14 -05:00
# Builds API
## List project builds
Get a list of builds in a project.
```
GET /projects/:id/builds
```
2016-02-10 09:07:11 -05:00
| Attribute | Type | Required | Description |
|-----------|---------|----------|---------------------|
2016-02-10 08:31:30 -05:00
| `id` | integer | yes | The ID of a project |
2016-02-10 09:07:11 -05:00
| `scope` | string **or** array of strings | no | The scope of builds to show, one or array of: `pending`, `running`, `failed`, `success`, `canceled`; showing all builds if none provided |
```
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds"
```
2016-02-10 08:31:30 -05:00
Example of response
2016-01-05 10:36:14 -05:00
```json
[
{
"commit": {
2016-01-11 05:15:04 -05:00
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
2016-01-05 10:36:14 -05:00
},
2016-01-11 05:15:04 -05:00
"coverage": null,
"created_at": "2015-12-24T15:51:21.802Z",
"artifacts_file": {
"filename": "artifacts.zip",
"size": 1000
},
2016-01-11 05:15:04 -05:00
"finished_at": "2015-12-24T17:54:27.895Z",
"id": 7,
"name": "teaspoon",
2016-01-05 10:36:14 -05:00
"ref": "master",
"runner": null,
"stage": "test",
2016-01-11 05:15:04 -05:00
"started_at": "2015-12-24T17:54:27.722Z",
"status": "failed",
"tag": false,
"user": {
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"bio": null,
"created_at": "2015-12-21T13:14:24.077Z",
"id": 1,
"is_admin": true,
"linkedin": "",
"name": "Administrator",
"skype": "",
"state": "active",
"twitter": "",
"username": "root",
"web_url": "http://gitlab.dev/u/root",
"website_url": ""
}
2016-01-05 10:36:14 -05:00
},
{
"commit": {
2016-01-11 05:15:04 -05:00
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
2016-01-05 10:36:14 -05:00
},
2016-01-11 05:15:04 -05:00
"coverage": null,
"created_at": "2015-12-24T15:51:21.727Z",
"artifacts_file": null,
2016-01-11 05:15:04 -05:00
"finished_at": "2015-12-24T17:54:24.921Z",
"id": 6,
"name": "spinach:other",
2016-01-05 10:36:14 -05:00
"ref": "master",
"runner": null,
"stage": "test",
2016-01-11 05:15:04 -05:00
"started_at": "2015-12-24T17:54:24.729Z",
"status": "failed",
"tag": false,
"user": {
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"bio": null,
"created_at": "2015-12-21T13:14:24.077Z",
"id": 1,
"is_admin": true,
"linkedin": "",
"name": "Administrator",
"skype": "",
"state": "active",
"twitter": "",
"username": "root",
"web_url": "http://gitlab.dev/u/root",
"website_url": ""
}
2016-01-05 10:36:14 -05:00
}
]
```
## List commit builds
Get a list of builds for specific commit in a project.
```
2016-01-11 05:15:04 -05:00
GET /projects/:id/repository/commits/:sha/builds
2016-01-05 10:36:14 -05:00
```
2016-02-10 09:07:11 -05:00
| Attribute | Type | Required | Description |
|-----------|---------|----------|---------------------|
2016-02-10 08:31:30 -05:00
| `id` | integer | yes | The ID of a project |
| `sha` | string | yes | The SHA id of a commit |
| `scope` | string **or** array of strings | no | The scope of builds to show, one or array of: `pending`, `running`, `failed`, `success`, `canceled`; showing all builds if none provided |
```
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/repository/commits/0ff3ae198f8601a285adcf5c0fff204ee6fba5fd/builds"
```
2016-02-10 08:31:30 -05:00
Example of response
2016-01-05 10:36:14 -05:00
```json
2016-01-12 05:50:14 -05:00
[
{
"commit": {
2016-01-11 05:15:04 -05:00
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
2016-01-05 10:36:14 -05:00
},
2016-01-11 05:15:04 -05:00
"coverage": null,
2016-01-12 05:50:14 -05:00
"created_at": "2016-01-11T10:13:33.506Z",
"artifacts_file": null,
2016-01-12 05:50:14 -05:00
"finished_at": "2016-01-11T10:14:09.526Z",
"id": 69,
"name": "rubocop",
2016-01-05 10:36:14 -05:00
"ref": "master",
"runner": null,
"stage": "test",
2016-01-12 05:50:14 -05:00
"started_at": null,
"status": "canceled",
2016-01-11 05:15:04 -05:00
"tag": false,
2016-01-12 05:50:14 -05:00
"user": null
2016-01-05 10:36:14 -05:00
},
{
"commit": {
2016-01-11 05:15:04 -05:00
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
2016-01-05 10:36:14 -05:00
},
2016-01-11 05:15:04 -05:00
"coverage": null,
2016-01-12 05:50:14 -05:00
"created_at": "2015-12-24T15:51:21.957Z",
"artifacts_file": null,
2016-01-12 05:50:14 -05:00
"finished_at": "2015-12-24T17:54:33.913Z",
"id": 9,
"name": "brakeman",
2016-01-05 10:36:14 -05:00
"ref": "master",
"runner": null,
"stage": "test",
2016-01-12 05:50:14 -05:00
"started_at": "2015-12-24T17:54:33.727Z",
2016-01-11 05:15:04 -05:00
"status": "failed",
"tag": false,
"user": {
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"bio": null,
"created_at": "2015-12-21T13:14:24.077Z",
"id": 1,
"is_admin": true,
"linkedin": "",
"name": "Administrator",
"skype": "",
"state": "active",
"twitter": "",
"username": "root",
"web_url": "http://gitlab.dev/u/root",
"website_url": ""
}
2016-01-05 10:36:14 -05:00
}
]
2016-01-12 05:50:14 -05:00
```
## Get a single build
2016-01-05 10:36:14 -05:00
Get a single build of a project
```
GET /projects/:id/builds/:build_id
```
2016-02-10 09:07:11 -05:00
| Attribute | Type | Required | Description |
2016-02-10 08:31:30 -05:00
|------------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a project |
| `build_id` | integer | yes | The ID of a build |
```
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8"
```
2016-02-10 08:31:30 -05:00
Example of response
2016-01-05 10:36:14 -05:00
```json
{
"commit": {
2016-01-11 05:15:04 -05:00
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
2016-01-05 10:36:14 -05:00
},
2016-01-11 05:15:04 -05:00
"coverage": null,
"created_at": "2015-12-24T15:51:21.880Z",
"artifacts_file": null,
2016-01-11 05:15:04 -05:00
"finished_at": "2015-12-24T17:54:31.198Z",
"id": 8,
2016-01-05 10:36:14 -05:00
"name": "rubocop",
"ref": "master",
"runner": null,
"stage": "test",
2016-01-11 05:15:04 -05:00
"started_at": "2015-12-24T17:54:30.733Z",
"status": "failed",
"tag": false,
"user": {
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"bio": null,
"created_at": "2015-12-21T13:14:24.077Z",
"id": 1,
"is_admin": true,
"linkedin": "",
"name": "Administrator",
"skype": "",
"state": "active",
"twitter": "",
"username": "root",
"web_url": "http://gitlab.dev/u/root",
"website_url": ""
}
2016-01-05 10:36:14 -05:00
}
```
2016-02-19 14:56:56 -05:00
## Get build artifacts
> [Introduced][ce-2893] in GitLab 8.5
2016-02-19 14:56:56 -05:00
Get build artifacts of a project
```
GET /projects/:id/builds/:build_id/artifacts
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a project |
| `build_id` | integer | yes | The ID of a build |
```
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8/artifacts"
```
Response:
| Status | Description |
|-----------|---------------------------------|
| 200 | Serves the artifacts file |
| 404 | Build not found or no artifacts |
[ce-2893]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2893
2016-01-05 10:36:14 -05:00
## Cancel a build
Cancel a single build of a project
```
POST /projects/:id/builds/:build_id/cancel
```
2016-02-10 09:07:11 -05:00
| Attribute | Type | Required | Description |
2016-02-10 08:31:30 -05:00
|------------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a project |
| `build_id` | integer | yes | The ID of a build |
```
curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/cancel"
```
2016-01-05 10:36:14 -05:00
2016-02-10 08:31:30 -05:00
Example of response
2016-01-05 10:36:14 -05:00
```json
{
"commit": {
2016-01-11 05:15:04 -05:00
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
2016-01-05 10:36:14 -05:00
},
2016-01-11 05:15:04 -05:00
"coverage": null,
"created_at": "2016-01-11T10:13:33.506Z",
"artifacts_file": null,
2016-01-11 05:15:04 -05:00
"finished_at": "2016-01-11T10:14:09.526Z",
"id": 69,
2016-01-05 10:36:14 -05:00
"name": "rubocop",
"ref": "master",
"runner": null,
"stage": "test",
"started_at": null,
2016-01-11 05:15:04 -05:00
"status": "canceled",
"tag": false,
"user": null
2016-01-05 10:36:14 -05:00
}
```
## Retry a build
Retry a single build of a project
```
POST /projects/:id/builds/:build_id/retry
```
2016-02-10 09:07:11 -05:00
| Attribute | Type | Required | Description |
2016-02-10 08:31:30 -05:00
|------------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a project |
| `build_id` | integer | yes | The ID of a build |
```
curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/retry"
```
2016-01-05 10:36:14 -05:00
2016-02-10 08:31:30 -05:00
Example of response
2016-01-05 10:36:14 -05:00
```json
{
"commit": {
2016-01-11 05:15:04 -05:00
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
2016-01-05 10:36:14 -05:00
},
2016-01-11 05:15:04 -05:00
"coverage": null,
"created_at": "2016-01-11T10:13:33.506Z",
"artifacts_file": null,
2016-01-05 10:36:14 -05:00
"finished_at": null,
2016-01-11 05:15:04 -05:00
"id": 69,
2016-01-05 10:36:14 -05:00
"name": "rubocop",
"ref": "master",
"runner": null,
"stage": "test",
"started_at": null,
2016-01-11 05:15:04 -05:00
"status": "pending",
"tag": false,
"user": null
2016-01-05 10:36:14 -05:00
}
```
## Erase a build
Erase a single build of a project (remove build artifacts and a build trace)
```
POST /projects/:id/builds/:build_id/erase
```
Parameters
| Attribute | Type | required | Description |
|-------------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a project |
| `build_id` | integer | yes | The ID of a build |
Example of request
```
curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/erase"
```
Example of response
```json
{
"commit": {
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
},
"coverage": null,
"download_url": null,
"id": 69,
"name": "rubocop",
"ref": "master",
"runner": null,
"stage": "test",
"created_at": "2016-01-11T10:13:33.506Z",
"started_at": "2016-01-11T10:13:33.506Z",
"finished_at": "2016-01-11T10:15:10.506Z",
"status": "failed",
"tag": false,
"user": null
}
```