diff options
Diffstat (limited to 'doc/ci/api')
| -rw-r--r-- | doc/ci/api/README.md | 87 | ||||
| -rw-r--r-- | doc/ci/api/builds.md | 41 | ||||
| -rw-r--r-- | doc/ci/api/commits.md | 101 | ||||
| -rw-r--r-- | doc/ci/api/forks.md | 23 | ||||
| -rw-r--r-- | doc/ci/api/projects.md | 154 | ||||
| -rw-r--r-- | doc/ci/api/runners.md | 77 |
6 files changed, 483 insertions, 0 deletions
diff --git a/doc/ci/api/README.md b/doc/ci/api/README.md new file mode 100644 index 00000000000..95fe2f837a5 --- /dev/null +++ b/doc/ci/api/README.md @@ -0,0 +1,87 @@ +# GitLab CI API + +## Resources + +- [Projects](projects.md) +- [Runners](runners.md) +- [Commits](commits.md) +- [Builds](builds.md) +- [Forks](forks.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://ci.example.com/api/v1/projects?private_token=QVy1PB7sTxfy4pqfZM1U&url=http://demo.gitlab.com/ + +If preferred, you may instead send the `private-token` as a header in +your request: + + curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://ci.example.com/api/v1/projects?url=http://demo.gitlab.com/" + + +### Authentication #2: GitLab CI project token + +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. + +### Authentication #3: GitLab CI runners registration token + +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: + +- `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 diff --git a/doc/ci/api/builds.md b/doc/ci/api/builds.md new file mode 100644 index 00000000000..54749bc6fa1 --- /dev/null +++ b/doc/ci/api/builds.md @@ -0,0 +1,41 @@ +# Builds API + +This API used by runners to receive and update builds. + +__Authentication is done by runner token__ + +## Builds + +### Runs oldest pending build by runner + + POST /builds/register + +Parameters: + + * `token` (required) - The unique token of runner + +Returns: + +```json +{ + "id" : 79, + "commands" : "", + "path" : "", + "ref" : "", + "sha" : "", + "project_id" : 6, + "repo_url" : "git@demo.gitlab.com:gitlab/gitlab-shell.git", + "before_sha" : "" +} +``` + + +### Update details of an existing build + + PUT /builds/:id + +Parameters: + + * `id` (required) - The ID of a project + * `state` (optional) - The state of a build + * `trace` (optional) - The trace of a build diff --git a/doc/ci/api/commits.md b/doc/ci/api/commits.md new file mode 100644 index 00000000000..0015a62a38f --- /dev/null +++ b/doc/ci/api/commits.md @@ -0,0 +1,101 @@ +# Commits API + +__Authentication is done by GitLab CI project token__ + +## Commits + +### Retrieve all commits per project + +Get list of commits per project + + GET /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 /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 + }] +} +``` diff --git a/doc/ci/api/forks.md b/doc/ci/api/forks.md new file mode 100644 index 00000000000..1a5ea8041d8 --- /dev/null +++ b/doc/ci/api/forks.md @@ -0,0 +1,23 @@ +# Forks API + +This API is intended to aid in the setup and configuration of +forked projects on Gitlab CI. + +__Authentication is done by GitLab user token & GitLab project token__ + +## Forks + +### Create fork for project + + + +``` +POST /forks +``` + +Parameters: + + project_id (required) - The ID of a project + project_token (requires) - Project token + private_token(required) - User private token + data (required) - GitLab project data (name_with_namespace, web_url, default_branch, ssh_url_to_repo) diff --git a/doc/ci/api/projects.md b/doc/ci/api/projects.md new file mode 100644 index 00000000000..c24d48f829f --- /dev/null +++ b/doc/ci/api/projects.md @@ -0,0 +1,154 @@ +# 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 /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 /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 /projects/:id + +Parameters: + + * `id` (required) - The ID of the Gitlab CI project + +### Create Project + +Creates a Gitlab CI project using Gitlab project details. + + POST /projects + +Parameters: + + * `name` (required) - The name of the project + * `gitlab_id` (required) - The ID of the project on the Gitlab instance + * `path` (required) - The gitlab project path + * `ssh_url_to_repo` (required) - The gitlab SSH url to the repo + * `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 /projects/:id + +Parameters: + + * `name` - The name of the project + * `gitlab_id` - The ID of the project on the Gitlab instance + * `path` - The gitlab project path + * `ssh_url_to_repo` - The gitlab SSH url to the repo + * `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 /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 /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 /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 diff --git a/doc/ci/api/runners.md b/doc/ci/api/runners.md new file mode 100644 index 00000000000..68b5851617a --- /dev/null +++ b/doc/ci/api/runners.md @@ -0,0 +1,77 @@ +# Runners API + +## Runners + +### Retrieve all runners + +__Authentication is done by GitLab user token & GitLab url__ + +Used to get information about all runners registered on the Gitlab CI +instance. + + GET /runners + +Returns: + +```json +[ + { + "id" : 85, + "token" : "12b68e90394084703135" + }, + { + "id" : 86, + "token" : "76bf894e969364709864" + }, +] +``` + +### Register a new runner + + +__Authentication is done with a Shared runner registration token or a project Specific runner registration token__ + +Used to make Gitlab CI aware of available runners. + + POST /runners/register + +Parameters: + + * `token` (required) - The registration token. It is 2 types of token you can pass here. + +1. Shared runner registration token +2. Project specific registration token + +Returns: + +```json +{ + "id" : 85, + "token" : "12b68e90394084703135" +} +``` + +### Delete a runner + + +__Authentication is done by runner token__ + +Used to removing runners. + + DELETE /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" +} +```
\ No newline at end of file |