Update CI API docs
- Move ci/api under api/ci - Clean up builds.md and runners.md - Replace old links with new ones - Add CI API links in ci/README.md
This commit is contained in:
Achilleas Pipinellis
parent
4b964011cf
commit
47c9b7d34c
8 changed files with 249 additions and 223 deletions
|
|
@ -8,32 +8,39 @@ under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api).
|
||||||
Documentation for various API resources can be found separately in the
|
Documentation for various API resources can be found separately in the
|
||||||
following locations:
|
following locations:
|
||||||
|
|
||||||
- [Users](users.md)
|
|
||||||
- [Session](session.md)
|
|
||||||
- [Projects](projects.md) including setting Webhooks
|
|
||||||
- [Project Snippets](project_snippets.md)
|
|
||||||
- [Services](services.md)
|
|
||||||
- [Repositories](repositories.md)
|
|
||||||
- [Repository Files](repository_files.md)
|
|
||||||
- [Commits](commits.md)
|
|
||||||
- [Tags](tags.md)
|
|
||||||
- [Branches](branches.md)
|
- [Branches](branches.md)
|
||||||
- [Merge Requests](merge_requests.md)
|
|
||||||
- [Issues](issues.md)
|
|
||||||
- [Labels](labels.md)
|
|
||||||
- [Milestones](milestones.md)
|
|
||||||
- [Notes](notes.md) (comments)
|
|
||||||
- [Deploy Keys](deploy_keys.md)
|
|
||||||
- [System Hooks](system_hooks.md)
|
|
||||||
- [Groups](groups.md)
|
|
||||||
- [Namespaces](namespaces.md)
|
|
||||||
- [Settings](settings.md)
|
|
||||||
- [Keys](keys.md)
|
|
||||||
- [Builds](builds.md)
|
- [Builds](builds.md)
|
||||||
- [Build triggers](build_triggers.md)
|
- [Build triggers](build_triggers.md)
|
||||||
- [Build Variables](build_variables.md)
|
- [Build Variables](build_variables.md)
|
||||||
- [Runners](runners.md)
|
- [Commits](commits.md)
|
||||||
|
- [Deploy Keys](deploy_keys.md)
|
||||||
|
- [Groups](groups.md)
|
||||||
|
- [Issues](issues.md)
|
||||||
|
- [Keys](keys.md)
|
||||||
|
- [Labels](labels.md)
|
||||||
|
- [Merge Requests](merge_requests.md)
|
||||||
|
- [Milestones](milestones.md)
|
||||||
- [Open source license templates](licenses.md)
|
- [Open source license templates](licenses.md)
|
||||||
|
- [Namespaces](namespaces.md)
|
||||||
|
- [Notes](notes.md) (comments)
|
||||||
|
- [Projects](projects.md) including setting Webhooks
|
||||||
|
- [Project Snippets](project_snippets.md)
|
||||||
|
- [Repositories](repositories.md)
|
||||||
|
- [Repository Files](repository_files.md)
|
||||||
|
- [Runners](runners.md)
|
||||||
|
- [Services](services.md)
|
||||||
|
- [Session](session.md)
|
||||||
|
- [Settings](settings.md)
|
||||||
|
- [System Hooks](system_hooks.md)
|
||||||
|
- [Tags](tags.md)
|
||||||
|
- [Users](users.md)
|
||||||
|
|
||||||
|
### Internal CI API
|
||||||
|
|
||||||
|
The following documentation is for the [internal CI API](ci/README.md):
|
||||||
|
|
||||||
|
- [Builds](ci/builds.md)
|
||||||
|
- [Runners](ci/runners.md)
|
||||||
|
|
||||||
## Authentication
|
## Authentication
|
||||||
|
|
||||||
|
|
|
||||||
22
doc/api/ci/README.md
Normal file
22
doc/api/ci/README.md
Normal file
|
|
@ -0,0 +1,22 @@
|
||||||
|
# GitLab CI API
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Main purpose of GitLab CI API is to provide necessary data and context for
|
||||||
|
GitLab CI Runners.
|
||||||
|
|
||||||
|
For consumer API take a look at this [documentation](../../api/README.md) where
|
||||||
|
you will find all relevant information.
|
||||||
|
|
||||||
|
## API Prefix
|
||||||
|
|
||||||
|
Current CI API prefix is `/ci/api/v1`.
|
||||||
|
|
||||||
|
You need to prepend this prefix to all examples in this documentation, like:
|
||||||
|
|
||||||
|
GET /ci/api/v1/builds/:id/artifacts
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
- [Builds](builds.md)
|
||||||
|
- [Runners](runners.md)
|
||||||
138
doc/api/ci/builds.md
Normal file
138
doc/api/ci/builds.md
Normal file
|
|
@ -0,0 +1,138 @@
|
||||||
|
# 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
|
||||||
|
[Builds API](../builds.md).
|
||||||
|
|
||||||
|
## 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 |
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
| 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 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 |
|
||||||
|
|
||||||
|
```
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
| Attribute | Type | Required | Description |
|
||||||
|
|-----------|---------|----------|-------------------------------|
|
||||||
|
| `id` | integer | yes | The ID of a build |
|
||||||
|
| `token` | string | yes | The build authorization token |
|
||||||
|
| `file` | mixed | yes | 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
|
||||||
|
```
|
||||||
|
|
||||||
|
| Attribute | Type | Required | Description |
|
||||||
|
|-----------|---------|----------|-------------------------------|
|
||||||
|
| `id` | integer | yes | The ID of a build |
|
||||||
|
| `token` | string | yes | 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
|
||||||
|
```
|
||||||
|
|
||||||
|
| Attribute | Type | Required | Description |
|
||||||
|
|-----------|---------|----------|-------------------------------|
|
||||||
|
| ` id` | integer | yes | The ID of a build |
|
||||||
|
| `token` | string | yes | The build authorization token |
|
||||||
|
|
||||||
|
```
|
||||||
|
curl -X DELETE "https://gitlab.example.com/ci/api/v1/builds/1234/artifacts" -F "token=build_t0k3n"
|
||||||
|
```
|
||||||
57
doc/api/ci/runners.md
Normal file
57
doc/api/ci/runners.md
Normal file
|
|
@ -0,0 +1,57 @@
|
||||||
|
# Runners API
|
||||||
|
|
||||||
|
API used by Runners to register and delete themselves.
|
||||||
|
|
||||||
|
>**Note:**
|
||||||
|
This API is intended to be used only by Runners as their own
|
||||||
|
communication channel. For the consumer API see the
|
||||||
|
[new Runners API](../runners.md).
|
||||||
|
|
||||||
|
## 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 Runners' registration token.
|
||||||
|
This is a token that can be found in project's settings.
|
||||||
|
It can also be found in the **Admin > Runners** settings area.
|
||||||
|
There are two types of tokens you can pass: shared Runner registration
|
||||||
|
token or project specific registration token.
|
||||||
|
|
||||||
|
## Register a new runner
|
||||||
|
|
||||||
|
Used to make GitLab CI aware of available runners.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
POST /ci/api/v1/runners/register
|
||||||
|
```
|
||||||
|
|
||||||
|
| Attribute | Type | Required | Description |
|
||||||
|
| --------- | ------- | --------- | ----------- |
|
||||||
|
| `token` | string | yes | Runner's registration token |
|
||||||
|
|
||||||
|
Example request:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -X POST "https://gitlab.example.com/ci/api/v1/runners/register" -F "token=t0k3n"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Delete a Runner
|
||||||
|
|
||||||
|
Used to remove a Runner.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
DELETE /ci/api/v1/runners/delete
|
||||||
|
```
|
||||||
|
|
||||||
|
| Attribute | Type | Required | Description |
|
||||||
|
| --------- | ------- | --------- | ----------- |
|
||||||
|
| `token` | string | yes | Runner's registration token |
|
||||||
|
|
||||||
|
Example request:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -X DELETE "https://gitlab.example.com/ci/api/v1/runners/delete" -F "token=t0k3n"
|
||||||
|
```
|
||||||
|
|
@ -14,5 +14,5 @@
|
||||||
- [Trigger builds through the API](triggers/README.md)
|
- [Trigger builds through the API](triggers/README.md)
|
||||||
- [Build artifacts](build_artifacts/README.md)
|
- [Build artifacts](build_artifacts/README.md)
|
||||||
- [User permissions](permissions/README.md)
|
- [User permissions](permissions/README.md)
|
||||||
- [API](api/README.md)
|
- [API](../../api/ci/README.md)
|
||||||
- [CI services (linked docker containers)](services/README.md)
|
- [CI services (linked docker containers)](services/README.md)
|
||||||
|
|
|
||||||
|
|
@ -1,22 +1,3 @@
|
||||||
# GitLab CI API
|
# GitLab CI API
|
||||||
|
|
||||||
## Purpose
|
This document was moved to a [new location](../../api/ci/README.md).
|
||||||
|
|
||||||
Main purpose of GitLab CI API is to provide necessary data and context for
|
|
||||||
GitLab CI Runners.
|
|
||||||
|
|
||||||
For consumer API take a look at this [documentation](../../api/README.md) where
|
|
||||||
you will find all relevant information.
|
|
||||||
|
|
||||||
## API Prefix
|
|
||||||
|
|
||||||
Current CI API prefix is `/ci/api/v1`.
|
|
||||||
|
|
||||||
You need to prepend this prefix to all examples in this documentation, like:
|
|
||||||
|
|
||||||
GET /ci/api/v1/builds/:id/artifacts
|
|
||||||
|
|
||||||
## Resources
|
|
||||||
|
|
||||||
- [Builds](builds.md)
|
|
||||||
- [Runners](runners.md)
|
|
||||||
|
|
|
||||||
|
|
@ -1,139 +1,3 @@
|
||||||
# Builds API
|
# Builds API
|
||||||
|
|
||||||
API used by runners to receive and update builds.
|
This document was moved to a [new location](../../api/ci/builds.md).
|
||||||
|
|
||||||
_**Note:** This API is intended to be used only by Runners as their own
|
|
||||||
communication channel. For the consumer API see the
|
|
||||||
[Builds API](../../api/builds.md)._
|
|
||||||
|
|
||||||
## Authentication
|
|
||||||
|
|
||||||
This API uses two types of authentication:
|
|
||||||
|
|
||||||
1. Unique runner's token
|
|
||||||
|
|
||||||
Token assigned to runner after it has been registered.
|
|
||||||
|
|
||||||
2. Using build authorization token
|
|
||||||
|
|
||||||
This is project's CI token that can be found in Continuous Integration
|
|
||||||
project settings.
|
|
||||||
|
|
||||||
Build authorization token can be passed as a parameter or a value of
|
|
||||||
`BUILD-TOKEN` header. This method 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 |
|
|
||||||
|
|
||||||
|
|
||||||
```
|
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
| 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 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 |
|
|
||||||
|
|
||||||
```
|
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
| Attribute | Type | Required | Description |
|
|
||||||
|-----------|---------|----------|-------------------------------|
|
|
||||||
| `id` | integer | yes | The ID of a build |
|
|
||||||
| `token` | string | yes | The build authorization token |
|
|
||||||
| `file` | mixed | yes | 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
|
|
||||||
```
|
|
||||||
|
|
||||||
| Attribute | Type | Required | Description |
|
|
||||||
|-----------|---------|----------|-------------------------------|
|
|
||||||
| `id` | integer | yes | The ID of a build |
|
|
||||||
| `token` | string | yes | 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
|
|
||||||
```
|
|
||||||
|
|
||||||
| Attribute | Type | Required | Description |
|
|
||||||
|-----------|---------|----------|-------------------------------|
|
|
||||||
| ` id` | integer | yes | The ID of a build |
|
|
||||||
| `token` | string | yes | The build authorization token |
|
|
||||||
|
|
||||||
```
|
|
||||||
curl -X DELETE "https://gitlab.example.com/ci/api/v1/builds/1234/artifacts" -F "token=build_t0k3n"
|
|
||||||
```
|
|
||||||
|
|
|
||||||
|
|
@ -1,46 +1,3 @@
|
||||||
# Runners API
|
# Runners API
|
||||||
|
|
||||||
API used by runners to register and delete themselves.
|
This document was moved to a [new location](../../api/ci/runners.md).
|
||||||
|
|
||||||
_**Note:** This API is intended to be used only by Runners as their own
|
|
||||||
communication channel. For the consumer API see the
|
|
||||||
[new Runners API](../../api/runners.md)._
|
|
||||||
|
|
||||||
## Authentication
|
|
||||||
|
|
||||||
This API uses two types of authentication:
|
|
||||||
|
|
||||||
1. Unique runner's token
|
|
||||||
|
|
||||||
Token assigned to runner after it has been registered.
|
|
||||||
|
|
||||||
2. Using runners' registration token
|
|
||||||
|
|
||||||
This is a token that can be found in project's settings.
|
|
||||||
It can be also found in Admin area » Runners settings.
|
|
||||||
|
|
||||||
There are two types of tokens you can pass - shared runner registration
|
|
||||||
token or project specific registration token.
|
|
||||||
|
|
||||||
## Runners
|
|
||||||
|
|
||||||
### Register a new runner
|
|
||||||
|
|
||||||
Used to make GitLab CI aware of available runners.
|
|
||||||
|
|
||||||
POST /ci/api/v1/runners/register
|
|
||||||
|
|
||||||
Parameters:
|
|
||||||
|
|
||||||
* `token` (required) - Registration token
|
|
||||||
|
|
||||||
|
|
||||||
### Delete a runner
|
|
||||||
|
|
||||||
Used to remove runner.
|
|
||||||
|
|
||||||
DELETE /ci/api/v1/runners/delete
|
|
||||||
|
|
||||||
Parameters:
|
|
||||||
|
|
||||||
* `token` (required) - Unique runner token
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue