Skip to content

G
gitlab-ce
Commit a19a9fab authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Merge branch 'doc/ci-api-update' into 'master' 

Deprecated GitLab CI API clean up

Deprecated GitLab CI API clean up.

The intent here is to clean up deprecated GitLab CI documentation leaving only relevant information.
Since we merged `Ci::Project` to `Project` most of this documentation is outdated.

Closes #13610 

See merge request !3003
parents 75a67ac0 74b96326
Hide whitespace changes
Inline Side-by-side
Showing with 84 additions and 453 deletions
doc/api/commits.md
View file @ a19a9fab
......@@ -213,8 +213,7 @@ Example response:
## Commit status
Since GitLab 8.1, this is the new commit status API. The documentation in
[ci/api/commits](../ci/api/commits.md) is deprecated.
Since GitLab 8.1, this is the new commit status API.
### Get the status of a commit
......
doc/ci/api/README.md
View file @ a19a9fab
# GitLab CI API
## Resources
- [Projects](projects.md)
- [Runners](runners.md)
- [Commits](commits.md)
- [Builds](builds.md)
## Authentication
GitLab CI API uses different types of authentication depends on what API you use.
Each API document has section with information about authentication you need to use.
GitLab CI API has 4 authentication methods:
* GitLab user token & GitLab url
* GitLab CI project token
* GitLab CI runners registration token
* GitLab CI runner token
### Authentication #1: GitLab user token & GitLab url
Authentication is done by
sending the `private-token` of a valid user and the `url` of an
authorized GitLab instance via a query string along with the API
request:
GET http://gitlab.example.com/ci/api/v1/projects?private_token=QVy1PB7sTxfy4pqfZM1U&url=http://demo.gitlab.com/
## Purpose
If preferred, you may instead send the `private-token` as a header in
your request:
Main purpose of GitLab CI API is to provide necessary data and context for
GitLab CI Runners.
curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://gitlab.example.com/ci/api/v1/projects?url=http://demo.gitlab.com/"
For consumer API take a look at this [documentation](../../api/README.md) where
you will find all relevant information.
## API Prefix
### Authentication #2: GitLab CI project token
Current CI API prefix is `/ci/api/v1`.
Each project in GitLab CI has it own token.
It can be used to get project commits and builds information.
You can use project token only for certain project.
You need to prepend this prefix to all examples in this documentation, like:
### Authentication #3: GitLab CI runners registration token
GET /ci/api/v1/builds/:id/artifacts
This token is not persisted and is generated on each application start.
It can be used only for registering new runners in system. You can find it on
GitLab CI Runners web page https://gitlab-ci.example.com/admin/runners
### Authentication #4: GitLab CI runner token
Every GitLab CI runner has it own token that allow it to receive and update
GitLab CI builds. This token exists of internal purposes and should be used only
by runners
## JSON
All API requests are serialized using JSON. You don't need to specify
`.json` at the end of API URL.
## Status codes
The API is designed to return different status codes according to context and action. In this way if a request results in an error the caller is able to get insight into what went wrong, e.g. status code `400 Bad Request` is returned if a required attribute is missing from the request. The following list gives an overview of how the API functions generally behave.
API request types:
- `GET` requests access one or more resources and return the result as JSON
- `POST` requests return `201 Created` if the resource is successfully created and return the newly created resource as JSON
- `GET`, `PUT` and `DELETE` return `200 OK` if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON
- `DELETE` requests are designed to be idempotent, meaning a request a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind it is the user is not really interested if the resource existed before or not.
The following list shows the possible return codes for API requests.
Return values:
## Resources
- `200 OK` - The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON
- `201 Created` - The `POST` request was successful and the resource is returned as JSON
- `400 Bad Request` - A required attribute of the API request is missing, e.g. the title of an issue is not given
- `401 Unauthorized` - The user is not authenticated, a valid user token is necessary, see above
- `403 Forbidden` - The request is not allowed, e.g. the user is not allowed to delete a project
- `404 Not Found` - A resource could not be accessed, e.g. an ID for a resource could not be found
- `405 Method Not Allowed` - The request is not supported
- `409 Conflict` - A conflicting resource already exists, e.g. creating a project with a name that already exists
- `422 Unprocessable` - The entity could not be processed
- `500 Server Error` - While handling the request something went wrong on the server side
- [Builds](builds.md)
- [Runners](runners.md)
doc/ci/api/builds.md
View file @ a19a9fab
# Builds API
This API used by runners to receive and update builds.
API used by runners to receive and update builds.
__Authentication is done by runner token__
_**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/builds/register
POST /ci/api/v1/builds/register
Parameters:
* `token` (required) - The unique token of runner
Returns:
```json
{
"id": 48584,
"ref": "0.1.1",
"tag": true,
"sha": "d63117656af6ff57d99e50cc270f854691f335ad",
"status": "success",
"name": "pages",
"token": "9dd60b4f1a439d1765357446c1084c",
"stage": "test",
"project_id": 479,
"project_name": "test",
"commands": "echo commands",
"repo_url": "http://gitlab-ci-token:token@gitlab.example/group/test.git",
"before_sha": "0000000000000000000000000000000000000000",
"allow_git_fetch": false,
"options": {
"image": "docker:image",
"artifacts": {
"paths": [
"public"
]
},
"cache": {
"paths": [
"vendor"
]
}
},
"timeout": 3600,
"variables": [
{
"key": "CI_BUILD_TAG",
"value": "0.1.1",
"public": true
}
],
"depends_on_builds": [
{
"id": 48584,
"ref": "0.1.1",
"tag": true,
"sha": "d63117656af6ff57d99e50cc270f854691f335ad",
"status": "success",
"name": "build",
"token": "9dd60b4f1a439d1765357446c1084c",
"stage": "build",
"project_id": 479,
"project_name": "test",
"artifacts_file": {
"filename": "artifacts.zip",
"size": 0
}
}
]
}
```
* `token` (required) - Unique runner token
### Update details of an existing build
PUT /ci/builds/:id
PUT /ci/api/v1/builds/:id
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
### Upload artifacts to build
POST /ci/api/v1/builds/:id/artifacts
Parameters:
* `id` (required) - The ID of a build
* `token` (required) - The build authorization token
* `file` (required) - Artifacts file
### Download the artifacts file from build
GET /ci/api/v1/builds/:id/artifacts
Parameters:
* `id` (required) - The ID of a build
* `token` (required) - The build authorization token
### Remove the artifacts file from build
DELETE /ci/api/v1/builds/:id/artifacts
Parameters:
* ` id` (required) - The ID of a build
* `token` (required) - The build authorization token
doc/ci/api/commits.md deleted 100644 → 0
View file @ 75a67ac0
# Commits API
**DEPRECATED**
Since GitLab 8.1, there is a new commit status API. Please see the [revised
documentation](../../api/commits.md#commit-status).
---
__Authentication is done by GitLab CI project token__
## Commits
### Retrieve all commits per project
Get list of commits per project
GET /ci/commits
Parameters:
* `project_id` (required) - The ID of a project
* `project_token` (requires) - Project token
* `page` (optional)
* `per_page` (optional) - items per request (default is 20)
Returns:
```json
[{
"id": 3,
"ref": "master",
"sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
"project_id": 2,
"before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
"created_at": "2014-11-05T09:46:35.247Z",
"status": "success",
"finished_at": "2014-11-05T09:46:44.254Z",
"duration": 5.062692165374756,
"git_commit_message": "wow\n",
"git_author_name": "Administrator",
"git_author_email": "admin@example.com",
"builds": [{
"id": 7,
"project_id": 2,
"ref": "master",
"status": "success",
"finished_at": "2014-11-05T09:46:44.254Z",
"created_at": "2014-11-05T09:46:35.259Z",
"updated_at": "2014-11-05T09:46:44.255Z",
"sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
"started_at": "2014-11-05T09:46:39.192Z",
"before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
"runner_id": 1,
"coverage": null,
"commit_id": 3
}]
}]
```
### Create commit
Inform GitLab CI about new commit you want it to build.
__If commit already exists in GitLab CI it will not be created__
POST /ci/commits
Parameters:
* `project_id` (required) - The ID of a project
* `project_token` (requires) - Project token
* `data` (required) - Push data. For example see comment in `lib/api/commits.rb`
Returns:
```json
{
"id": 3,
"ref": "master",
"sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
"project_id": 2,
"before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
"created_at": "2014-11-05T09:46:35.247Z",
"status": "success",
"finished_at": "2014-11-05T09:46:44.254Z",
"duration": 5.062692165374756,
"git_commit_message": "wow\n",
"git_author_name": "Administrator",
"git_author_email": "admin@example.com",
"builds": [{
"id": 7,
"project_id": 2,
"ref": "master",
"status": "success",
"finished_at": "2014-11-05T09:46:44.254Z",
"created_at": "2014-11-05T09:46:35.259Z",
"updated_at": "2014-11-05T09:46:44.255Z",
"sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
"started_at": "2014-11-05T09:46:39.192Z",
"before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
"runner_id": 1,
"coverage": null,
"commit_id": 3
}]
}
```
doc/ci/api/projects.md deleted 100644 → 0
View file @ 75a67ac0
# Projects API
This API is intended to aid in the setup and configuration of
projects on GitLab CI.
__Authentication is done by GitLab user token & GitLab url__
## Projects
### List Authorized Projects
Lists all projects that the authenticated user has access to.
```
GET /ci/projects
```
Returns:
```json
[
{
"id" : 271,
"name" : "gitlabhq",
"timeout" : 1800,
"token" : "iPWx6WM4lhHNedGfBpPJNP",
"default_ref" : "master",
"gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell",
"path" : "gitlab/gitlab-shell",
"always_build" : false,
"polling_interval" : null,
"public" : false,
"ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
"gitlab_id" : 3
},
{
"id" : 272,
"name" : "gitlab-ci",
"timeout" : 1800,
"token" : "iPWx6WM4lhHNedGfBpPJNP",
"default_ref" : "master",
"gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell",
"path" : "gitlab/gitlab-shell",
"always_build" : false,
"polling_interval" : null,
"public" : false,
"ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
"gitlab_id" : 4
}
]
```
### List Owned Projects
Lists all projects that the authenticated user owns.
```
GET /ci/projects/owned
```
Returns:
```json
[
{
"id" : 272,
"name" : "gitlab-ci",
"timeout" : 1800,
"token" : "iPWx6WM4lhHNedGfBpPJNP",
"default_ref" : "master",
"gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell",
"path" : "gitlab/gitlab-shell",
"always_build" : false,
"polling_interval" : null,
"public" : false,
"ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
"gitlab_id" : 4
}
]
```
### Single Project
Returns information about a single project for which the user is
authorized.
GET /ci/projects/:id
Parameters:
* `id` (required) - The ID of the GitLab CI project
### Create Project
Creates a GitLab CI project using GitLab project details.
POST /ci/projects
Parameters:
* `name` (required) - The name of the project
* `gitlab_id` (required) - The ID of the project on the GitLab instance
* `default_ref` (optional) - The branch to run on (default to `master`)
### Update Project
Updates a GitLab CI project using GitLab project details that the
authenticated user has access to.
PUT /ci/projects/:id
Parameters:
* `name` - The name of the project
* `default_ref` - The branch to run on (default to `master`)
### Remove Project
Removes a GitLab CI project that the authenticated user has access to.
DELETE /ci/projects/:id
Parameters:
* `id` (required) - The ID of the GitLab CI project
### Link Project to Runner
Links a runner to a project so that it can make builds (only via
authorized user).
POST /ci/projects/:id/runners/:runner_id
Parameters:
* `id` (required) - The ID of the GitLab CI project
* `runner_id` (required) - The ID of the GitLab CI runner
### Remove Project from Runner
Removes a runner from a project so that it can not make builds (only
via authorized user).
DELETE /ci/projects/:id/runners/:runner_id
Parameters:
* `id` (required) - The ID of the GitLab CI project
* `runner_id` (required) - The ID of the GitLab CI runner
\ No newline at end of file
doc/ci/api/runners.md
View file @ a19a9fab
# 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](../../api/runners.md)._
## Runners
### Retrieve all runners
## Authentication
__Authentication is done by GitLab user token & GitLab url__
This API uses two types of authentication:
Used to get information about all runners registered on the GitLab CI
instance.
1. Unique runner's token
GET /ci/runners
Token assigned to runner after it has been registered.
Returns:
2. Using runners' registration token
```json
[
{
"id" : 85,
"token" : "12b68e90394084703135"
},
{
"id" : 86,
"token" : "76bf894e969364709864"
},
]
```
This is a token that can be found in project's settings.
It can be also found in Admin area » Runners settings.
### Register a new runner
There are two types of tokens you can pass - shared runner registration
token or project specific registration token.
## Runners
__Authentication is done with a Shared runner registration token or a project Specific runner registration token__
### Register a new runner
Used to make GitLab CI aware of available runners.
POST /ci/runners/register
POST /ci/api/v1/runners/register
Parameters:
* `token` (required) - The registration token. It is 2 types of token you can pass here.
* `token` (required) - Registration token
1. Shared runner registration token
2. Project specific registration token
Returns:
```json
{
"id" : 85,
"token" : "12b68e90394084703135"
}
```
### Delete a runner
Used to remove runner.
__Authentication is done by runner token__
Used to removing runners.
DELETE /ci/runners/delete
DELETE /ci/api/v1/runners/delete
Parameters:
* `token` (required) - The runner token.
Returns:
```json
{
"id" : 1,
"token" : "d14963981a428f70121777e50643d1",
"created_at" : "2015-02-26T11:39:39.232Z",
"updated_at" : "2015-02-26T11:39:39.232Z",
"description" : "awesome runner"
}
```
* `token` (required) - Unique runner token
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7