diff options
Diffstat (limited to 'doc/api')
| -rw-r--r-- | doc/api/README.md | 2 | ||||
| -rw-r--r-- | doc/api/access_requests.md | 2 | ||||
| -rw-r--r-- | doc/api/avatar.md | 33 | ||||
| -rw-r--r-- | doc/api/branches.md | 11 | ||||
| -rw-r--r-- | doc/api/commits.md | 1 | ||||
| -rw-r--r-- | doc/api/graphql/index.md | 40 | ||||
| -rw-r--r-- | doc/api/groups.md | 6 | ||||
| -rw-r--r-- | doc/api/members.md | 6 | ||||
| -rw-r--r-- | doc/api/merge_requests.md | 83 | ||||
| -rw-r--r-- | doc/api/namespaces.md | 2 | ||||
| -rw-r--r-- | doc/api/pages_domains.md | 8 | ||||
| -rw-r--r-- | doc/api/pipelines.md | 1 | ||||
| -rw-r--r-- | doc/api/projects.md | 12 | ||||
| -rw-r--r-- | doc/api/protected_branches.md | 18 | ||||
| -rw-r--r-- | doc/api/repositories.md | 1 | ||||
| -rw-r--r-- | doc/api/repository_files.md | 34 | ||||
| -rw-r--r-- | doc/api/runners.md | 12 | ||||
| -rw-r--r-- | doc/api/search.md | 9 | ||||
| -rw-r--r-- | doc/api/services.md | 2 | ||||
| -rw-r--r-- | doc/api/settings.md | 2 | ||||
| -rw-r--r-- | doc/api/snippets.md | 6 |
21 files changed, 227 insertions, 64 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index 1c756dc855f..6267618d3bc 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -104,7 +104,7 @@ with a major point release of GitLab itself. All deprecations and changes between two versions should be listed in the documentation. For the changes between v3 and v4; please read the [v3 to v4 documentation](v3_to_v4.md) -#### Current status +### Current status Currently only API version v4 is available. Version v3 was removed in [GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-ce/issues/36819). diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index 603fa4a8194..4b2014ca843 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -10,7 +10,7 @@ 10 => Guest access 20 => Reporter access 30 => Developer access -40 => Master access +40 => Maintainer access 50 => Owner access # Only valid for groups ``` diff --git a/doc/api/avatar.md b/doc/api/avatar.md new file mode 100644 index 00000000000..7faed893066 --- /dev/null +++ b/doc/api/avatar.md @@ -0,0 +1,33 @@ +# Avatar API + +> [Introduced][ce-19121] in GitLab 11.0 + +## Get a single avatar URL + +Get a single avatar URL for a given email addres. If user with matching public +email address is not found, results from external avatar services are returned. +This endpoint can be accessed without authentication. In case public visibility +is restricted, response will be `403 Forbidden` when unauthenticated. + +``` +GET /avatar?email=admin@example.com +``` + +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | --------------------- | +| `email` | string | yes | Public email address of the user | +| `size` | integer | no | Single pixel dimension (since images are squares). Only used for avatar lookups at `Gravatar` or at the configured `Libravatar` server | + +```bash +curl https://gitlab.example.com/api/v4/avatar?email=admin@example.com +``` + +Example response: + +```json +{ + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon" +} +``` + +[ce-19121]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19121 diff --git a/doc/api/branches.md b/doc/api/branches.md index 01bb30c3859..bfb21608d28 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -29,6 +29,7 @@ Example response: "protected": true, "developers_can_push": false, "developers_can_merge": false, + "can_push": true, "commit": { "author_email": "john@example.com", "author_name": "John Smith", @@ -76,6 +77,7 @@ Example response: "protected": true, "developers_can_push": false, "developers_can_merge": false, + "can_push": true, "commit": { "author_email": "john@example.com", "author_name": "John Smith", @@ -140,7 +142,8 @@ Example response: "merged": false, "protected": true, "developers_can_push": true, - "developers_can_merge": true + "developers_can_merge": true, + "can_push": true } ``` @@ -188,7 +191,8 @@ Example response: "merged": false, "protected": false, "developers_can_push": false, - "developers_can_merge": false + "developers_can_merge": false, + "can_push": true } ``` @@ -231,7 +235,8 @@ Example response: "merged": false, "protected": false, "developers_can_push": false, - "developers_can_merge": false + "developers_can_merge": false, + "can_push": true } ``` diff --git a/doc/api/commits.md b/doc/api/commits.md index d1584cf64de..d07b9d5614a 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -16,6 +16,7 @@ GET /projects/:id/repository/commits | `until` | string | no | Only commits before or on this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ | | `path` | string | no | The file path | | `all` | boolean | no | Retrieve every commit from the repository | +| `with_stats` | boolean | no | Stats about each commit will be added to the response | ```bash diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md new file mode 100644 index 00000000000..71922318227 --- /dev/null +++ b/doc/api/graphql/index.md @@ -0,0 +1,40 @@ +# GraphQL API (Alpha) + +> [Introduced][ce-19008] in GitLab 11.0. + +[GraphQL](https://graphql.org/) is a query language for APIs that +allows clients to request exactly the data they need, making it +possible to get all required data in a limited number of requests. + +The GraphQL data (fields) can be described in the form of types, +allowing clients to use [clientside GraphQL +libraries](https://graphql.org/code/#graphql-clients) to consume the +API and avoid manual parsing. + +Since there's no fixed endpoints and datamodel, new abilities can be +added to the API without creating breaking changes. This allows us to +have a versionless API as described in [the GraphQL +documentation](https://graphql.org/learn/best-practices/#versioning). + +## Enabling the GraphQL feature + +The GraphQL API itself is currently in Alpha, and therefore hidden behind a +feature flag. You can enable the feature using the [features api][features-api] on a self-hosted instance. + +For example: + +```shell +curl --data "value=100" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/features/graphql +``` + +## Available queries + +A first iteration of a GraphQL API includes a query for: `project`. Within a project it is also possible to fetch a `mergeRequest` by IID. + +## GraphiQL + +The API can be explored by using the GraphiQL IDE, it is available on your +instance on `gitlab.example.com/-/graphql-explorer`. + +[ce-19008]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19008 +[features-api]: ../features.md diff --git a/doc/api/groups.md b/doc/api/groups.md index 96842ef330f..53d72509423 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -12,7 +12,7 @@ Parameters: | `skip_groups` | array of integers | no | Skip the group IDs passed | | `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin) | | `search` | string | no | Return the list of authorized groups matching the search criteria | -| `order_by` | string | no | Order groups by `name` or `path`. Default is `name` | +| `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` | | `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | | `statistics` | boolean | no | Include group statistics (admins only) | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | @@ -96,7 +96,7 @@ Parameters: | `skip_groups` | array of integers | no | Skip the group IDs passed | | `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin) | | `search` | string | no | Return the list of authorized groups matching the search criteria | -| `order_by` | string | no | Order groups by `name` or `path`. Default is `name` | +| `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` | | `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | | `statistics` | boolean | no | Include group statistics (admins only) | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | @@ -147,6 +147,8 @@ Parameters: | `simple` | boolean | no | Return only the ID, URL, name, and path of each project | | `owned` | boolean | no | Limit by projects owned by the current user | | `starred` | boolean | no | Limit by projects starred by the current user | +| `with_issues_enabled` | boolean | no | Limit by enabled issues feature | +| `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | Example response: diff --git a/doc/api/members.md b/doc/api/members.md index 3234f833eae..8ebe464c359 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -8,7 +8,7 @@ The access levels are defined in the `Gitlab::Access` module. Currently, these l 10 => Guest access 20 => Reporter access 30 => Developer access -40 => Master access +40 => Maintainer access 50 => Owner access # Only valid for groups ``` @@ -173,3 +173,7 @@ DELETE /projects/:id/members/:user_id curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/members/:user_id curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/members/:user_id ``` + +## Give a group access to a project + +Look at [share project with group](projects.md#share-project-with-group) diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 051d2a10bc6..2057ed3588a 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -11,7 +11,7 @@ default it returns only merge requests created by the current user. To get all merge requests, use parameter `scope=all`. The `state` parameter can be used to get only merge requests with a -given state (`opened`, `closed`, or `merged`) or all of them (`all`). +given state (`opened`, `closed`, `locked`, or `merged`) or all of them (`all`). It should be noted that when searching by `locked` it will mostly return no results as it is a short-lived, transitional state. The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests. @@ -35,7 +35,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, or `merged` | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | | `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | | `milestone` | string | no | Return merge requests for a specific milestone | @@ -70,18 +70,18 @@ Parameters: "author": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 2, "target_project_id": 3, @@ -122,7 +122,7 @@ Parameters: ## List project merge requests Get all merge requests for this project. -The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, or `merged`) or all of them (`all`). +The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, `locked`, or `merged`) or all of them (`all`). The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests. ``` @@ -155,7 +155,7 @@ Parameters: | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `id` | integer | yes | The ID of a project | | `iids[]` | Array[integer] | no | Return the request having the given `iid` | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, or `merged` | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | | `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | | `milestone` | string | no | Return merge requests for a specific milestone | @@ -190,18 +190,18 @@ Parameters: "author": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 2, "target_project_id": 3, @@ -243,7 +243,7 @@ Parameters: ## List group merge requests Get all merge requests for this group and its subgroups. -The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, or `merged`) or all of them (`all`). +The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, `locked`, or `merged`) or all of them (`all`). The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests. ``` @@ -262,7 +262,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `id` | integer | yes | The ID of a group | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, or `merged` | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | | `order_by` | string | no | Return merge requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc` | | `milestone` | string | no | Return merge requests for a specific milestone | @@ -297,18 +297,18 @@ Parameters: "author": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 2, "target_project_id": 3, @@ -548,14 +548,16 @@ Parameters: "username": "jarrett", "id": 5, "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/b95567800f828948baf5f4160ebb2473?s=40&d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/b95567800f828948baf5f4160ebb2473?s=40&d=identicon", + "web_url" : "https://gitlab.example.com/jarrett" }, "assignee": { "name": "Administrator", "username": "root", "id": 1, "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40&d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40&d=identicon", + "web_url" : "https://gitlab.example.com/root" }, "source_project_id": 4, "target_project_id": 4, @@ -582,6 +584,7 @@ Parameters: "changes_count": "1", "should_remove_source_branch": true, "force_remove_source_branch": false, + "squash": false, "web_url": "http://example.com/example/example/merge_requests/1", "discussion_locked": false, "time_stats": { @@ -650,7 +653,8 @@ POST /projects/:id/merge_requests | `labels` | string | no | Labels for MR as a comma-separated list | | `milestone_id` | integer | no | The global ID of a milestone | | `remove_source_branch` | boolean | no | Flag indicating if a merge request should remove the source branch when merging | -| `allow_maintainer_to_push` | boolean | no | Whether or not a maintainer of the target project can push to the source branch | +| `allow_collaboration` | boolean | no | Allow commits from members who can merge to the target branch | +| `allow_maintainer_to_push` | boolean | no | Deprecated, see allow_collaboration | | `squash` | boolean | no | Squash commits into a single commit when merging | ```json @@ -667,18 +671,18 @@ POST /projects/:id/merge_requests "author": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 3, "target_project_id": 4, @@ -708,6 +712,7 @@ POST /projects/:id/merge_requests "squash": false, "web_url": "http://example.com/example/example/merge_requests/1", "discussion_locked": false, + "allow_collaboration": false, "allow_maintainer_to_push": false, "time_stats": { "time_estimate": 0, @@ -740,7 +745,8 @@ PUT /projects/:id/merge_requests/:merge_request_iid | `remove_source_branch` | boolean | no | Flag indicating if a merge request should remove the source branch when merging | | `squash` | boolean | no | Squash commits into a single commit when merging | | `discussion_locked` | boolean | no | Flag indicating if the merge request's discussion is locked. If the discussion is locked only project members can add, edit or resolve comments. | -| `allow_maintainer_to_push` | boolean | no | Whether or not a maintainer of the target project can push to the source branch | +| `allow_collaboration` | boolean | no | Allow commits from members who can merge to the target branch | +| `allow_maintainer_to_push` | boolean | no | Deprecated, see allow_collaboration | Must include at least one non-required attribute from above. @@ -757,18 +763,18 @@ Must include at least one non-required attribute from above. "author": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 3, "target_project_id": 4, @@ -798,6 +804,7 @@ Must include at least one non-required attribute from above. "squash": false, "web_url": "http://example.com/example/example/merge_requests/1", "discussion_locked": false, + "allow_collaboration": false, "allow_maintainer_to_push": false, "time_stats": { "time_estimate": 0, @@ -865,18 +872,18 @@ Parameters: "author": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 4, "target_project_id": 4, @@ -944,18 +951,18 @@ Parameters: "author": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, "username": "admin", - "email": "admin@example.com", "name": "Administrator", "state": "active", - "created_at": "2012-04-29T08:46:00Z" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 4, "target_project_id": 4, diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 1f0dc700640..656bf07bb55 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -54,7 +54,7 @@ Example response: ] ``` -**Note**: `members_count_with_descendants` are presented only for group masters/owners. +**Note**: `members_count_with_descendants` are presented only for group maintainers/owners. ## Search for namespace diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 20275b902c6..da2ffcfe40a 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -122,11 +122,11 @@ POST /projects/:id/pages/domains | `key` | file/string | no | The certificate key in PEM format. | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form="domain=ssl.domain.example" --form="certificate=@/path/to/cert.pem" --form="key=@/path/to/key.pem" https://gitlab.example.com/api/v4/projects/5/pages/domains +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "domain=ssl.domain.example" --form "certificate=@/path/to/cert.pem" --form "key=@/path/to/key.pem" https://gitlab.example.com/api/v4/projects/5/pages/domains ``` ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form="domain=ssl.domain.example" --form="certificate=$CERT_PEM" --form="key=$KEY_PEM" https://gitlab.example.com/api/v4/projects/5/pages/domains +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "domain=ssl.domain.example" --form "certificate=$CERT_PEM" --form "key=$KEY_PEM" https://gitlab.example.com/api/v4/projects/5/pages/domains ``` ```json @@ -158,11 +158,11 @@ PUT /projects/:id/pages/domains/:domain | `key` | file/string | no | The certificate key in PEM format. | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form="certificate=@/path/to/cert.pem" --form="key=@/path/to/key.pem" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example +curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "certificate=@/path/to/cert.pem" --form "key=@/path/to/key.pem" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example ``` ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form="certificate=$CERT_PEM" --form="key=$KEY_PEM" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example +curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "certificate=$CERT_PEM" --form "key=$KEY_PEM" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example ``` ```json diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 899f5da6647..ebae68fe389 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -102,6 +102,7 @@ POST /projects/:id/pipeline |------------|---------|----------|---------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `ref` | string | yes | Reference to commit | +| `variables` | array | no | An array containing the variables available in the pipeline, matching the structure [{ 'key' => 'UPLOAD_TO_S3', 'value' => 'true' }] | ``` curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=master" diff --git a/doc/api/projects.md b/doc/api/projects.md index d3e95926322..b4599fdc97e 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1198,7 +1198,7 @@ POST /projects/:id/share | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `group_id` | integer | yes | The ID of the group to share with | -| `group_access` | integer | yes | The permissions level to grant the group | +| `group_access` | integer | yes | The [permissions level](members.md) to grant the group | | `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 | ## Delete a shared project link within a group @@ -1390,6 +1390,16 @@ POST /projects/:id/housekeeping | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +### Transfer a project to a new namespace + +``` +PUT /projects/:id/transfer +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `namespace` | integer/string | yes | The ID or path of the namespace to transfer to project to | + ## Branches Read more in the [Branches](branches.md) documentation. diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 950ead52560..f6813f27dc0 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -8,7 +8,7 @@ The access levels are defined in the `ProtectedRefAccess::ALLOWED_ACCESS_LEVELS` ``` 0 => No access 30 => Developer access -40 => Master access +40 => Maintainer access ``` ## List protected branches @@ -36,13 +36,13 @@ Example response: "push_access_levels": [ { "access_level": 40, - "access_level_description": "Masters" + "access_level_description": "Maintainers" } ], "merge_access_levels": [ { "access_level": 40, - "access_level_description": "Masters" + "access_level_description": "Maintainers" } ] }, @@ -75,13 +75,13 @@ Example response: "push_access_levels": [ { "access_level": 40, - "access_level_description": "Masters" + "access_level_description": "Maintainers" } ], "merge_access_levels": [ { "access_level": 40, - "access_level_description": "Masters" + "access_level_description": "Maintainers" } ] } @@ -104,8 +104,8 @@ curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitl | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch or wildcard | -| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, master access level) | -| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, master access level) | +| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, maintainer access level) | +| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, maintainer access level) | Example response: @@ -115,13 +115,13 @@ Example response: "push_access_levels": [ { "access_level": 30, - "access_level_description": "Developers + Masters" + "access_level_description": "Developers + Maintainers" } ], "merge_access_levels": [ { "access_level": 30, - "access_level_description": "Developers + Masters" + "access_level_description": "Developers + Maintainers" } ] } diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 5aff255c20a..cb816bbd712 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -130,6 +130,7 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `from` (required) - the commit SHA or branch name - `to` (required) - the commit SHA or branch name +- `straight` (optional) - comparison method, `true` for direct comparison between `from` and `to` (`from`..`to`), `false` to compare using merge base (`from`...`to`)'. Default is `false`. ``` GET /projects/:id/repository/compare?from=master&to=feature diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index c29dc22e12d..49fb9bc141d 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -27,6 +27,7 @@ Example response: "size": 1476, "encoding": "base64", "content": "IyA9PSBTY2hlbWEgSW5mb3...", + "content_sha256": "4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481", "ref": "master", "blob_id": "79f7bbd25901e8334750839545a9bd021f0e4c83", "commit_id": "d5a3ff139356ce33e37e73add446f16869741b50", @@ -39,6 +40,36 @@ Parameters: - `file_path` (required) - Url encoded full path to new file. Ex. lib%2Fclass%2Erb - `ref` (required) - The name of branch, tag or commit +NOTE: **Note:** +`blob_id` is the blob sha, see [repositories - Get a blob from repository](repositories.md#get-a-blob-from-repository) + +In addition to the `GET` method, you can also use `HEAD` to get just file metadata. + +``` +HEAD /projects/:id/repository/files/:file_path +``` + +```bash +curl --head --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master' +``` + +Example response: + +```text +HTTP/1.1 200 OK +... +X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83 +X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50 +X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481 +X-Gitlab-Encoding: base64 +X-Gitlab-File-Name: key.rb +X-Gitlab-File-Path: app/models/key.rb +X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d +X-Gitlab-Ref: master +X-Gitlab-Size: 1476 +... +``` + ## Get raw file from repository ``` @@ -54,6 +85,9 @@ Parameters: - `file_path` (required) - Url encoded full path to new file. Ex. lib%2Fclass%2Erb - `ref` (required) - The name of branch, tag or commit +NOTE: **Note:** +Like [Get file from repository](repository_files.md#get-file-from-repository) you can use `HEAD` to get just file metadata. + ## Create new file in repository ``` diff --git a/doc/api/runners.md b/doc/api/runners.md index 3ca07ce9795..ac814bbf19a 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -30,6 +30,7 @@ Example response: "description": "test-1-20150125", "id": 6, "is_shared": false, + "ip_address": "127.0.0.1", "name": null, "online": true, "status": "online" @@ -38,6 +39,7 @@ Example response: "active": true, "description": "test-2-20150125", "id": 8, + "ip_address": "127.0.0.1", "is_shared": false, "name": null, "online": false, @@ -72,6 +74,7 @@ Example response: "active": true, "description": "shared-runner-1", "id": 1, + "ip_address": "127.0.0.1", "is_shared": true, "name": null, "online": true, @@ -81,6 +84,7 @@ Example response: "active": true, "description": "shared-runner-2", "id": 3, + "ip_address": "127.0.0.1", "is_shared": true, "name": null, "online": false @@ -90,6 +94,7 @@ Example response: "active": true, "description": "test-1-20150125", "id": 6, + "ip_address": "127.0.0.1", "is_shared": false, "name": null, "online": true @@ -99,6 +104,7 @@ Example response: "active": true, "description": "test-2-20150125", "id": 8, + "ip_address": "127.0.0.1", "is_shared": false, "name": null, "online": false, @@ -131,6 +137,7 @@ Example response: "architecture": null, "description": "test-1-20150125", "id": 6, + "ip_address": "127.0.0.1", "is_shared": false, "contacted_at": "2016-01-25T16:39:48.066Z", "name": null, @@ -189,6 +196,7 @@ Example response: "architecture": null, "description": "test-1-20150125-test", "id": 6, + "ip_address": "127.0.0.1", "is_shared": false, "contacted_at": "2016-01-25T16:39:48.066Z", "name": null, @@ -257,6 +265,7 @@ Example response: [ { "id": 2, + "ip_address": "127.0.0.1", "status": "running", "stage": "test", "name": "test", @@ -345,6 +354,7 @@ Example response: "active": true, "description": "test-2-20150125", "id": 8, + "ip_address": "127.0.0.1", "is_shared": false, "name": null, "online": false, @@ -354,6 +364,7 @@ Example response: "active": true, "description": "development_runner", "id": 5, + "ip_address": "127.0.0.1", "is_shared": true, "name": null, "online": true @@ -386,6 +397,7 @@ Example response: "active": true, "description": "test-2016-02-01", "id": 9, + "ip_address": "127.0.0.1", "is_shared": false, "name": null, "online": true, diff --git a/doc/api/search.md b/doc/api/search.md index 107ddaffa6a..9716f682ace 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -776,6 +776,15 @@ Example response: ### Scope: blobs +Filters are available for this scope: +- filename +- path +- extension + +to use a filter simply include it in your query like so: `a query filename:some_name*`. + +You may use wildcards (`*`) to use glob matching. + ```bash curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=installation ``` diff --git a/doc/api/services.md b/doc/api/services.md index f23303ef836..aeb48ccc36c 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -1,6 +1,6 @@ # Services API ->**Note:** This API requires an access token with Master or Owner permissions +>**Note:** This API requires an access token with Maintainer or Owner permissions ## Asana diff --git a/doc/api/settings.md b/doc/api/settings.md index 36a0782d8f2..e6b207d8746 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -81,7 +81,7 @@ PUT /application/settings | `clientside_sentry_enabled` | boolean | no | Enable Sentry error reporting for the client side | | `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes | | `default_artifacts_expire_in` | string | no | Set the default expiration time for each job's artifacts | -| `default_branch_protection` | integer | no | Determine if developers can push to master. Can take `0` _(not protected, both developers and masters can push new commits, force push, or delete the branch)_, `1` _(partially protected, developers and masters can push new commits, but cannot force push or delete the branch)_ or `2` _(fully protected, developers cannot push new commits, but masters can; no-one can force push or delete the branch)_ as a parameter. Default is `2`. | +| `default_branch_protection` | integer | no | Determine if developers can push to master. Can take `0` _(not protected, both developers and maintainers can push new commits, force push, or delete the branch)_, `1` _(partially protected, developers and maintainers can push new commits, but cannot force push or delete the branch)_ or `2` _(fully protected, developers cannot push new commits, but maintainers can; no-one can force push or delete the branch)_ as a parameter. Default is `2`. | | `default_group_visibility` | string | no | What visibility level new groups receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `default_project_visibility` | string | no | What visibility level new projects receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `default_projects_limit` | integer | no | Project limit per user. Default is `100000` | diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 42b760c107d..7892866cd8e 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -49,6 +49,7 @@ Example response: "title": "test", "file_name": "add.rb", "description": "Ruby test snippet", + "visibility": "private", "author": { "id": 1, "username": "john_smith", @@ -99,6 +100,7 @@ Example response: "title": "This is a snippet", "file_name": "test.txt", "description": "Hello World snippet", + "visibility": "internal", "author": { "id": 1, "username": "john_smith", @@ -150,6 +152,7 @@ Example response: "title": "test", "file_name": "add.rb", "description": "description of snippet", + "visibility": "internal", "author": { "id": 1, "username": "john_smith", @@ -238,7 +241,8 @@ Example response: "raw_url": "http://localhost:3000/snippets/48/raw", "title": "Minus similique nesciunt vel fugiat qui ullam sunt.", "updated_at": "2016-11-25T16:53:34.479Z", - "web_url": "http://localhost:3000/snippets/48" + "web_url": "http://localhost:3000/snippets/48", + "visibility": "public" } ] ``` |