Commit d46dca74 authored by Marcel Amirault's avatar Marcel Amirault Committed by Achilleas Pipinellis

Docs: Merge 5 api docs from EE to CE

parent 3fd99b4e
...@@ -21,72 +21,83 @@ See also: ...@@ -21,72 +21,83 @@ See also:
The following API resources are available in the project context: The following API resources are available in the project context:
| Resource | Available endpoints | | Resource | Available endpoints |
|:------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:--------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Access requests](access_requests.md) | `/projects/:id/access_requests` (also available for groups) | | [Access requests](access_requests.md) | `/projects/:id/access_requests` (also available for groups) |
| [Award emoji](award_emoji.md) | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji` | | [Award emoji](award_emoji.md) | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji` |
| [Branches](branches.md) | `/projects/:id/repository/branches/`, `/projects/:id/repository/merged_branches` | | [Branches](branches.md) | `/projects/:id/repository/branches/`, `/projects/:id/repository/merged_branches` |
| [Commits](commits.md) | `/projects/:id/repository/commits`, `/projects/:id/statuses` | | [Commits](commits.md) | `/projects/:id/repository/commits`, `/projects/:id/statuses` |
| [Container Registry](container_registry.md) | `/projects/:id/registry/repositories` | | [Container Registry](container_registry.md) | `/projects/:id/registry/repositories` |
| [Custom attributes](custom_attributes.md) | `/projects/:id/custom_attributes` (also available for groups and users) | | [Custom attributes](custom_attributes.md) | `/projects/:id/custom_attributes` (also available for groups and users) |
| [Deploy keys](deploy_keys.md) | `/projects/:id/deploy_keys` (also available standalone) | | [Deploy keys](deploy_keys.md) | `/projects/:id/deploy_keys` (also available standalone) |
| [Deployments](deployments.md) | `/projects/:id/deployments` | | [Deployments](deployments.md) | `/projects/:id/deployments` |
| [Discussions](discussions.md) (threaded comments) | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` | | [Discussions](discussions.md) (threaded comments) | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` (also available for groups) |
| [Environments](environments.md) | `/projects/:id/environments` | | [Environments](environments.md) | `/projects/:id/environments` |
| [Events](events.md) | `/projects/:id/events` (also available for users and standalone) | | [Events](events.md) | `/projects/:id/events` (also available for users and standalone) |
| [Issues](issues.md) | `/projects/:id/issues` (also available for groups and standalone) | | [Issues](issues.md) | `/projects/:id/issues` (also available for groups and standalone) |
| [Issue boards](boards.md) | `/projects/:id/boards` | | [Issue boards](boards.md) | `/projects/:id/boards` |
| [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` | | [Issue links](issue_links.md) **[STARTER]** | `/projects/:id/issues/.../links` |
| [Labels](labels.md) | `/projects/:id/labels` | | [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` |
| [Members](members.md) | `/projects/:id/members` (also available for groups) | | [Labels](labels.md) | `/projects/:id/labels` |
| [Merge requests](merge_requests.md) | `/projects/:id/merge_requests` (also available for groups and standalone) | | [Managed licenses](managed_licenses.md) **[ULTIMATE]** | `/projects/:id/managed_licenses` |
| [Notes](notes.md) (comments) | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` | | [Members](members.md) | `/projects/:id/members` (also available for groups) |
| [Notification settings](notification_settings.md) | `/projects/:id/notification_settings` (also available for groups and standalone) | | [Merge request approvals](merge_request_approvals.md) **[STARTER]** | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals` |
| [Pages domains](pages_domains.md) | `/projects/:id/pages` (also available standalone) | | [Merge requests](merge_requests.md) | `/projects/:id/merge_requests` (also available for groups and standalone) |
| [Pipelines](pipelines.md) | `/projects/:id/pipelines` | | [Notes](notes.md) (comments) | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` (also available for groups) |
| [Pipeline schedules](pipeline_schedules.md) | `/projects/:id/pipeline_schedules` | | [Notification settings](notification_settings.md) | `/projects/:id/notification_settings` (also available for groups and standalone) |
| [Pipeline triggers](pipeline_triggers.md) | `/projects/:id/triggers` | | [Packages](packages.md) **[PREMIUM]** | `/projects/:id/packages` |
| [Projects](projects.md) including setting Webhooks | `/projects`, `/projects/:id/hooks` (also available for users) | | [Pages domains](pages_domains.md) | `/projects/:id/pages` (also available standalone) |
| [Project badges](project_badges.md) | `/projects/:id/badges` | | [Pipelines](pipelines.md) | `/projects/:id/pipelines` |
| [Project clusters](project_clusters.md) | `/projects/:id/clusters` | | [Pipeline schedules](pipeline_schedules.md) | `/projects/:id/pipeline_schedules` |
| [Project-level variables](project_level_variables.md) | `/projects/:id/variables` | | [Pipeline triggers](pipeline_triggers.md) | `/projects/:id/triggers` |
| [Project import/export](project_import_export.md) | `/projects/:id/export`, `/projects/import`, `/projects/:id/import` | | [Projects](projects.md) including setting Webhooks | `/projects`, `/projects/:id/hooks` (also available for users) |
| [Project milestones](milestones.md) | `/projects/:id/milestones` | | [Project badges](project_badges.md) | `/projects/:id/badges` |
| [Project snippets](project_snippets.md) | `/projects/:id/snippets` | | [Project clusters](project_clusters.md) | `/projects/:id/clusters` |
| [Project templates](project_templates.md) | `/projects/:id/templates` | | [Project-level variables](project_level_variables.md) | `/projects/:id/variables` |
| [Protected branches](protected_branches.md) | `/projects/:id/protected_branches` | | [Project import/export](project_import_export.md) | `/projects/:id/export`, `/projects/import`, `/projects/:id/import` |
| [Protected tags](protected_tags.md) | `/projects/:id/protected_tags` | | [Project milestones](milestones.md) | `/projects/:id/milestones` |
| [Releases](releases/index.md) | `/projects/:id/releases` | | [Project snippets](project_snippets.md) | `/projects/:id/snippets` |
| [Release links](releases/links.md) | `/projects/:id/releases/.../assets/links` | | [Project templates](project_templates.md) | `/projects/:id/templates` |
| [Repositories](repositories.md) | `/projects/:id/repository` | | [Protected branches](protected_branches.md) | `/projects/:id/protected_branches` |
| [Repository files](repository_files.md) | `/projects/:id/repository/files` | | [Protected tags](protected_tags.md) | `/projects/:id/protected_tags` |
| [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` | | [Releases](releases/index.md) | `/projects/:id/releases` |
| [Resource label events](resource_label_events.md) | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events` | | [Release links](releases/links.md) | `/projects/:id/releases/.../assets/links` |
| [Runners](runners.md) | `/projects/:id/runners` (also available standalone) | | [Repositories](repositories.md) | `/projects/:id/repository` |
| [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) | | [Repository files](repository_files.md) | `/projects/:id/repository/files` |
| [Services](services.md) | `/projects/:id/services` | | [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` |
| [Tags](tags.md) | `/projects/:id/repository/tags` | | [Resource label events](resource_label_events.md) | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events` (also available for groups) |
| [Wikis](wikis.md) | `/projects/:id/wikis` | | [Runners](runners.md) | `/projects/:id/runners` (also available standalone) |
| [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) |
| [Services](services.md) | `/projects/:id/services` |
| [Tags](tags.md) | `/projects/:id/repository/tags` |
| [Vulnerabilities](vulnerabilities.md) **[ULTIMATE]** | `/projects/:id/vulnerabilities` (also available for groups) |
| [Wikis](wikis.md) | `/projects/:id/wikis` |
### Group resources ### Group resources
The following API resources are available in the group context: The following API resources are available in the group context:
| Resource | Available endpoints | | Resource | Available endpoints |
|:--------------------------------------------------|:---------------------------------------------------------------------------------| |:-----------------------------------------------------------------|:---------------------------------------------------------------------------------|
| [Access requests](access_requests.md) | `/groups/:id/access_requests/` (also available for projects) | | [Access requests](access_requests.md) | `/groups/:id/access_requests/` (also available for projects) |
| [Custom attributes](custom_attributes.md) | `/groups/:id/custom_attributes` (also available for projects and users) | | [Custom attributes](custom_attributes.md) | `/groups/:id/custom_attributes` (also available for projects and users) |
| [Groups](groups.md) | `/groups`, `/groups/.../subgroups` | | [Discussions](discussions.md) (threaded comments) **[ULTIMATE]** | `/groups/:id/epics/.../discussions` (also available for projects) |
| [Group badges](group_badges.md) | `/groups/:id/badges` | | [Epic issues](epic_issues.md) **[ULTIMATE]** | `/groups/:id/epics/.../issues` |
| [Group issue boards](group_boards.md) | `/groups/:id/boards` | | [Epic links](epic_links.md) **[ULTIMATE]** | `/groups/:id/epics/.../epics` |
| [Group labels](group_labels.md) | `/groups/:id/labels` | | [Epics](epics.md) **[ULTIMATE]** | `/groups/:id/epics` |
| [Group-level variables](group_level_variables.md) | `/groups/:id/variables` | | [Groups](groups.md) | `/groups`, `/groups/.../subgroups` |
| [Group milestones](group_milestones.md) | `/groups/:id/milestones` | | [Group badges](group_badges.md) | `/groups/:id/badges` |
| [Issues](issues.md) | `/groups/:id/issues` (also available for projects and standalone) | | [Group issue boards](group_boards.md) | `/groups/:id/boards` |
| [Members](members.md) | `/groups/:id/members` (also available for projects) | | [Group labels](group_labels.md) | `/groups/:id/labels` |
| [Merge requests](merge_requests.md) | `/groups/:id/merge_requests` (also available for projects and standalone) | | [Group-level variables](group_level_variables.md) | `/groups/:id/variables` |
| [Notification settings](notification_settings.md) | `/groups/:id/notification_settings` (also available for projects and standalone) | | [Group milestones](group_milestones.md) | `/groups/:id/milestones` |
| [Search](search.md) | `/groups/:id/search` (also available for projects and standalone) | | [Issues](issues.md) | `/groups/:id/issues` (also available for projects and standalone) |
| [Members](members.md) | `/groups/:id/members` (also available for projects) |
| [Merge requests](merge_requests.md) | `/groups/:id/merge_requests` (also available for projects and standalone) |
| [Notes](notes.md) (comments) | `/groups/:id/epics/.../notes` (also available for projects) |
| [Notification settings](notification_settings.md) | `/groups/:id/notification_settings` (also available for projects and standalone) |
| [Resource label events](resource_label_events.md) | `/groups/:id/epics/.../resource_label_events` (also available for projects) |
| [Search](search.md) | `/groups/:id/search` (also available for projects and standalone) |
### Standalone resources ### Standalone resources
...@@ -102,9 +113,11 @@ The following API resources are available outside of project and group contexts ...@@ -102,9 +113,11 @@ The following API resources are available outside of project and group contexts
| [Deploy keys](deploy_keys.md) | `/deploy_keys` (also available for projects) | | [Deploy keys](deploy_keys.md) | `/deploy_keys` (also available for projects) |
| [Events](events.md) | `/events`, `/users/:id/events` (also available for projects) | | [Events](events.md) | `/events`, `/users/:id/events` (also available for projects) |
| [Feature flags](features.md) | `/features` | | [Feature flags](features.md) | `/features` |
| [Geo Nodes](geo_nodes.md) **[PREMIUM ONLY]** | `/geo_nodes` |
| [Import repository from GitHub](import.md) | `/import/github` | | [Import repository from GitHub](import.md) | `/import/github` |
| [Issues](issues.md) | `/issues` (also available for groups and projects) | | [Issues](issues.md) | `/issues` (also available for groups and projects) |
| [Keys](keys.md) | `/keys` | | [Keys](keys.md) | `/keys` |
| [License](license.md) **[CORE ONLY]** | `/license` |
| [Markdown](markdown.md) | `/markdown` | | [Markdown](markdown.md) | `/markdown` |
| [Merge requests](merge_requests.md) | `/merge_requests` (also available for groups and projects) | | [Merge requests](merge_requests.md) | `/merge_requests` (also available for groups and projects) |
| [Namespaces](namespaces.md) | `/namespaces` | | [Namespaces](namespaces.md) | `/namespaces` |
...@@ -131,6 +144,11 @@ Endpoints are available for: ...@@ -131,6 +144,11 @@ Endpoints are available for:
- [GitLab CI YAML templates](templates/gitlab_ci_ymls.md). - [GitLab CI YAML templates](templates/gitlab_ci_ymls.md).
- [Open source license templates](templates/licenses.md). - [Open source license templates](templates/licenses.md).
## SCIM **[SILVER ONLY]**
[GitLab.com Silver and above](https://about.gitlab.com/pricing/) provides an [SCIM API](scim.md) that implements [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) and provides
the `/Users` endpoint. The base URL is: `/api/scim/v2/groups/:group_path/Users/`.
## Road to GraphQL ## Road to GraphQL
Going forward, we will start on moving to Going forward, we will start on moving to
...@@ -186,8 +204,6 @@ curl "https://gitlab.example.com/api/v4/projects" ...@@ -186,8 +204,6 @@ curl "https://gitlab.example.com/api/v4/projects"
The API uses JSON to serialize data. You don't need to specify `.json` at the The API uses JSON to serialize data. You don't need to specify `.json` at the
end of an API URL. end of an API URL.
All of the API endpoints that use the `POST`, `PUT` or `PATCH` method support params in the request body, with `Content-Type` `application/x-www-form-urlencoded`, `multipart/form-data` or `application/json`.
## Authentication ## Authentication
Most API requests require authentication, or will only return public data when Most API requests require authentication, or will only return public data when
......
...@@ -346,30 +346,58 @@ Example of response ...@@ -346,30 +346,58 @@ Example of response
> **Notes**: > **Notes**:
> >
> - [Introduced][ce-2893] in GitLab 8.5. > - [Introduced][ce-2893] in GitLab 8.5.
> - The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346]
> in [GitLab Premium][ee] 9.5.
Get job artifacts of a project. Get the job's artifacts zipped archive of a project.
``` ```
GET /projects/:id/jobs/:job_id/artifacts GET /projects/:id/jobs/:job_id/artifacts
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id` | integer | yes | ID of a job. | | `job_id` | integer | yes | ID of a job. |
| `job_token` **[PREMIUM]** | string | no | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
Example requests: Example request using the `PRIVATE-TOKEN` header:
```sh ```sh
curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/artifacts" curl --output artifacts.zip --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts"
``` ```
To use this in a [`script` definition](../ci/yaml/README.md#script) inside
`.gitlab-ci.yml` **[PREMIUM]**, you can use either:
- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable.
For example, the following job will download the artifacts of the job with ID
`42`. Note that the command is wrapped into single quotes since it contains a
colon (`:`):
```yaml
artifact_download:
stage: test
script:
- 'curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts"'
```
- Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable.
For example, the following job will download the artifacts of the job with ID `42`:
```yaml
artifact_download:
stage: test
script:
- 'curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts?job_token=$CI_JOB_TOKEN"'
```
Possible response status codes: Possible response status codes:
| Status | Description | | Status | Description |
|-----------|---------------------------------| |-----------|---------------------------------|
| 200 | Serves the artifacts file | | 200 | Serves the artifacts file. |
| 404 | Build not found or no artifacts | | 404 | Build not found or no artifacts.|
[ce-2893]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2893 [ce-2893]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2893
...@@ -378,9 +406,13 @@ Possible response status codes: ...@@ -378,9 +406,13 @@ Possible response status codes:
> **Notes**: > **Notes**:
> >
> - [Introduced][ce-5347] in GitLab 8.10. > - [Introduced][ce-5347] in GitLab 8.10.
> - The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346]
> in [GitLab Premium][ee] 9.5.
Download the artifacts archive from the given reference name and job provided the Download the artifacts zipped archive from the given reference name and job,
job finished successfully. provided the job finished successfully. This is the same as
[getting the job's artifacts](#get-job-artifacts), but by defining the job's
name instead of its ID.
``` ```
GET /projects/:id/jobs/artifacts/:ref_name/download?job=name GET /projects/:id/jobs/artifacts/:ref_name/download?job=name
...@@ -388,24 +420,51 @@ GET /projects/:id/jobs/artifacts/:ref_name/download?job=name ...@@ -388,24 +420,51 @@ GET /projects/:id/jobs/artifacts/:ref_name/download?job=name
Parameters Parameters
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | | `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. |
| `job` | string | yes | The name of the job. | | `job` | string | yes | The name of the job. |
| `job_token` **[PREMIUM]** | string | no | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
Example requests: Example request using the `PRIVATE-TOKEN` header:
```sh ```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test" curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
``` ```
To use this in a [`script` definition](../ci/yaml/README.md#script) inside
`.gitlab-ci.yml` **[PREMIUM]**, you can use either:
- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable.
For example, the following job will download the artifacts of the `test` job
of the `master` branch. Note that the command is wrapped into single quotes
since it contains a colon (`:`):
```yaml
artifact_download:
stage: test
script:
- 'curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/master/download?job=test"'
```
- Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable.
For example, the following job will download the artifacts of the `test` job
of the `master` branch:
```yaml
artifact_download:
stage: test
script:
- 'curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/master/download?job=test&job_token=$CI_JOB_TOKEN"'
```
Possible response status codes: Possible response status codes:
| Status | Description | | Status | Description |
|-----------|---------------------------------| |-----------|---------------------------------|
| 200 | Serves the artifacts file | | 200 | Serves the artifacts file. |
| 404 | Build not found or no artifacts | | 404 | Build not found or no artifacts.|
[ce-5347]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5347 [ce-5347]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5347
...@@ -414,7 +473,7 @@ Possible response status codes: ...@@ -414,7 +473,7 @@ Possible response status codes:
> Introduced in GitLab 10.0 > Introduced in GitLab 10.0
Download a single artifact file from a job with a specified ID from within Download a single artifact file from a job with a specified ID from within
the job's artifacts archive. The file is extracted from the archive and the job's artifacts zipped archive. The file is extracted from the archive and
streamed to the client. streamed to the client.
``` ```
...@@ -783,3 +842,7 @@ Example of response ...@@ -783,3 +842,7 @@ Example of response
"user": null "user": null
} }
``` ```
[ee]: https://about.gitlab.com/pricing/
[ee-2346]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2346
[triggers]: ../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline-premium
...@@ -167,6 +167,7 @@ Parameters: ...@@ -167,6 +167,7 @@ Parameters:
| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | | `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project | | `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project |
| `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | | `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. |
| `environment_scope` | String | no | The associated environment to the cluster. Defaults to `*` **[PREMIUM]** |
Example request: Example request:
...@@ -256,6 +257,7 @@ Parameters: ...@@ -256,6 +257,7 @@ Parameters:
| `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes | | `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes |
| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | | `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project | | `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project |
| `environment_scope` | String | no | The associated environment to the cluster **[PREMIUM]** |
NOTE: **Note:** NOTE: **Note:**
`name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added
......
# Project-level Variables API # Project-level Variables API
## List project variables ## List project variables
...@@ -66,14 +66,15 @@ Create a new variable. ...@@ -66,14 +66,15 @@ Create a new variable.
POST /projects/:id/variables POST /projects/:id/variables
``` ```
| Attribute | Type | required | Description | | Attribute | Type | required | Description |
|-----------------|---------|----------|-----------------------| |---------------------|---------|----------|-----------------------|
| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | | `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed |
| `value` | string | yes | The `value` of a variable | | `value` | string | yes | The `value` of a variable |
| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` |
| `protected` | boolean | no | Whether the variable is protected | | `protected` | boolean | no | Whether the variable is protected |
| `masked` | boolean | no | Whether the variable is masked | | `masked` | boolean | no | Whether the variable is masked |
| `environment_scope` | string | no | The `environment_scope` of the variable **[PREMIUM]** |
``` ```
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value" curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value"
...@@ -83,9 +84,11 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla ...@@ -83,9 +84,11 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla
{ {
"key": "NEW_VARIABLE", "key": "NEW_VARIABLE",
"value": "new value", "value": "new value",
"protected": false,
"variable_type": "env_var", "variable_type": "env_var",
"protected": false, "protected": false,
"masked": false "masked": false,
"environment_scope": "*"
} }
``` ```
...@@ -97,14 +100,15 @@ Update a project's variable. ...@@ -97,14 +100,15 @@ Update a project's variable.
PUT /projects/:id/variables/:key PUT /projects/:id/variables/:key
``` ```
| Attribute | Type | required | Description | | Attribute | Type | required | Description |
|-----------------|---------|----------|-------------------------| |---------------------|---------|----------|-------------------------|
| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `key` | string | yes | The `key` of a variable | | `key` | string | yes | The `key` of a variable |
| `value` | string | yes | The `value` of a variable | | `value` | string | yes | The `value` of a variable |
| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` |
| `protected` | boolean | no | Whether the variable is protected | | `protected` | boolean | no | Whether the variable is protected |
| `masked` | boolean | no | Whether the variable is masked | | `masked` | boolean | no | Whether the variable is masked |
| `environment_scope` | string | no | The `environment_scope` of the variable **[PREMIUM]** |
``` ```
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value" curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value"
...@@ -116,7 +120,8 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab ...@@ -116,7 +120,8 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab
"value": "updated value", "value": "updated value",
"variable_type": "env_var", "variable_type": "env_var",
"protected": true, "protected": true,
"masked": false "masked": false,
"environment_scope": "*"
} }
``` ```
......
...@@ -19,6 +19,8 @@ GET /search ...@@ -19,6 +19,8 @@ GET /search
Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, snippet_blobs, users. Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, snippet_blobs, users.
If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **[STARTER]**
The response depends on the requested scope. The response depends on the requested scope.
### Scope: projects ### Scope: projects
...@@ -281,6 +283,98 @@ Example response: ...@@ -281,6 +283,98 @@ Example response:
] ]
``` ```
### Scope: wiki_blobs **[STARTER]**
This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
```bash
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=wiki_blobs&search=bye
```
Example response:
```json
[
{
"basename": "home",
"data": "hello\n\nand bye\n\nend",
"filename": "home.md",
"id": null,
"ref": "master",
"startline": 5,
"project_id": 6
}
]
```
### Scope: commits **[STARTER]**
This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
```bash
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=commits&search=bye
```
Example response:
```json
[
{
"id": "4109c2d872d5fdb1ed057400d103766aaea97f98",
"short_id": "4109c2d8",
"title": "goodbye $.browser",
"created_at": "2013-02-18T22:02:54.000Z",
"parent_ids": [
"59d05353ab575bcc2aa958fe1782e93297de64c9"
],
"message": "goodbye $.browser\n",
"author_name": "angus croll",
"author_email": "anguscroll@gmail.com",
"authored_date": "2013-02-18T22:02:54.000Z",
"committer_name": "angus croll",
"committer_email": "anguscroll@gmail.com",
"committed_date": "2013-02-18T22:02:54.000Z",
"project_id": 6
}
]
```
### Scope: blobs **[STARTER]**
This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
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: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=blobs&search=installation
```
Example response:
```json
[
{
"basename": "README",
"data": "```\n\n## Installation\n\nQuick start using the [pre-built",
"filename": "README.md",
"id": null,
"ref": "master",
"startline": 46,
"project_id": 6
}
]
```
### Scope: users ### Scope: users
```bash ```bash
...@@ -320,6 +414,8 @@ GET /groups/:id/search ...@@ -320,6 +414,8 @@ GET /groups/:id/search
Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users. Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users.
If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **[STARTER]**
The response depends on the requested scope. The response depends on the requested scope.
### Scope: projects ### Scope: projects
...@@ -520,6 +616,98 @@ Example response: ...@@ -520,6 +616,98 @@ Example response:
] ]
``` ```
### Scope: wiki_blobs **[STARTER]**
This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
```bash
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/6/search?scope=wiki_blobs&search=bye
```
Example response:
```json
[
{
"basename": "home",
"data": "hello\n\nand bye\n\nend",
"filename": "home.md",
"id": null,
"ref": "master",
"startline": 5,
"project_id": 6
}
]
```
### Scope: commits **[STARTER]**
This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
```bash
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/6/search?scope=commits&search=bye
```
Example response:
```json
[
{
"id": "4109c2d872d5fdb1ed057400d103766aaea97f98",
"short_id": "4109c2d8",
"title": "goodbye $.browser",
"created_at": "2013-02-18T22:02:54.000Z",
"parent_ids": [
"59d05353ab575bcc2aa958fe1782e93297de64c9"
],
"message": "goodbye $.browser\n",
"author_name": "angus croll",
"author_email": "anguscroll@gmail.com",
"authored_date": "2013-02-18T22:02:54.000Z",
"committer_name": "angus croll",
"committer_email": "anguscroll@gmail.com",
"committed_date": "2013-02-18T22:02:54.000Z",
"project_id": 6
}
]
```
### Scope: blobs **[STARTER]**
This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
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: <your_access_token>" https://gitlab.example.com/api/v4/groups/6/search?scope=blobs&search=installation
```
Example response:
```json
[
{
"basename": "README",
"data": "```\n\n## Installation\n\nQuick start using the [pre-built",
"filename": "README.md",
"id": null,
"ref": "master",
"startline": 46,
"project_id": 6
}
]
```
### Scope: users ### Scope: users
```bash ```bash
...@@ -556,7 +744,6 @@ GET /projects/:id/search ...@@ -556,7 +744,6 @@ GET /projects/:id/search
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `scope` | string | yes | The scope to search in | | `scope` | string | yes | The scope to search in |
| `search` | string | yes | The search query | | `search` | string | yes | The search query |
| `ref` | string | no | The name of a repository branch or tag to search on. The project's default branch is used by default. This is only applicable for scopes: commits, blobs, and wiki_blobs. |
Search the expression within the specified scope. Currently these scopes are supported: issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users. Search the expression within the specified scope. Currently these scopes are supported: issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users.
...@@ -851,7 +1038,7 @@ Blobs searches are performed on both filenames and contents. Search results: ...@@ -851,7 +1038,7 @@ Blobs searches are performed on both filenames and contents. Search results:
times in the content. times in the content.
```bash ```bash
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=installation&ref=feature curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=installation
``` ```
Example response: Example response:
...@@ -864,7 +1051,7 @@ Example response: ...@@ -864,7 +1051,7 @@ Example response:
"data": "```\n\n## Installation\n\nQuick start using the [pre-built", "data": "```\n\n## Installation\n\nQuick start using the [pre-built",
"filename": "README.md", "filename": "README.md",
"id": null, "id": null,
"ref": "feature", "ref": "master",
"startline": 46, "startline": 46,
"project_id": 6 "project_id": 6
} }
......
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