BigW Consortium Gitlab

builds.md 5.26 KB
Newer Older
1 2 3 4 5 6 7
# Builds API

API used by runners to receive and update builds.

>**Note:**
This API is intended to be used only by Runners as their own
communication channel. For the consumer API see the
8
[Jobs API](../jobs.md).
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37

## Authentication

This API uses two types of authentication:

1. Unique Runner's token which is the token assigned to the Runner after it
   has been registered.

2. Using the build authorization token.
   This is project's CI token that can be found under the **Builds** section of
   a project's settings. The build authorization token can be passed as a
   parameter or a value of `BUILD-TOKEN` header.

These two methods of authentication are interchangeable.

## Builds

### Runs oldest pending build by runner

```
POST /ci/api/v1/builds/register
```

| Attribute | Type    | Required | Description         |
|-----------|---------|----------|---------------------|
| `token`   | string  | yes      | Unique runner token |


```
38
curl --request POST "https://gitlab.example.com/ci/api/v1/builds/register" --form "token=t0k3n"
39 40
```

41 42 43 44 45 46
**Responses:**

| Status | Data |Description                                                                |
|--------|------|---------------------------------------------------------------------------|
| `201`  | yes  | When a build is scheduled for a runner                                    |
| `204`  | no   | When no builds are scheduled for a runner (for GitLab Runner >= `v1.3.0`) |
47
| `403`  | no   | When invalid token is used or no token is sent                            |
48 49
| `404`  | no   | When no builds are scheduled for a runner (for GitLab Runner < `v1.3.0`) **or** when the runner is set to `paused` in GitLab runner's configuration page |

50 51 52 53 54 55 56 57 58 59 60 61 62 63
### Update details of an existing build

```
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 |

```
64
curl --request PUT "https://gitlab.example.com/ci/api/v1/builds/1234" --form "token=t0k3n" --form "state=running" --form "trace=Running git clone...\n"
65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98
```

### Incremental build trace update

Using this method you need to send trace content as a request body. You also need to provide the `Content-Range` header
with a range of sent trace part. Note that you need to send parts in the proper order, so the begining of the part
must start just after the end of the previous part. If you provide the wrong part, then GitLab CI API 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 contain a `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:

| 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 |

```
99
curl --request PATCH "https://gitlab.example.com/ci/api/v1/builds/1234/trace.txt" --header "BUILD-TOKEN=build_t0k3n" --header "Content-Range=0-21" --data "Running git clone...\n"
100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115
```


### Upload artifacts to build

```
POST /ci/api/v1/builds/:id/artifacts
```

| Attribute | Type    | Required | Description                   |
|-----------|---------|----------|-------------------------------|
| `id`      | integer | yes      | The ID of a build             |
| `token`   | string  | yes      | The build authorization token |
| `file`    | mixed   | yes      | Artifacts file                |

```
116
curl --request POST "https://gitlab.example.com/ci/api/v1/builds/1234/artifacts" --form "token=build_t0k3n" --form "file=@/path/to/file"
117 118 119 120 121 122 123 124 125 126 127 128 129 130
```

### Download the artifacts file from build

```
GET /ci/api/v1/builds/:id/artifacts
```

| Attribute | Type    | Required | Description                   |
|-----------|---------|----------|-------------------------------|
| `id`      | integer | yes      | The ID of a build             |
| `token`   | string  | yes      | The build authorization token |

```
131
curl "https://gitlab.example.com/ci/api/v1/builds/1234/artifacts" --form "token=build_t0k3n"
132 133 134 135 136 137 138 139 140 141 142 143 144 145
```

### Remove the artifacts file from build

```
DELETE /ci/api/v1/builds/:id/artifacts
```

| Attribute | Type    | Required | Description                   |
|-----------|---------|----------|-------------------------------|
| ` id`     | integer | yes      | The ID of a build             |
| `token`   | string  | yes      | The build authorization token |

```
146
curl --request DELETE "https://gitlab.example.com/ci/api/v1/builds/1234/artifacts" --form "token=build_t0k3n"
147
```