Add documentation of incremental trace update API
[ci skip]
This commit is contained in:
parent
a70164519d
commit
0725c28069
|
@ -26,48 +26,114 @@ This API uses two types of authentication:
|
|||
|
||||
### Runs oldest pending build by runner
|
||||
|
||||
POST /ci/api/v1/builds/register
|
||||
```
|
||||
POST /ci/api/v1/builds/register
|
||||
```
|
||||
|
||||
Parameters:
|
||||
| Attribute | Type | Required | Description |
|
||||
|-----------|---------|----------|---------------------|
|
||||
| `token` | string | yes | Unique runner token |
|
||||
|
||||
* `token` (required) - Unique runner token
|
||||
|
||||
```
|
||||
curl -X POST "https://gitlab.example.com/ci/api/v1/builds/register" -F "token=t0k3n"
|
||||
```
|
||||
|
||||
### Update details of an existing build
|
||||
|
||||
PUT /ci/api/v1/builds/:id
|
||||
```
|
||||
PUT /ci/api/v1/builds/:id
|
||||
```
|
||||
|
||||
| Attribute | Type | Required | Description |
|
||||
|-----------|---------|----------|----------------------|
|
||||
| `id` | integer | yes | The ID of a project |
|
||||
| `token` | string | yes | Unique runner token |
|
||||
| `state` | string | no | The state of a build |
|
||||
| `trace` | string | no | The trace of a build |
|
||||
|
||||
```
|
||||
curl -X PUT "https://gitlab.example.com/ci/api/v1/builds/1234" -F "token=t0k3n" -F "state=running" -F "trace=Running git clone...\n"
|
||||
```
|
||||
|
||||
### Incremental build trace update
|
||||
|
||||
Using this method you need to send trace content as a request body. You need also to provide the `Content-Range` header
|
||||
with a range of sent trace part. Note, that you need to send parts in a proper order, so the begining of the part
|
||||
must starts just after the end of the previous part. If you will mess the parts, then GitLab CI AIP will return `416
|
||||
Range Not Satisfiable` response with a header `Range: 0-X`, where `X` is the current trace length.
|
||||
|
||||
For example: if you receive `Range: 0-11` in the response, then your next part must contains `Content-Range: 11-...`
|
||||
header and a trace part covered by this range.
|
||||
|
||||
For a valid update API will return `202` response with:
|
||||
* `Build-Status: {status}` header containing current status of the build,
|
||||
* `Range: 0-{length}` header with the current trace length.
|
||||
|
||||
```
|
||||
PATCH /ci/api/v1/builds/:id/trace.txt
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
* `id` (required) - The ID of a project
|
||||
* `token` (required) - Unique runner token
|
||||
* `state` (optional) - The state of a build
|
||||
* `trace` (optional) - The trace of a build
|
||||
| Attribute | Type | Required | Description |
|
||||
|-----------|---------|----------|----------------------|
|
||||
| `id` | integer | yes | The ID of a build |
|
||||
|
||||
Headers:
|
||||
|
||||
| Attribute | Type | Required | Description |
|
||||
|-----------------|---------|----------|-----------------------------------|
|
||||
| `BUILD-TOKEN` | string | yes | The build authorization token |
|
||||
| `Content-Range` | string | yes | Bytes range of trace that is sent |
|
||||
|
||||
```
|
||||
curl -X PATCH "https://gitlab.example.com/ci/api/v1/builds/1234/trace.txt" -H "BUILD-TOKEN=build_t0k3n" -H "Content-Range=0-21" -d "Running git clone...\n"
|
||||
```
|
||||
|
||||
|
||||
### Upload artifacts to build
|
||||
|
||||
POST /ci/api/v1/builds/:id/artifacts
|
||||
```
|
||||
POST /ci/api/v1/builds/:id/artifacts
|
||||
```
|
||||
|
||||
Parameters:
|
||||
| Attribute | Type | Required | Description |
|
||||
|-----------|---------|----------|-------------------------------|
|
||||
| `id` | integer | yes | The ID of a build |
|
||||
| `token` | string | yes | The build authorization token |
|
||||
| `file` | mixed | yes | Artifacts file |
|
||||
|
||||
* `id` (required) - The ID of a build
|
||||
* `token` (required) - The build authorization token
|
||||
* `file` (required) - Artifacts file
|
||||
```
|
||||
curl -X POST "https://gitlab.example.com/ci/api/v1/builds/1234/artifacts" -F "token=build_t0k3n" -F "file=@/path/to/file"
|
||||
```
|
||||
|
||||
### Download the artifacts file from build
|
||||
|
||||
GET /ci/api/v1/builds/:id/artifacts
|
||||
```
|
||||
GET /ci/api/v1/builds/:id/artifacts
|
||||
```
|
||||
|
||||
Parameters:
|
||||
| Attribute | Type | Required | Description |
|
||||
|-----------|---------|----------|-------------------------------|
|
||||
| `id` | integer | yes | The ID of a build |
|
||||
| `token` | string | yes | The build authorization token |
|
||||
|
||||
* `id` (required) - The ID of a build
|
||||
* `token` (required) - The build authorization token
|
||||
```
|
||||
curl "https://gitlab.example.com/ci/api/v1/builds/1234/artifacts" -F "token=build_t0k3n"
|
||||
```
|
||||
|
||||
### Remove the artifacts file from build
|
||||
|
||||
DELETE /ci/api/v1/builds/:id/artifacts
|
||||
```
|
||||
DELETE /ci/api/v1/builds/:id/artifacts
|
||||
```
|
||||
|
||||
Parameters:
|
||||
| Attribute | Type | Required | Description |
|
||||
|-----------|---------|----------|-------------------------------|
|
||||
| ` id` | integer | yes | The ID of a build |
|
||||
| `token` | string | yes | The build authorization token |
|
||||
|
||||
* ` id` (required) - The ID of a build
|
||||
* `token` (required) - The build authorization token
|
||||
```
|
||||
curl -X DELETE "https://gitlab.example.com/ci/api/v1/builds/1234/artifacts" -F "token=build_t0k3n"
|
||||
```
|
||||
|
|
|
@ -57,7 +57,8 @@ module Ci
|
|||
# Body:
|
||||
# content of logs to append
|
||||
# Headers:
|
||||
# Content-Range: range of conntent that was sent
|
||||
# Content-Range (required) - range of conntent that was sent
|
||||
# BUILD-TOKEN (required) - The build authorization token
|
||||
# Example Request:
|
||||
# PATCH /builds/:id/trace.txt
|
||||
patch ":id/trace.txt" do
|
||||
|
|
Loading…
Reference in New Issue