Skip to content

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

Merge branch 'docs-api-merge-2' into 'master' 

Docs: Merge 5 api docs from EE to CE

See merge request gitlab-org/gitlab-ce!28633
parents 3fd99b4e d46dca74
Show whitespace changes
Inline Side-by-side
Showing with 378 additions and 105 deletions
doc/api/README.md
View file @ 33537616
...@@ -22,7 +22,7 @@ See also: ...@@ -22,7 +22,7 @@ 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` |
...@@ -31,17 +31,21 @@ The following API resources are available in the project context: ...@@ -31,17 +31,21 @@ The following API resources are available in the project context:
| [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` |
| [Issue links](issue_links.md) **[STARTER]** | `/projects/:id/issues/.../links` |
| [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` | | [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` |
| [Labels](labels.md) | `/projects/:id/labels` | | [Labels](labels.md) | `/projects/:id/labels` |
| [Managed licenses](managed_licenses.md) **[ULTIMATE]** | `/projects/:id/managed_licenses` |
| [Members](members.md) | `/projects/:id/members` (also available for groups) | | [Members](members.md) | `/projects/:id/members` (also available for groups) |
| [Merge request approvals](merge_request_approvals.md) **[STARTER]** | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals` |
| [Merge requests](merge_requests.md) | `/projects/:id/merge_requests` (also available for groups and standalone) | | [Merge requests](merge_requests.md) | `/projects/:id/merge_requests` (also available for groups and standalone) |
| [Notes](notes.md) (comments) | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` | | [Notes](notes.md) (comments) | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` (also available for groups) |
| [Notification settings](notification_settings.md) | `/projects/:id/notification_settings` (also available for groups and standalone) | | [Notification settings](notification_settings.md) | `/projects/:id/notification_settings` (also available for groups and standalone) |
| [Packages](packages.md) **[PREMIUM]** | `/projects/:id/packages` |
| [Pages domains](pages_domains.md) | `/projects/:id/pages` (also available standalone) | | [Pages domains](pages_domains.md) | `/projects/:id/pages` (also available standalone) |
| [Pipelines](pipelines.md) | `/projects/:id/pipelines` | | [Pipelines](pipelines.md) | `/projects/:id/pipelines` |
| [Pipeline schedules](pipeline_schedules.md) | `/projects/:id/pipeline_schedules` | | [Pipeline schedules](pipeline_schedules.md) | `/projects/:id/pipeline_schedules` |
...@@ -61,11 +65,12 @@ The following API resources are available in the project context: ...@@ -61,11 +65,12 @@ The following API resources are available in the project context:
| [Repositories](repositories.md) | `/projects/:id/repository` | | [Repositories](repositories.md) | `/projects/:id/repository` |
| [Repository files](repository_files.md) | `/projects/:id/repository/files` | | [Repository files](repository_files.md) | `/projects/:id/repository/files` |
| [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` | | [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` |
| [Resource label events](resource_label_events.md) | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events` | | [Resource label events](resource_label_events.md) | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events` (also available for groups) |
| [Runners](runners.md) | `/projects/:id/runners` (also available standalone) | | [Runners](runners.md) | `/projects/:id/runners` (also available standalone) |
| [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) | | [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) |
| [Services](services.md) | `/projects/:id/services` | | [Services](services.md) | `/projects/:id/services` |
| [Tags](tags.md) | `/projects/:id/repository/tags` | | [Tags](tags.md) | `/projects/:id/repository/tags` |
| [Vulnerabilities](vulnerabilities.md) **[ULTIMATE]** | `/projects/:id/vulnerabilities` (also available for groups) |
| [Wikis](wikis.md) | `/projects/:id/wikis` | | [Wikis](wikis.md) | `/projects/:id/wikis` |
### Group resources ### Group resources
...@@ -73,9 +78,13 @@ The following API resources are available in the project context: ...@@ -73,9 +78,13 @@ The following API resources are available in the project context:
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) |
| [Discussions](discussions.md) (threaded comments) **[ULTIMATE]** | `/groups/:id/epics/.../discussions` (also available for projects) |
| [Epic issues](epic_issues.md) **[ULTIMATE]** | `/groups/:id/epics/.../issues` |
| [Epic links](epic_links.md) **[ULTIMATE]** | `/groups/:id/epics/.../epics` |
| [Epics](epics.md) **[ULTIMATE]** | `/groups/:id/epics` |
| [Groups](groups.md) | `/groups`, `/groups/.../subgroups` | | [Groups](groups.md) | `/groups`, `/groups/.../subgroups` |
| [Group badges](group_badges.md) | `/groups/:id/badges` | | [Group badges](group_badges.md) | `/groups/:id/badges` |
| [Group issue boards](group_boards.md) | `/groups/:id/boards` | | [Group issue boards](group_boards.md) | `/groups/:id/boards` |
...@@ -85,7 +94,9 @@ The following API resources are available in the group context: ...@@ -85,7 +94,9 @@ The following API resources are available in the group context:
| [Issues](issues.md) | `/groups/:id/issues` (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) | | [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) | | [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) | | [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) | | [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
......
doc/api/jobs.md
View file @ 33537616
...@@ -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
...@@ -389,23 +421,50 @@ GET /projects/:id/jobs/artifacts/:ref_name/download?job=name ...@@ -389,23 +421,50 @@ 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
doc/api/project_clusters.md
View file @ 33537616
...@@ -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
......
doc/api/project_level_variables.md
View file @ 33537616
...@@ -67,13 +67,14 @@ POST /projects/:id/variables ...@@ -67,13 +67,14 @@ 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": "*"
} }
``` ```
...@@ -98,13 +101,14 @@ PUT /projects/:id/variables/:key ...@@ -98,13 +101,14 @@ 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": "*"
} }
``` ```
......
doc/api/search.md
View file @ 33537616
...@@ -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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7