diff options
Diffstat (limited to 'doc/api')
125 files changed, 3196 insertions, 1741 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index c23a383c70f..5ab8653dc35 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -1,781 +1,8 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'index.md' --- -# API Docs **(FREE)** +This document was moved to [another location](index.md). -Use the GitLab [REST](http://spec.openapis.org/oas/v3.0.3) API to automate GitLab. - -You can also use a partial [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/openapi/openapi.yaml), -to test the API directly from the GitLab user interface. -Contributions are welcome. - -## Available API resources - -For a list of the available resources and their endpoints, see -[API resources](api_resources.md). - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an introduction and basic steps, see -[How to make GitLab API calls](https://www.youtube.com/watch?v=0LsMC3ZiXkA). - -## SCIM **(PREMIUM SAAS)** - -GitLab provides an [SCIM API](scim.md) that both 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/`. - -## GraphQL API - -A [GraphQL](graphql/index.md) API is available in GitLab. - -With GraphQL, you can make an API request for only what you need, -and it's versioned by default. - -GraphQL co-exists with the current v4 REST API. If we have a v5 API, this should -be a compatibility layer on top of GraphQL. - -There were some patenting and licensing concerns with GraphQL. However, these -have been resolved to our satisfaction. The reference implementations -were re-licensed under MIT, and the OWF license used for the GraphQL specification. - -When GraphQL is fully implemented, GitLab: - -- Can delete controller-specific endpoints. -- Will no longer maintain two different APIs. - -## Compatibility guidelines - -The HTTP API is versioned with a single number, which is currently `4`. This number -symbolizes the major version number, as described by [SemVer](https://semver.org/). -Because of this, backward-incompatible changes require this version number to -change. - -The minor version isn't explicit, which allows for a stable API -endpoint. New features can be added to the API in the same -version number. - -New features and bug fixes are released in tandem with GitLab. Apart -from incidental patch and security releases, GitLab is released on the 22nd of each -month. Major API version changes, and removal of entire API versions, are done in tandem -with major GitLab releases. - -All deprecations and changes between versions are in the documentation. -For the changes between v3 and v4, see the [v3 to v4 documentation](v3_to_v4.md). - -### Current status - -Only API version v4 is available. Version v3 was removed in -[GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819). - -## How to use the API - -API requests must include both `api` and the API version. The API -version is defined in [`lib/api.rb`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/api/api.rb). -For example, the root of the v4 API is at `/api/v4`. - -### Valid API request - -If you have a GitLab instance at `gitlab.example.com`: - -```shell -curl "https://gitlab.example.com/api/v4/projects" -``` - -The API uses JSON to serialize data. You don't need to specify `.json` at the -end of the API URL. - -### API request to expose HTTP response headers - -If you want to expose HTTP response headers, use the `--include` option: - -```shell -curl --include "https://gitlab.example.com/api/v4/projects" -HTTP/2 200 -... -``` - -This request can help you investigate an unexpected response. - -### API request that includes the exit code - -If you want to expose the HTTP exit code, include the `--fail` option: - -```shell script -curl --fail "https://gitlab.example.com/api/v4/does-not-exist" -curl: (22) The requested URL returned error: 404 -``` - -The HTTP exit code can help you diagnose the success or failure of your REST request. - -## Authentication - -Most API requests require authentication, or only return public data when -authentication isn't provided. When authentication is not required, the documentation -for each endpoint specifies this. For example, the -[`/projects/:id` endpoint](projects.md#get-single-project) does not require authentication. - -There are several ways you can authenticate with the GitLab API: - -- [OAuth2 tokens](#oauth2-tokens) -- [Personal access tokens](../user/profile/personal_access_tokens.md) -- [Project access tokens](../user/project/settings/project_access_tokens.md) -- [Session cookie](#session-cookie) -- [GitLab CI/CD job token](#gitlab-cicd-job-token) **(Specific endpoints only)** - -Project access tokens are supported by: - -- Self-managed GitLab Free and higher. -- GitLab SaaS Premium and higher. - -If you are an administrator, you or your application can authenticate as a specific user. -To do so, use: - -- [Impersonation tokens](#impersonation-tokens) -- [Sudo](#sudo) - -If authentication information is not valid or is missing, GitLab returns an error -message with a status code of `401`: - -```json -{ - "message": "401 Unauthorized" -} -``` - -### OAuth2 tokens - -You can use an [OAuth2 token](oauth2.md) to authenticate with the API by passing -it in either the `access_token` parameter or the `Authorization` header. - -Example of using the OAuth2 token in a parameter: - -```shell -curl "https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN" -``` - -Example of using the OAuth2 token in a header: - -```shell -curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/projects" -``` - -Read more about [GitLab as an OAuth2 provider](oauth2.md). - -### Personal/project access tokens - -You can use access tokens to authenticate with the API by passing it in either -the `private_token` parameter or the `PRIVATE-TOKEN` header. - -Example of using the personal or project access token in a parameter: - -```shell -curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>" -``` - -Example of using the personal or project access token in a header: - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects" -``` - -You can also use personal or project access tokens with OAuth-compliant headers: - -```shell -curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects" -``` - -### Session cookie - -Signing in to the main GitLab application sets a `_gitlab_session` cookie. The -API uses this cookie for authentication if it's present. Using the API to -generate a new session cookie isn't supported. - -The primary user of this authentication method is the web frontend of GitLab -itself. The web frontend can use the API as the authenticated user to get a -list of projects without explicitly passing an access token. - -### GitLab CI/CD job token - -When a pipeline job is about to run, GitLab generates a unique token and injects it as the -[`CI_JOB_TOKEN` predefined variable](../ci/variables/predefined_variables.md). - -You can use a GitLab CI/CD job token to authenticate with specific API endpoints: - -- Packages: - - [Package Registry](../user/packages/package_registry/index.md). To push to the - Package Registry, you can use [deploy tokens](../user/project/deploy_tokens/index.md). - - [Container Registry](../user/packages/container_registry/index.md) - (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`). - - [Container Registry API](container_registry.md) (scoped to the job's project, when the `ci_job_token_scope` feature flag is enabled) -- [Get job artifacts](job_artifacts.md#get-job-artifacts). -- [Get job token's job](jobs.md#get-job-tokens-job). -- [Pipeline triggers](pipeline_triggers.md), using the `token=` parameter. -- [Release creation](releases/index.md#create-a-release). -- [Terraform plan](../user/infrastructure/index.md). - -The token has the same permissions to access the API as the user that triggers the -pipeline. Therefore, this user must be assigned to [a role that has the required privileges](../user/permissions.md). - -The token is valid only while the pipeline job runs. After the job finishes, you can't -use the token anymore. - -A job token can access a project's resources without any configuration, but it might -give extra permissions that aren't necessary. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) -to redesign the feature for more strategic control of the access permissions. - -#### GitLab CI/CD job token security - -To make sure that this token doesn't leak, GitLab: - -- Masks the job token in job logs. -- Grants permissions to the job token only when the job is running. - -To make sure that this token doesn't leak, you should also configure -your [runners](../ci/runners/README.md) to be secure. Avoid: - -- Using Docker's `privileged` mode if the machines are re-used. -- Using the [`shell` executor](https://docs.gitlab.com/runner/executors/shell.html) when jobs - run on the same machine. - -If you have an insecure GitLab Runner configuration, you increase the risk that someone -tries to steal tokens from other jobs. - -### Impersonation tokens - -Impersonation tokens are a type of [personal access token](../user/profile/personal_access_tokens.md). -They can be created only by an administrator, and are used to authenticate with the -API as a specific user. - -Use impersonation tokens an alternative to: - -- The user's password or one of their personal access tokens. -- The [Sudo](#sudo) feature. The user's or administrator's password or token - may not be known, or may change over time. - -For more information, see the [users API](users.md#create-an-impersonation-token) -documentation. - -Impersonation tokens are used exactly like regular personal access tokens, and -can be passed in either the `private_token` parameter or the `PRIVATE-TOKEN` -header. - -#### Disable impersonation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/40385) in GitLab 11.6. - -By default, impersonation is enabled. To disable impersonation: - -**For Omnibus installations** - -1. Edit the `/etc/gitlab/gitlab.rb` file: - - ```ruby - gitlab_rails['impersonation_enabled'] = false - ``` - -1. Save the file, and then [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - GitLab for the changes to take effect. - -To re-enable impersonation, remove this configuration, and then reconfigure -GitLab. - -**For installations from source** - -1. Edit the `config/gitlab.yml` file: - - ```yaml - gitlab: - impersonation_enabled: false - ``` - -1. Save the file, and then [restart](../administration/restart_gitlab.md#installations-from-source) - GitLab for the changes to take effect. - -To re-enable impersonation, remove this configuration, and then restart GitLab. - -### Sudo - -All API requests support performing an API request as if you were another user, -provided you're authenticated as an administrator with an OAuth or personal -access token that has the `sudo` scope. The API requests are executed with the -permissions of the impersonated user. - -As an [administrator](../user/permissions.md), pass the `sudo` parameter either -by using query string or a header with an ID or username (case insensitive) of -the user you want to perform the operation as. If passed as a header, the header -name must be `Sudo`. - -If a non administrative access token is provided, GitLab returns an error -message with a status code of `403`: - -```json -{ - "message": "403 Forbidden - Must be admin to use sudo" -} -``` - -If an access token without the `sudo` scope is provided, an error message is -be returned with a status code of `403`: - -```json -{ - "error": "insufficient_scope", - "error_description": "The request requires higher privileges than provided by the access token.", - "scope": "sudo" -} -``` - -If the sudo user ID or username cannot be found, an error message is -returned with a status code of `404`: - -```json -{ - "message": "404 User with ID or username '123' Not Found" -} -``` - -Example of a valid API request and a request using cURL with sudo request, -providing a username: - -```plaintext -GET /projects?private_token=<your_access_token>&sudo=username -``` - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects" -``` - -Example of a valid API request and a request using cURL with sudo request, -providing an ID: - -```plaintext -GET /projects?private_token=<your_access_token>&sudo=23 -``` - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects" -``` - -## Status codes - -The API is designed to return different status codes according to context and -action. This way, if a request results in an error, you can get -insight into what went wrong. - -The following table gives an overview of how the API functions generally behave. - -| Request type | Description | -|---------------|-------------| -| `GET` | Access one or more resources and return the result as JSON. | -| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. | -| `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. | -| `DELETE` | Returns `204 No Content` if the resource was deleted successfully. | - -The following table shows the possible return codes for API requests. - -| Return values | Description | -|--------------------------|-------------| -| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, and the resource(s) itself is returned as JSON. | -| `204 No Content` | The server has successfully fulfilled the request, and there is no additional content to send in the response payload body. | -| `201 Created` | The `POST` request was successful, and the resource is returned as JSON. | -| `304 Not Modified` | The resource hasn't been modified since the last request. | -| `400 Bad Request` | A required attribute of the API request is missing. For example, the title of an issue is not given. | -| `401 Unauthorized` | The user isn't authenticated. A valid [user token](#authentication) is necessary. | -| `403 Forbidden` | The request isn't allowed. For example, the user isn't allowed to delete a project. | -| `404 Not Found` | A resource couldn't be accessed. For example, an ID for a resource couldn't be found. | -| `405 Method Not Allowed` | The request isn't supported. | -| `409 Conflict` | A conflicting resource already exists. For example, creating a project with a name that already exists. | -| `412` | The request was denied. This can happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. | -| `422 Unprocessable` | The entity couldn't be processed. | -| `429 Too Many Requests` | The user exceeded the [application rate limits](../administration/instance_limits.md#rate-limits). | -| `500 Server Error` | While handling the request, something went wrong on the server. | - -## Pagination - -GitLab supports the following pagination methods: - -- Offset-based pagination. This is the default method and is available on all endpoints. -- Keyset-based pagination. Added to selected endpoints but being - [progressively rolled out](https://gitlab.com/groups/gitlab-org/-/epics/2039). - -For large collections, for performance reasons we recommend keyset pagination -(when available) instead of offset pagination. - -### Offset-based pagination - -Sometimes, the returned result spans many pages. When listing resources, you can -pass the following parameters: - -| Parameter | Description | -|------------|-------------| -| `page` | Page number (default: `1`). | -| `per_page` | Number of items to list per page (default: `20`, max: `100`). | - -In the following example, we list 50 [namespaces](namespaces.md) per page: - -```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces?per_page=50" -``` - -#### Pagination `Link` header - -[`Link` headers](https://www.w3.org/wiki/LinkHeader) are returned with each -response. They have `rel` set to `prev`, `next`, `first`, or `last` and contain -the relevant URL. Be sure to use these links instead of generating your own URLs. - -For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers). - -In the following cURL example, we limit the output to three items per page -(`per_page=3`) and we request the second page (`page=2`) of [comments](notes.md) -of the issue with ID `8` which belongs to the project with ID `9`: - -```shell -curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2" -``` - -The response is: - -```http -HTTP/2 200 OK -cache-control: no-cache -content-length: 1103 -content-type: application/json -date: Mon, 18 Jan 2016 09:43:18 GMT -link: <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="last" -status: 200 OK -vary: Origin -x-next-page: 3 -x-page: 2 -x-per-page: 3 -x-prev-page: 1 -x-request-id: 732ad4ee-9870-4866-a199-a9db0cde3c86 -x-runtime: 0.108688 -x-total: 8 -x-total-pages: 3 -``` - -#### Other pagination headers - -GitLab also returns the following additional pagination headers: - -| Header | Description | -|-----------------|-------------| -| `x-next-page` | The index of the next page. | -| `x-page` | The index of the current page (starting at 1). | -| `x-per-page` | The number of items per page. | -| `X-prev-page` | The index of the previous page. | -| `x-total` | The total number of items. | -| `x-total-pages` | The total number of pages. | - -For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers). - -### Keyset-based pagination - -Keyset-pagination allows for more efficient retrieval of pages and - in contrast -to offset-based pagination - runtime is independent of the size of the -collection. - -This method is controlled by the following parameters: - -| Parameter | Description | -|--------------| ------------| -| `pagination` | `keyset` (to enable keyset pagination). | -| `per_page` | Number of items to list per page (default: `20`, max: `100`). | - -In the following example, we list 50 [projects](projects.md) per page, ordered -by `id` ascending. - -```shell -curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc" -``` - -The response header includes a link to the next page. For example: - -```http -HTTP/1.1 200 OK -... -Links: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next" -Link: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next" -Status: 200 OK -... -``` - -WARNING: -The `Links` header is scheduled to be removed in GitLab 14.0 to be aligned with the -[W3C `Link` specification](https://www.w3.org/wiki/LinkHeader). The `Link` -header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714) -and should be used instead. - -The link to the next page contains an additional filter `id_after=42` that -excludes already-retrieved records. The type of filter depends on the -`order_by` option used, and we may have more than one additional filter. - -When the end of the collection is reached and there are no additional -records to retrieve, the `Link` header is absent and the resulting array is -empty. - -We recommend using only the given link to retrieve the next page instead of -building your own URL. Apart from the headers shown, we don't expose additional -pagination headers. - -Keyset-based pagination is supported only for selected resources and ordering -options: - -| Resource | Order | -|-------------------------|-------| -| [Projects](projects.md) | `order_by=id` only. | - -## Path parameters - -If an endpoint has path parameters, the documentation displays them with a -preceding colon. - -For example: - -```plaintext -DELETE /projects/:id/share/:group_id -``` - -The `:id` path parameter needs to be replaced with the project ID, and the -`:group_id` needs to be replaced with the ID of the group. The colons `:` -shouldn't be included. - -The resulting cURL request for a project with ID `5` and a group ID of `17` is then: - -```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17" -``` - -Path parameters that are required to be URL-encoded must be followed. If not, -it doesn't match an API endpoint and responds with a 404. If there's -something in front of the API (for example, Apache), ensure that it doesn't decode -the URL-encoded path parameters. - -## Namespaced path encoding - -If using namespaced API requests, make sure that the `NAMESPACE/PROJECT_PATH` is -URL-encoded. - -For example, `/` is represented by `%2F`: - -```plaintext -GET /api/v4/projects/diaspora%2Fdiaspora -``` - -A project's _path_ isn't necessarily the same as its _name_. A project's path is -found in the project's URL or in the project's settings, under -**General > Advanced > Change path**. - -## File path, branches, and tags name encoding - -If a file path, branch or tag contains a `/`, make sure it is URL-encoded. - -For example, `/` is represented by `%2F`: - -```plaintext -GET /api/v4/projects/1/repository/files/src%2FREADME.md?ref=master -GET /api/v4/projects/1/branches/my%2Fbranch/commits -GET /api/v4/projects/1/repository/tags/my%2Ftag -``` - -## Request Payload - -API Requests can use parameters sent as [query strings](https://en.wikipedia.org/wiki/Query_string) -or as a [payload body](https://tools.ietf.org/html/draft-ietf-httpbis-p3-payload-14#section-3.2). -GET requests usually send a query string, while PUT or POST requests usually -send the payload body: - -- Query string: - - ```shell - curl --request POST "https://gitlab/api/v4/projects?name=<example-name>&description=<example-description>" - ``` - -- Request payload (JSON): - - ```shell - curl --request POST --header "Content-Type: application/json" \ - --data '{"name":"<example-name>", "description":"<example-description"}' "https://gitlab/api/v4/projects" - ``` - -URL encoded query strings have a length limitation. Requests that are too large -result in a `414 Request-URI Too Large` error message. This can be resolved by -using a payload body instead. - -## Encoding API parameters of `array` and `hash` types - -You can request the API with `array` and `hash` types parameters: - -### `array` - -`import_sources` is a parameter of type `array`: - -```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ --d "import_sources[]=github" \ --d "import_sources[]=bitbucket" \ -"https://gitlab.example.com/api/v4/some_endpoint" -``` - -### `hash` - -`override_params` is a parameter of type `hash`: - -```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ ---form "namespace=email" \ ---form "path=impapi" \ ---form "file=@/path/to/somefile.txt" ---form "override_params[visibility]=private" \ ---form "override_params[some_other_param]=some_value" \ -"https://gitlab.example.com/api/v4/projects/import" -``` - -### Array of hashes - -`variables` is a parameter of type `array` containing hash key/value pairs -`[{ 'key': 'UPLOAD_TO_S3', 'value': 'true' }]`: - -```shell -curl --globoff --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ -"https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[][key]=VAR1&variables[][value]=hello&variables[][key]=VAR2&variables[][value]=world" - -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ ---header "Content-Type: application/json" \ ---data '{ "ref": "master", "variables": [ {"key": "VAR1", "value": "hello"}, {"key": "VAR2", "value": "world"} ] }' \ -"https://gitlab.example.com/api/v4/projects/169/pipeline" -``` - -## `id` vs `iid` - -Some resources have two similarly-named fields. For example, [issues](issues.md), -[merge requests](merge_requests.md), and [project milestones](merge_requests.md). -The fields are: - -- `id`: ID that is unique across all projects. -- `iid`: Additional, internal ID (displayed in the web UI) that's unique in the - scope of a single project. - -If a resource has both the `iid` field and the `id` field, the `iid` field is -usually used instead of `id` to fetch the resource. - -For example, suppose a project with `id: 42` has an issue with `id: 46` and -`iid: 5`. In this case: - -- A valid API request to retrieve the issue is `GET /projects/42/issues/5`. -- An invalid API request to retrieve the issue is `GET /projects/42/issues/46`. - -Not all resources with the `iid` field are fetched by `iid`. For guidance -regarding which field to use, see the documentation for the specific resource. - -## Data validation and error reporting - -When working with the API you may encounter validation errors, in which case -the API returns an HTTP `400` error. - -Such errors appear in the following cases: - -- A required attribute of the API request is missing (for example, the title of - an issue isn't given). -- An attribute did not pass the validation (for example, the user bio is too - long). - -When an attribute is missing, you receive something like: - -```http -HTTP/1.1 400 Bad Request -Content-Type: application/json -{ - "message":"400 (Bad request) \"title\" not given" -} -``` - -When a validation error occurs, error messages are different. They hold -all details of validation errors: - -```http -HTTP/1.1 400 Bad Request -Content-Type: application/json -{ - "message": { - "bio": [ - "is too long (maximum is 255 characters)" - ] - } -} -``` - -This makes error messages more machine-readable. The format can be described as -follows: - -```json -{ - "message": { - "<property-name>": [ - "<error-message>", - "<error-message>", - ... - ], - "<embed-entity>": { - "<property-name>": [ - "<error-message>", - "<error-message>", - ... - ], - } - } -} -``` - -## Unknown route - -When you attempt to access an API URL that doesn't exist, you receive a -404 Not Found message. - -```http -HTTP/1.1 404 Not Found -Content-Type: application/json -{ - "error": "404 Not Found" -} -``` - -## Encoding `+` in ISO 8601 dates - -If you need to include a `+` in a query parameter, you may need to use `%2B` -instead, due to a [W3 recommendation](http://www.w3.org/Addressing/URL/4_URI_Recommentations.html) -that causes a `+` to be interpreted as a space. For example, in an ISO 8601 date, -you may want to include a specific time in ISO 8601 format, such as: - -```plaintext -2017-10-17T23:11:13.000+05:30 -``` - -The correct encoding for the query parameter would be: - -```plaintext -2017-10-17T23:11:13.000%2B05:30 -``` - -## Clients - -There are many unofficial GitLab API Clients for most of the popular programming -languages. For a complete list, visit the [GitLab website](https://about.gitlab.com/partners/technology-partners/#api-clients). - -## Rate limits - -For administrator documentation on rate limit settings, see -[Rate limits](../security/rate_limits.md). To find the settings that are -specifically used by GitLab.com, see -[GitLab.com-specific rate limits](../user/gitlab_com/index.md#gitlabcom-specific-rate-limits). - -## Content type - -The GitLab API supports the `application/json` content type by default, though -some API endpoints also support `text/plain`. - -In [GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/250342), -API endpoints do not support `text/plain` by default, unless it's explicitly documented. +<!-- This redirect file can be deleted after 2021-09-28. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index db68c140ae6..8ef3e882209 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -33,7 +33,7 @@ GET /projects/:id/access_requests | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | Example request: @@ -76,7 +76,7 @@ POST /projects/:id/access_requests | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | Example request: @@ -109,9 +109,9 @@ PUT /projects/:id/access_requests/:user_id/approve | Attribute | Type | Required | Description | | -------------- | -------------- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the access requester | -| `access_level` | integer | no | A valid access level (defaults: `30`, developer access level) | +| `access_level` | integer | no | A valid access level (defaults: `30`, the Developer role) | Example request: @@ -144,7 +144,7 @@ DELETE /projects/:id/access_requests/:user_id | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the access requester | Example request: diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 9200d47effe..6c9baab83e9 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -4,9 +4,9 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# API resources **(FREE)** +# REST API resources **(FREE)** -Available resources for the [GitLab API](README.md) can be grouped in the following contexts: +Available resources for the [GitLab REST API](index.md) can be grouped in the following contexts: - [Projects](#project-resources). - [Groups](#group-resources). @@ -34,6 +34,7 @@ The following API resources are available in the project context: | [Dependencies](dependencies.md) **(ULTIMATE)** | `/projects/:id/dependencies` | | [Deploy keys](deploy_keys.md) | `/projects/:id/deploy_keys` (also available standalone) | | [Freeze Periods](freeze_periods.md) | `/projects/:id/freeze_periods` | +| [Debian distributions](packages/debian_project_distributions.md) | `/projects/:id/debian_distributions` (also available for groups) | | [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` (also available for groups) | | [Environments](environments.md) | `/projects/:id/environments` | @@ -99,6 +100,7 @@ The following API resources are available in the group context: |:-----------------------------------------------------------------|:---------------------------------------------------------------------------------| | [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) | +| [Debian distributions](packages/debian_group_distributions.md) | `/groups/:id/-/packages/debian` (also available for projects) | | [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` | @@ -168,7 +170,7 @@ The following API resources are available outside of project and group contexts | [Suggestions](suggestions.md) | `/suggestions` | | [System hooks](system_hooks.md) | `/hooks` | | [To-dos](todos.md) | `/todos` | -| [Usage data](usage_data.md) | `/usage_data` (For GitLab instance [Administrator](../user/permissions.md) users only) | +| [Service Data](usage_data.md) | `/usage_data` (For GitLab instance [Administrator](../user/permissions.md) users only) | | [Users](users.md) | `/users` | | [Validate `.gitlab-ci.yml` file](lint.md) | `/lint` | | [Version](version.md) | `/version` | diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md index dec2b85c61d..8fbee89f9be 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.md @@ -4,7 +4,7 @@ group: Compliance info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Audit Events API +# Audit Events API **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/121) in GitLab 12.4. @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The Audit Events API allows you to retrieve [instance audit events](../administration/audit_events.md#instance-events). This API cannot retrieve group or project audit events. -To retrieve audit events using the API, you must [authenticate yourself](README.md#authentication) as an Administrator. +To retrieve audit events using the API, you must [authenticate yourself](index.md#authentication) as an Administrator. ### Retrieve all instance audit events @@ -31,7 +31,7 @@ GET /audit_events By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](README.md#pagination). +Read more on [pagination](index.md#pagination). ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/audit_events" @@ -129,7 +129,7 @@ Example response: } ``` -## Group Audit Events **(PREMIUM)** +## Group Audit Events > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34078) in GitLab 12.5. @@ -147,14 +147,14 @@ GET /groups/:id/audit_events | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `created_after` | string | no | Return group audit events created on or after the given time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | | `created_before` | string | no | Return group audit events created on or before the given time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](README.md#pagination). +Read more on [pagination](index.md#pagination). ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/groups/60/audit_events" @@ -209,7 +209,7 @@ GET /groups/:id/audit_events/:audit_event_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `audit_event_id` | integer | yes | The ID of the audit event | ```shell @@ -237,7 +237,7 @@ Example response: } ``` -## Project Audit Events **(PREMIUM)** +## Project Audit Events > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219238) in GitLab 13.1. @@ -254,14 +254,14 @@ GET /projects/:id/audit_events | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `created_after` | string | no | Return project audit events created on or after the given time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | | `created_before` | string | no | Return project audit events created on or before the given time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](README.md#pagination). +Read more on [pagination](index.md#pagination). ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/projects/7/audit_events" @@ -320,7 +320,7 @@ GET /projects/:id/audit_events/:audit_event_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `audit_event_id` | integer | yes | The ID of the audit event | ```shell diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md index 32ac6ef26ea..dc3dc9fcaca 100644 --- a/doc/api/award_emoji.md +++ b/doc/api/award_emoji.md @@ -4,9 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Award Emoji API - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4575) in GitLab 8.9. Snippet support added in 8.12. +# Award emoji API **(FREE)** An [awarded emoji](../user/award_emojis.md) tells a thousand words. @@ -37,7 +35,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | Example request: @@ -99,7 +97,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | | `award_id` | integer | yes | ID of the award emoji. | @@ -144,7 +142,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | | `name` | string | yes | Name of the emoji without colons. | @@ -189,7 +187,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | | `award_id` | integer | yes | ID of an award emoji. | @@ -218,7 +216,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | Internal ID of an issue. | | `note_id` | integer | yes | ID of a comment (note). | @@ -263,7 +261,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | Internal ID of an issue. | | `note_id` | integer | yes | ID of a comment (note). | | `award_id` | integer | yes | ID of the award emoji. | @@ -307,7 +305,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | Internal ID of an issue. | | `note_id` | integer | yes | ID of a comment (note). | | `name` | string | yes | Name of the emoji without colons. | @@ -353,7 +351,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | Internal ID of an issue. | | `note_id` | integer | yes | ID of a comment (note). | | `award_id` | integer | yes | ID of an award_emoji. | diff --git a/doc/api/boards.md b/doc/api/boards.md index 3cdd9552d66..3288aefb1cf 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -4,9 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project Issue Boards API +# Project issue boards API **(FREE)** -Every API call to boards must be authenticated. +Every API call to [issue boards](../user/project/issue_board.md) must be authenticated. If a user is not a member of a private project, a `GET` request on that project results in a `404` status code. @@ -21,7 +21,7 @@ GET /projects/:id/boards | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards" @@ -105,7 +105,7 @@ GET /projects/:id/boards/:board_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -182,7 +182,7 @@ POST /projects/:id/boards | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the new board | ```shell @@ -225,7 +225,7 @@ PUT /projects/:id/boards/:board_id | Attribute | Type | Required | Description | | ---------------------------- | -------------- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `name` | string | no | The new name of the board | | `assignee_id` **(PREMIUM)** | integer | no | The assignee the board should be scoped to | @@ -305,7 +305,7 @@ DELETE /projects/:id/boards/:board_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -323,7 +323,7 @@ GET /projects/:id/boards/:board_id/lists | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -383,7 +383,7 @@ GET /projects/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id`| integer | yes | The ID of a board's list | @@ -418,7 +418,7 @@ POST /projects/:id/boards/:board_id/lists | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `label_id` | integer | no | The ID of a label | | `assignee_id` **(PREMIUM)** | integer | no | The ID of a user | @@ -461,7 +461,7 @@ PUT /projects/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | | `position` | integer | yes | The position of the list | @@ -497,7 +497,7 @@ DELETE /projects/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | diff --git a/doc/api/branches.md b/doc/api/branches.md index 2fb9997bdca..15d1b6c2a18 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -26,7 +26,7 @@ Parameters: | 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](index.md#namespaced-path-encoding) owned by the authenticated user.| | `search` | string | no | Return list of branches containing the search string. You can use `^term` and `term$` to find branches that begin and end with `term` respectively. | Example request: @@ -83,7 +83,7 @@ Parameters: | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `branch` | string | yes | Name of the branch. | Example request: @@ -144,7 +144,7 @@ Parameters: | Attribute | Type | Required | Description | |:----------|:--------|:---------|:-------------------------------------------------------------------------------------------------------------| -| `id` | integer | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `branch` | string | yes | Name of the branch. | | `ref` | string | yes | Branch name or commit SHA to create branch from. | @@ -199,7 +199,7 @@ Parameters: | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `branch` | string | yes | Name of the branch. | Example request: @@ -223,7 +223,7 @@ Parameters: | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | Example request: diff --git a/doc/api/bulk_imports.md b/doc/api/bulk_imports.md new file mode 100644 index 00000000000..9521c769d49 --- /dev/null +++ b/doc/api/bulk_imports.md @@ -0,0 +1,193 @@ +--- +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# GitLab Migrations (Bulk Imports) API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64335) in GitLab 14.1. + +With the GitLab Migrations API, you can view the progress of migrations initiated with +[GitLab Group Migration](../user/group/import/index.md). + +## List all GitLab migrations + +```plaintext +GET /bulk_imports +``` + +| Attribute | Type | Required | Description | +|:-----------|:--------|:---------|:---------------------------------------| +| `per_page` | integer | no | Number of records to return per page. | +| `page` | integer | no | Page to retrieve. | +| `status` | string | no | Import status. | + +The status can be one of the following: + +- `created` +- `started` +- `finished` +- `failed` + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/bulk_imports?per_page=2&page=1" +``` + +```json +[ + { + "id": 1, + "status": "finished", + "source_type": "gitlab", + "created_at": "2021-06-18T09:45:55.358Z", + "updated_at": "2021-06-18T09:46:27.003Z" + }, + { + "id": 2, + "status": "started", + "source_type": "gitlab", + "created_at": "2021-06-18T09:47:36.581Z", + "updated_at": "2021-06-18T09:47:58.286Z" + } +] +``` + +## List all GitLab migrations' entities + +```plaintext +GET /bulk_imports/entities +``` + +| Attribute | Type | Required | Description | +|:-----------|:--------|:---------|:---------------------------------------| +| `per_page` | integer | no | Number of records to return per page. | +| `page` | integer | no | Page to retrieve. | +| `status` | string | no | Import status. | + +The status can be one of the following: + +- `created` +- `started` +- `finished` +- `failed` + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/bulk_imports/entities?per_page=2&page=1&status=started" +``` + +```json +[ + { + "id": 1, + "bulk_import_id": 1, + "status": "finished", + "source_full_path": "source_group", + "destination_name": "destination_name", + "destination_namespace": "destination_path", + "parent_id": null, + "namespace_id": 1, + "project_id": null, + "created_at": "2021-06-18T09:47:37.390Z", + "updated_at": "2021-06-18T09:47:51.867Z", + "failures": [] + }, + { + "id": 2, + "bulk_import_id": 2, + "status": "failed", + "source_full_path": "another_group", + "destination_name": "another_name", + "destination_namespace": "another_namespace", + "parent_id": null, + "namespace_id": null, + "project_id": null, + "created_at": "2021-06-24T10:40:20.110Z", + "updated_at": "2021-06-24T10:40:46.590Z", + "failures": [ + { + "pipeline_class": "BulkImports::Groups::Pipelines::GroupPipeline", + "pipeline_step": "extractor", + "exception_class": "Exception", + "correlation_id_value": "dfcf583058ed4508e4c7c617bd7f0edd", + "created_at": "2021-06-24T10:40:46.495Z" + } + ] + } +] +``` + +## Get GitLab migration details + +```plaintext +GET /bulk_imports/:id +``` + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/bulk_imports/1" +``` + +```json +{ + "id": 1, + "status": "finished", + "source_type": "gitlab", + "created_at": "2021-06-18T09:45:55.358Z", + "updated_at": "2021-06-18T09:46:27.003Z" +} +``` + +## List GitLab migration entities + +```plaintext +GET /bulk_imports/:id/entities +``` + +| Attribute | Type | Required | Description | +|:-----------|:--------|:---------|:---------------------------------------| +| `per_page` | integer | no | Number of records to return per page. | +| `page` | integer | no | Page to retrieve. | +| `status` | string | no | Import status. | + +The status can be one of the following: + +- `created` +- `started` +- `finished` +- `failed` + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/bulk_imports/1/entities?per_page=2&page=1&status=finished" +``` + +```json +[ + { + "id": 1, + "status": "finished", + "source_type": "gitlab", + "created_at": "2021-06-18T09:45:55.358Z", + "updated_at": "2021-06-18T09:46:27.003Z" + } +] +``` + +## Get GitLab migration entity details + +```plaintext +GET /bulk_imports/:id/entities/:entity_id +``` + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/bulk_imports/1/entities/2" +``` + +```json +{ + "id": 1, + "status": "finished", + "source_type": "gitlab", + "created_at": "2021-06-18T09:45:55.358Z", + "updated_at": "2021-06-18T09:46:27.003Z" +} +``` diff --git a/doc/api/commits.md b/doc/api/commits.md index 711b565bdbd..e164532e0eb 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -19,7 +19,7 @@ GET /projects/:id/repository/commits | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | `ref_name` | string | no | The name of a repository branch, tag or revision range, or if not given the default branch | | `since` | string | no | Only commits after or on this date are returned in ISO 8601 format `YYYY-MM-DDTHH:MM:SSZ` | | `until` | string | no | Only commits before or on this date are returned in ISO 8601 format `YYYY-MM-DDTHH:MM:SSZ` | @@ -85,12 +85,12 @@ POST /projects/:id/repository/commits | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `branch` | string | yes | Name of the branch to commit into. To create a new branch, also provide either `start_branch` or `start_sha`, and optionally `start_project`. | | `commit_message` | string | yes | Commit message | | `start_branch` | string | no | Name of the branch to start the new branch from | | `start_sha` | string | no | SHA of the commit to start the new branch from | -| `start_project` | integer/string | no | The project ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) to start the new branch from. Defaults to the value of `id`. | +| `start_project` | integer/string | no | The project ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) to start the new branch from. Defaults to the value of `id`. | | `actions[]` | array | yes | An array of action hashes to commit as a batch. See the next table for what attributes it can take. | | `author_email` | string | no | Specify the commit author's email address | | `author_name` | string | no | Specify the commit author's name | @@ -174,7 +174,7 @@ Example response: } ``` -GitLab supports [form encoding](README.md#encoding-api-parameters-of-array-and-hash-types). The following is an example using Commit API with form encoding: +GitLab supports [form encoding](index.md#encoding-api-parameters-of-array-and-hash-types). The following is an example using Commit API with form encoding: ```shell curl --request POST \ @@ -212,7 +212,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | | `stats` | boolean | no | Include commit stats. Default is true | @@ -269,7 +269,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash | | `type` | string | no | The scope of commits. Possible values `branch`, `tag`, `all`. Default is `all`. | @@ -303,7 +303,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `sha` | string | yes | The commit hash | | `branch` | string | yes | The name of the branch | | `dry_run` | boolean | no | Does not commit any changes. Default is false. [Introduced in GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/231032) | @@ -378,7 +378,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `sha` | string | yes | Commit SHA to revert | | `branch` | string | yes | Target branch name | | `dry_run` | boolean | no | Does not commit any changes. Default is false. [Introduced in GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/231032) | @@ -446,7 +446,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell @@ -482,7 +482,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell @@ -531,7 +531,7 @@ POST /projects/:id/repository/commits/:sha/comments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA or name of a repository branch or tag | | `note` | string | yes | The text of the comment | | `path` | string | no | The file path relative to the repository | @@ -576,7 +576,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell @@ -635,11 +635,11 @@ GET /projects/:id/repository/commits/:sha/statuses | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA | `ref` | string | no | The name of a repository branch or tag or, if not given, the default branch -| `stage` | string | no | Filter by [build stage](../ci/yaml/README.md#stages), e.g., `test` -| `name` | string | no | Filter by [job name](../ci/yaml/README.md#job-keywords), e.g., `bundler:audit` +| `stage` | string | no | Filter by [build stage](../ci/yaml/index.md#stages), for example, `test` +| `name` | string | no | Filter by [job name](../ci/yaml/index.md#job-keywords), for example, `bundler:audit` | `all` | boolean | no | Return all statuses, not only the latest ones ```shell @@ -709,7 +709,7 @@ POST /projects/:id/statuses/:sha | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA | `state` | string | yes | The state of the status. Can be one of the following: `pending`, `running`, `success`, `failed`, `canceled` | `ref` | string | no | The `ref` (branch or tag) to which the status refers @@ -762,7 +762,7 @@ GET /projects/:id/repository/commits/:sha/merge_requests | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA ```shell @@ -834,7 +834,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index 4de024da2de..cf5a7f89c8b 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -42,7 +42,7 @@ GET /projects/:id/registry/repositories | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) accessible by the authenticated user. | | `tags` | boolean | no | If the parameter is included as true, each repository includes an array of `"tags"` in the response. | | `tags_count` | boolean | no | If the parameter is included as true, each repository includes `"tags_count"` in the response ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32141) in GitLab 13.1). | @@ -85,7 +85,7 @@ GET /groups/:id/registry/repositories | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) accessible by the authenticated user. | | `tags` | boolean | no | If the parameter is included as true, each repository includes an array of `"tags"` in the response. | | `tags_count` | boolean | no | If the parameter is included as true, each repository includes `"tags_count"` in the response ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32141) in GitLab 13.1). | @@ -200,7 +200,7 @@ DELETE /projects/:id/registry/repositories/:repository_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | ```shell @@ -220,7 +220,7 @@ GET /projects/:id/registry/repositories/:repository_id/tags | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) accessible by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | ```shell @@ -255,7 +255,7 @@ GET /projects/:id/registry/repositories/:repository_id/tags/:tag_name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) accessible by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | | `tag_name` | string | yes | The name of tag. | @@ -289,7 +289,7 @@ DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | | `tag_name` | string | yes | The name of tag. | @@ -314,7 +314,7 @@ DELETE /projects/:id/registry/repositories/:repository_id/tags | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | | `name_regex` | string | no | The [re2](https://github.com/google/re2/wiki/Syntax) regex of the name to delete. To delete all tags specify `.*`. **Note:** `name_regex` is deprecated in favor of `name_regex_delete`. This field is validated. | | `name_regex_delete` | string | yes | The [re2](https://github.com/google/re2/wiki/Syntax) regex of the name to delete. To delete all tags specify `.*`. This field is validated. | diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md index 6175c26ed75..c85a3521aed 100644 --- a/doc/api/dependencies.md +++ b/doc/api/dependencies.md @@ -30,7 +30,7 @@ GET /projects/:id/dependencies?package_manager=yarn,bundler | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `package_manager` | string array | no | Returns dependencies belonging to specified package manager. Valid values: `bundler`, `composer`, `maven`, `npm`, `pip` or `yarn`. | ```shell diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md index 139669c018c..e9ddc1e9df9 100644 --- a/doc/api/dependency_proxy.md +++ b/doc/api/dependency_proxy.md @@ -23,7 +23,7 @@ DELETE /groups/:id/dependency_proxy/cache | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | Example request: diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index 3b063180900..3d6d680e3e4 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -47,7 +47,7 @@ GET /projects/:id/deploy_keys | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/deploy_keys" @@ -86,7 +86,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `key_id` | integer | yes | The ID of the deploy key | ```shell @@ -118,7 +118,7 @@ POST /projects/:id/deploy_keys | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | New deploy key's title | | `key` | string | yes | New deploy key | | `can_push` | boolean | no | Can deploy key push to the project's repository | @@ -151,7 +151,7 @@ PUT /projects/:id/deploy_keys/:key_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | no | New deploy key's title | | `can_push` | boolean | no | Can deploy key push to the project's repository | @@ -182,7 +182,7 @@ DELETE /projects/:id/deploy_keys/:key_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `key_id` | integer | yes | The ID of the deploy key | ```shell @@ -199,7 +199,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `key_id` | integer | yes | The ID of the deploy key | Example response: diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index d8aab8896a1..6ed8f76583f 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -66,7 +66,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:-----------------------|:------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `active` | boolean | **{dotted-circle}** No | Limit by active status. | Example request: @@ -108,7 +108,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | ---------------- | ---------------------- | ----------- | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | **{check-circle}** Yes | New deploy token's name | | `expires_at` | datetime | **{dotted-circle}** No | Expiration date for the deploy token. Does not expire if no value is provided. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `username` | string | **{dotted-circle}** No | Username for deploy token. Default is `gitlab+deploy-token-{n}` | @@ -153,7 +153,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------- | -------------- | ---------------------- | ----------- | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `token_id` | integer | **{check-circle}** Yes | The ID of the deploy token | Example request: @@ -182,7 +182,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:-----------------------|:------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `active` | boolean | **{dotted-circle}** No | Limit by active status. | Example request: @@ -224,7 +224,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | ---- | --------- | ----------- | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | **{check-circle}** Yes | New deploy token's name | | `expires_at` | datetime | **{dotted-circle}** No | Expiration date for the deploy token. Does not expire if no value is provided. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `username` | string | **{dotted-circle}** No | Username for deploy token. Default is `gitlab+deploy-token-{n}` | @@ -269,7 +269,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------- | -------------- | ---------------------- | ----------- | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `token_id` | integer | **{check-circle}** Yes | The ID of the deploy token | Example request: diff --git a/doc/api/deployments.md b/doc/api/deployments.md index a2e56fc8557..3ed431cf63d 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -17,7 +17,7 @@ GET /projects/:id/deployments | Attribute | Type | Required | Description | |------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `order_by` | string | no | Return deployments ordered by either one of `id`, `iid`, `created_at`, `updated_at` or `ref` fields. Default is `id`. | | `sort` | string | no | Return deployments sorted in `asc` or `desc` order. Default is `asc`. | | `updated_after` | datetime | no | Return deployments updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | @@ -184,7 +184,7 @@ GET /projects/:id/deployments/:deployment_id | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `deployment_id` | integer | yes | The ID of the deployment | ```shell @@ -272,7 +272,7 @@ POST /projects/:id/deployments | Attribute | Type | Required | Description | |---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user.| | `environment` | string | yes | The [name of the environment](../ci/environments/index.md) to create the deployment for. | | `sha` | string | yes | The SHA of the commit that is deployed. | | `ref` | string | yes | The name of the branch or tag that is deployed. | @@ -319,7 +319,7 @@ PUT /projects/:id/deployments/:deployment_id | Attribute | Type | Required | Description | |------------------|----------------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `deployment_id` | integer | yes | The ID of the deployment to update. | | `status` | string | no | The new status of the deployment. One of `created`, `running`, `success`, `failed`, or `canceled`. | diff --git a/doc/api/discussions.md b/doc/api/discussions.md index d8d989adfe2..9e9b9dcc901 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -21,7 +21,7 @@ This includes system notes, which are notes about changes to the object (for exa By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](README.md#pagination). +Read more on [pagination](index.md#pagination). ## Issues @@ -35,7 +35,7 @@ GET /projects/:id/issues/:issue_iid/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | ```json @@ -133,7 +133,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `discussion_id` | integer | yes | The ID of a discussion item | @@ -153,7 +153,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `body` | string | yes | The content of the thread | | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -164,7 +164,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla ### Add note to existing issue thread -Adds a new note to the thread. This can also [create a thread from a single comment](../user/discussions/#start-a-thread-by-replying-to-a-standard-comment). +Adds a new note to the thread. This can also [create a thread from a single comment](../user/discussions/#create-a-thread-by-replying-to-a-standard-comment). **WARNING** Notes can be added to other items than comments, such as system notes, making them threads. @@ -177,7 +177,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -200,7 +200,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -222,7 +222,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `discussion_id` | integer | yes | The ID of a discussion | | `note_id` | integer | yes | The ID of a discussion note | @@ -243,7 +243,7 @@ GET /projects/:id/snippets/:snippet_id/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | ```json @@ -341,7 +341,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `discussion_id` | integer | yes | The ID of a discussion item | @@ -362,7 +362,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `body` | string | yes | The content of a discussion | | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -383,7 +383,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -406,7 +406,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -428,7 +428,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `discussion_id` | integer | yes | The ID of a discussion | | `note_id` | integer | yes | The ID of a discussion note | @@ -449,7 +449,7 @@ GET /groups/:id/epics/:epic_id/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | ```json @@ -548,7 +548,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `discussion_id` | integer | yes | The ID of a discussion item | @@ -569,7 +569,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `body` | string | yes | The content of the thread | | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -581,7 +581,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla ### Add note to existing epic thread Adds a new note to the thread. This can also -[create a thread from a single comment](../user/discussions/#start-a-thread-by-replying-to-a-standard-comment). +[create a thread from a single comment](../user/discussions/#create-a-thread-by-replying-to-a-standard-comment). ```plaintext POST /groups/:id/epics/:epic_id/discussions/:discussion_id/notes @@ -591,7 +591,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -614,7 +614,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -636,7 +636,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -657,7 +657,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | ```json @@ -820,7 +820,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a discussion item | @@ -843,7 +843,7 @@ Parameters for all comments: | Attribute | Type | Required | Description | | ---------------------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `body` | string | yes | The content of the thread | | `commit_id` | string | no | SHA referencing commit to start this thread on | @@ -954,7 +954,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a thread | | `resolved` | boolean | yes | Resolve/unresolve the discussion | @@ -966,7 +966,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab ### Add note to existing merge request thread Adds a new note to the thread. This can also -[create a thread from a single comment](../user/discussions/#start-a-thread-by-replying-to-a-standard-comment). +[create a thread from a single comment](../user/discussions/#create-a-thread-by-replying-to-a-standard-comment). ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id/notes @@ -976,7 +976,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -999,7 +999,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1028,7 +1028,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1049,7 +1049,7 @@ GET /projects/:id/commits/:commit_id/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `commit_id` | integer | yes | The ID of a commit | ```json @@ -1192,7 +1192,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `commit_id` | integer | yes | The ID of a commit | | `discussion_id` | integer | yes | The ID of a discussion item | @@ -1213,7 +1213,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `commit_id` | integer | yes | The ID of a commit | | `body` | string | yes | The content of the thread | | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -1247,7 +1247,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `commit_id` | integer | yes | The ID of a commit | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1270,7 +1270,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `commit_id` | integer | yes | The ID of a commit | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1298,7 +1298,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `commit_id` | integer | yes | The ID of a commit | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md index 99826550b61..38f1f50839e 100644 --- a/doc/api/dora/metrics.md +++ b/doc/api/dora/metrics.md @@ -22,7 +22,7 @@ GET /projects/:id/dora/metrics | Attribute | Type | Required | Description | |-------------- |-------- |----------|----------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding) can be accessed by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) can be accessed by the authenticated user. | | `metric` | string | yes | The [metric name](../../user/analytics/ci_cd_analytics.md#supported-metrics-in-gitlab). One of `deployment_frequency` or `lead_time_for_changes`. | | `start_date` | string | no | Date range to start from. ISO 8601 Date format, for example `2021-03-01`. Default is 3 months ago. | | `end_date` | string | no | Date range to end at. ISO 8601 Date format, for example `2021-03-01`. Default is the current date. | @@ -62,7 +62,7 @@ GET /groups/:id/dora/metrics | Attribute | Type | Required | Description | |-------------- |-------- |----------|----------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding) can be accessed by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) can be accessed by the authenticated user. | | `metric` | string | yes | The [metric name](../../user/analytics/ci_cd_analytics.md#supported-metrics-in-gitlab). One of `deployment_frequency` or `lead_time_for_changes`. | | `start_date` | string | no | Date range to start from. ISO 8601 Date format, for example `2021-03-01`. Default is 3 months ago. | | `end_date` | string | no | Date range to end at. ISO 8601 Date format, for example `2021-03-01`. Default is the current date. | diff --git a/doc/api/environments.md b/doc/api/environments.md index 4c93b3b15d5..25690cc099a 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -17,7 +17,7 @@ GET /projects/:id/environments | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | no | Return the environment with this name. Mutually exclusive with `search` | | `search` | string | no | Return list of environments matching the search criteria. Mutually exclusive with `name` | | `states` | string | no | List all environments that match a specific state. Accepted values: `available` or `stopped`. If no state value given, returns all environments. | @@ -48,7 +48,7 @@ GET /projects/:id/environments/:environment_id | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `environment_id` | integer | yes | The ID of the environment | ```shell @@ -159,7 +159,7 @@ POST /projects/:id/environments | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the environment | | `external_url` | string | no | Place to link to for this environment | @@ -192,7 +192,7 @@ PUT /projects/:id/environments/:environments_id | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `environment_id` | integer | yes | The ID of the environment | | `name` | string | no | The new name of the environment | | `external_url` | string | no | The new `external_url` | @@ -224,7 +224,7 @@ DELETE /projects/:id/environments/:environment_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `environment_id` | integer | yes | The ID of the environment | ```shell @@ -241,7 +241,7 @@ POST /projects/:id/environments/:environment_id/stop | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `environment_id` | integer | yes | The ID of the environment | ```shell diff --git a/doc/api/epic_issues.md b/doc/api/epic_issues.md index 3644375ad0a..dfc54cd81aa 100644 --- a/doc/api/epic_issues.md +++ b/doc/api/epic_issues.md @@ -16,7 +16,7 @@ If the Epics feature is not available, a `403` status code is returned. ## Epic Issues pagination -API results [are paginated](README.md#pagination). Requests that return +API results [are paginated](index.md#pagination). Requests that return multiple issues default to returning 20 results at a time. ## List issues for an epic @@ -29,7 +29,7 @@ GET /groups/:id/epics/:epic_iid/issues | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | ```shell @@ -124,7 +124,7 @@ POST /groups/:id/epics/:epic_iid/issues/:issue_id | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | | `issue_id` | integer/string | yes | The ID of the issue. | @@ -230,7 +230,7 @@ DELETE /groups/:id/epics/:epic_iid/issues/:epic_issue_id | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | -----------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | | `epic_issue_id` | integer/string | yes | The ID of the issue - epic association. | @@ -336,7 +336,7 @@ PUT /groups/:id/epics/:epic_iid/issues/:epic_issue_id | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | -----------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | | `epic_issue_id` | integer/string | yes | The ID of the issue - epic association. | | `move_before_id` | integer/string | no | The ID of the issue - epic association that should be placed before the link in the question. | diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index e570b9f31cf..5d8a92d0263 100644 --- a/doc/api/epic_links.md +++ b/doc/api/epic_links.md @@ -28,7 +28,7 @@ GET /groups/:id/epics/:epic_iid/epics | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer | yes | The internal ID of the epic. | ```shell @@ -82,7 +82,7 @@ POST /groups/:id/epics/:epic_iid/epics/:child_epic_id | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer | yes | The internal ID of the epic. | | `child_epic_id` | integer | yes | The global ID of the child epic. Internal ID can't be used because they can conflict with epics from other groups. | @@ -135,7 +135,7 @@ POST /groups/:id/epics/:epic_iid/epics | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer | yes | The internal ID of the (future parent) epic. | | `title` | string | yes | The title of a newly created epic. | | `confidential` | boolean | no | Whether the epic should be confidential. Parameter is ignored if `confidential_epics` feature flag is disabled. Defaults to the confidentiality state of the parent epic. | @@ -169,7 +169,7 @@ PUT /groups/:id/epics/:epic_iid/epics/:child_epic_id | Attribute | Type | Required | Description | | ---------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | | `epic_iid` | integer | yes | The internal ID of the epic. | | `child_epic_id` | integer | yes | The global ID of the child epic. Internal ID can't be used because they can conflict with epics from other groups. | | `move_before_id` | integer | no | The global ID of a sibling epic that should be placed before the child epic. | @@ -226,7 +226,7 @@ DELETE /groups/:id/epics/:epic_iid/epics/:child_epic_id | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | | `epic_iid` | integer | yes | The internal ID of the epic. | | `child_epic_id` | integer | yes | The global ID of the child epic. Internal ID can't be used because they can conflict with epics from other groups. | diff --git a/doc/api/epics.md b/doc/api/epics.md index d501d61bfb8..263cfe5806e 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -37,7 +37,7 @@ fields `start_date_is_fixed` and `due_date_is_fixed`, and four date fields `star By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](README.md#pagination). +Read more on [pagination](index.md#pagination). WARNING: > `reference` attribute in response is deprecated in favour of `references`. @@ -60,11 +60,11 @@ GET /groups/:id/epics?state=opened | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `author_id` | integer | no | Return epics created by the given user `id` | | `labels` | string | no | Return epics matching a comma separated list of labels names. Label names from the epic group or a parent group can be used | | `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Available in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) and later | -| `order_by` | string | no | Return epics ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `order_by` | string | no | Return epics ordered by `created_at`, `updated_at`, or `title` fields. Default is `created_at` | | `sort` | string | no | Return epics sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search epics against their `title` and `description` | | `state` | string | no | Search epics against their `state`, possible filters: `opened`, `closed` and `all`, default: `all` | @@ -190,7 +190,7 @@ GET /groups/:id/epics/:epic_iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | ```shell @@ -263,7 +263,7 @@ POST /groups/:id/epics | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | The title of the epic | | `labels` | string | no | The comma separated list of labels | | `description` | string | no | The description of the epic. Limited to 1,048,576 characters. | @@ -345,7 +345,7 @@ PUT /groups/:id/epics/:epic_iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic | | `title` | string | no | The title of an epic | | `description` | string | no | The description of an epic. Limited to 1,048,576 characters. | @@ -420,7 +420,7 @@ DELETE /groups/:id/epics/:epic_iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | ```shell @@ -439,7 +439,7 @@ POST /groups/:id/epics/:epic_iid/todo | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer | yes | The internal ID of a group's epic | ```shell diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index 306383c2de7..fbfd2a69ef7 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -21,7 +21,7 @@ GET /projects/:id/error_tracking/settings | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/error_tracking/settings" @@ -48,7 +48,7 @@ PATCH /projects/:id/error_tracking/settings | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `active` | boolean | yes | Pass `true` to enable the already configured error tracking settings or `false` to disable it. | ```shell diff --git a/doc/api/events.md b/doc/api/events.md index 49d99cc43fe..7088eb65bd4 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -10,20 +10,52 @@ info: To determine the technical writer assigned to the Stage/Group associated w ### Action Types -Available action types for the `action` parameter are: +Available types for the `action` parameter, and the resources that might be affected: - `approved` -- `created` -- `updated` + - Merge request - `closed` -- `reopened` -- `pushed` -- `commented` -- `merged` -- `joined` -- `left` + - Epic + - Issue + - Merge request + - Milestone +- `commented` on any `Noteable` record. + - Alert + - Commit + - Design + - Issue + - Merge request + - Snippet +- `created` + - Design + - Epic + - Issue + - Merge request + - Milestone + - Project + - Wiki page - `destroyed` + - Design + - Milestone + - Wiki page - `expired` + - Project membership +- `joined` + - Project membership +- `left` + - Project membership +- `merged` + - Merge request +- `pushed` commits to (or deleted commits from) a repository, individually or in bulk. + - Project +- `reopened` + - Epic + - Issue + - Merge request + - Milestone +- `updated` + - Design + - Wiki page Note that these options are in lower case. @@ -283,7 +315,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `action` | string | no | Include only events of a particular [action type](#action-types) | | `target_type` | string | no | Include only events of a particular [target type](#target-types) | | `before` | date | no | Include only events created before a particular date. [View how to format dates](#date-formatting). | diff --git a/doc/api/feature_flag_user_lists.md b/doc/api/feature_flag_user_lists.md index af8b3fcc71e..4306167603d 100644 --- a/doc/api/feature_flag_user_lists.md +++ b/doc/api/feature_flag_user_lists.md @@ -15,7 +15,7 @@ Users with Developer or higher [permissions](../user/permissions.md) can access NOTE: `GET` requests return twenty results at a time because the API results -are [paginated](README.md#pagination). You can change this value. +are [paginated](index.md#pagination). You can change this value. ## List all feature flag user lists for a project @@ -27,7 +27,7 @@ GET /projects/:id/feature_flags_user_lists | Attribute | Type | Required | Description | | --------- | -------------- | -------- | -------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `search` | string | no | Return user lists matching the search criteria. | ```shell @@ -69,7 +69,7 @@ POST /projects/:id/feature_flags_user_lists | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `name` | string | yes | The name of the feature flag. | | `user_xids` | string | yes | A comma separated list of user IDs. | @@ -109,7 +109,7 @@ GET /projects/:id/feature_flags_user_lists/:iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `iid` | integer/string | yes | The internal ID of the project's feature flag user list. | ```shell @@ -140,7 +140,7 @@ PUT /projects/:id/feature_flags_user_lists/:iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `iid` | integer/string | yes | The internal ID of the project's feature flag user list. | | `name` | string | no | The name of the feature flag. | | `user_xids` | string | no | A comma separated list of user IDs. | @@ -181,7 +181,7 @@ DELETE /projects/:id/feature_flags_user_lists/:iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `iid` | integer/string | yes | The internal ID of the project's feature flag user list | ```shell diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md index 50cb9b1141e..b40a3994dbf 100644 --- a/doc/api/feature_flags.md +++ b/doc/api/feature_flags.md @@ -16,7 +16,7 @@ Users with Developer or higher [permissions](../user/permissions.md) can access ## Feature Flags pagination By default, `GET` requests return 20 results at a time because the API results -are [paginated](README.md#pagination). +are [paginated](index.md#pagination). ## List feature flags for a project @@ -28,7 +28,7 @@ GET /projects/:id/feature_flags | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `scope` | string | no | The condition of feature flags, one of: `enabled`, `disabled`. | ```shell @@ -98,7 +98,7 @@ GET /projects/:id/feature_flags/:feature_flag_name | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `feature_flag_name` | string | yes | The name of the feature flag. | ```shell @@ -142,13 +142,13 @@ POST /projects/:id/feature_flags | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `name` | string | yes | The name of the feature flag. | | `version` | string | yes | The version of the feature flag. Must be `new_version_flag`. Omit or set to `legacy_flag` to create a [Legacy Feature Flag](feature_flags_legacy.md). | | `description` | string | no | The description of the feature flag. | | `active` | boolean | no | The active state of the flag. Defaults to true. [Supported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38350) in GitLab 13.3 and later. | | `strategies` | JSON | no | The feature flag [strategies](../operations/feature_flags.md#feature-flag-strategies). | -| `strategies:name` | JSON | no | The strategy name. Can be `default`, `gradualRolloutUserId`, `userWithId`, or `gitlabUserList`. In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/36380) and later, can be [`flexibleRollout`](https://docs.getunleash.io/docs/activation_strategy#flexiblerollout). | +| `strategies:name` | JSON | no | The strategy name. Can be `default`, `gradualRolloutUserId`, `userWithId`, or `gitlabUserList`. In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/36380) and later, can be [`flexibleRollout`](https://docs.getunleash.io/activation_strategy/#flexiblerollout). | | `strategies:parameters` | JSON | no | The strategy parameters. | | `strategies:scopes` | JSON | no | The scopes for the strategy. | | `strategies:scopes:environment_scope` | string | no | The environment spec for the scope. | @@ -203,7 +203,7 @@ PUT /projects/:id/feature_flags/:feature_flag_name | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `feature_flag_name` | string | yes | The current name of the feature flag. | | `description` | string | no | The description of the feature flag. | | `active` | boolean | no | The active state of the flag. [Supported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38350) in GitLab 13.3 and later. | @@ -278,7 +278,7 @@ DELETE /projects/:id/feature_flags/:feature_flag_name | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `feature_flag_name` | string | yes | The name of the feature flag. | ```shell diff --git a/doc/api/freeze_periods.md b/doc/api/freeze_periods.md index 50f1fe9f12b..454d2dfb1c5 100644 --- a/doc/api/freeze_periods.md +++ b/doc/api/freeze_periods.md @@ -26,7 +26,7 @@ GET /projects/:id/freeze_periods | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | Example request: @@ -59,7 +59,7 @@ GET /projects/:id/freeze_periods/:freeze_period_id | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `freeze_period_id` | string | yes | The database ID of the Freeze Period. | Example request: @@ -91,7 +91,7 @@ POST /projects/:id/freeze_periods | Attribute | Type | Required | Description | | -------------------| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `freeze_start` | string | yes | Start of the Freeze Period in [cron](https://crontab.guru/) format. | | `freeze_end` | string | yes | End of the Freeze Period in [cron](https://crontab.guru/) format. | | `cron_timezone` | string | no | The timezone for the cron fields, defaults to UTC if not provided. | @@ -127,7 +127,7 @@ PUT /projects/:id/freeze_periods/:tag_name | Attribute | Type | Required | Description | | ------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `freeze_period_id` | integer or string | yes | The database ID of the Freeze Period. | | `freeze_start` | string | no | Start of the Freeze Period in [cron](https://crontab.guru/) format. | | `freeze_end` | string | no | End of the Freeze Period in [cron](https://crontab.guru/) format. | @@ -164,7 +164,7 @@ DELETE /projects/:id/freeze_periods/:freeze_period_id | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `freeze_period_id` | string | yes | The database ID of the Freeze Period. | Example request: diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index 7926aeeeed7..42cf40d62b8 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -741,7 +741,7 @@ GET /geo_nodes/current/failures | `type` | string | no | Type of failed objects (`repository`/`wiki`) | | `failure_type` | string | no | Type of failures (`sync`/`checksum_mismatch`/`verification`) | -This endpoint uses [Pagination](README.md#pagination). +This endpoint uses [Pagination](index.md#pagination). ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/geo_nodes/current/failures" diff --git a/doc/api/graphql/custom_emoji.md b/doc/api/graphql/custom_emoji.md new file mode 100644 index 00000000000..a4d0acda8e7 --- /dev/null +++ b/doc/api/graphql/custom_emoji.md @@ -0,0 +1,111 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Use custom emojis with GraphQL **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37911) in GitLab 13.6 +> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-custom-emoji-api). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../user/feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +To use custom emoji in comments and descriptions, you can add them to a group using the GraphQL API. + +Parameters: + +| Attribute | Type | Required | Description | +| :----------- | :------------- | :--------------------- | :------------------------------------------------------------------------ | +| `group_path` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) | +| `name` | string | **{check-circle}** Yes | Name of the custom emoji. | +| `file` | string | **{check-circle}** Yes | URL of the custom emoji image. | + +## Create a custom emoji + +```graphql +mutation CreateCustomEmoji($groupPath: ID!) { + createCustomEmoji(input: {groupPath: $groupPath, name: "party-parrot", file: "https://cultofthepartyparrot.com/parrots/hd/parrot.gif", external: true}) { + clientMutationId + name + errors + } +} +``` + +After adding custom emoji to the group, members can use it in the same way as other emoji in the comments. + +## Get custom emoji for a group + +```graphql +query GetCustomEmoji($groupPath: ID!) { + group(fullPath: $groupPath) { + id + customEmoji { + nodes { + name + } + } + } +} +``` + +## Set up the GraphiQL explorer + +This procedure presents a substantive example that you can copy and paste into GraphiQL +explorer. GraphiQL explorer is available for: + +- GitLab.com users at [https://gitlab.com/-/graphql-explorer](https://gitlab.com/-/graphql-explorer). +- Self-managed users at `https://gitlab.example.com/-/graphql-explorer`. + +1. Copy the following code excerpt: + + ```graphql + query GetCustomEmoji { + group(fullPath: "gitlab-org") { + id + customEmoji { + nodes { + name, + url + } + } + } + } + ``` + +1. Open the [GraphiQL explorer tool](https://gitlab.com/-/graphql-explorer). +1. Paste the `query` listed above into the left window of your GraphiQL explorer tool. +1. Click Play to get the result shown here: + + + +For more information on: + +- GraphQL specific entities, such as Fragments and Interfaces, see the official + [GraphQL documentation](https://graphql.org/learn/). +- Individual attributes, see the [GraphQL API Resources](reference/index.md). + +## Enable or disable custom emoji API **(FREE SELF)** + +Custom emoji is under development and but ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:custom_emoji) +``` + +To disable it: + +```ruby +Feature.disable(:custom_emoji) +``` diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index 85b36346167..5b482d15c51 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w This guide demonstrates basic usage of the GitLab GraphQL API. -Read the [GraphQL API style guide](../../development/api_graphql_styleguide.md) +Read the [GraphQL API style guide](../../development/api_graphql_styleguide.md) for implementation details aimed at developers who wish to work on developing the API itself. @@ -141,7 +141,7 @@ More about queries: Authorization uses the same engine as the GitLab application (and GitLab.com). If you've signed in to GitLab and use GraphiQL, all queries are performed as you, the signed in user. For more information, read the -[GitLab API documentation](../README.md#authentication). +[GitLab API documentation](../index.md#authentication). ### Mutations @@ -298,6 +298,24 @@ query IssueTypes { More about introspection: [GraphQL documentation](https://graphql.org/learn/introspection/) +### Query complexity + +The calculated [complexity score and limit](index.md#max-query-complexity) for a query can be revealed to clients by +querying for `queryComplexity`. + +```graphql +query { + queryComplexity { + score + limit + } + + project(fullPath: "gitlab-org/graphql-sandbox") { + name + } +} +``` + ## Sorting Some of the GitLab GraphQL endpoints allow you to specify how to sort a diff --git a/doc/api/graphql/img/custom_emoji_query_example.png b/doc/api/graphql/img/custom_emoji_query_example.png Binary files differnew file mode 100644 index 00000000000..2caccd6cd10 --- /dev/null +++ b/doc/api/graphql/img/custom_emoji_query_example.png diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 073f5faf57c..b7a82dba7e9 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -76,6 +76,8 @@ These changes include the removal or renaming of fields, arguments or other part In these situations, GitLab follows a [Deprecation and removal process](#deprecation-and-removal-process) where the deprecated part of the schema is supported for a period of time before being removed. +There are some changes which are explicitly [not considered breaking](../../development/contributing/#breaking-changes). + Clients should familiarize themselves with the process to avoid breaking changes affecting their integrations. WARNING: @@ -99,7 +101,6 @@ The process is as follows: [GraphQL API Reference](reference/index.md) and in introspection queries. 1. Removals are announced at least one release prior in the [Deprecations](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations) section of the release post (at or prior to `X.11` and `X.5` releases). - release post (at or prior to `X.11` and `X.5` releases). 1. Items meeting criteria are removed in `X.0` or `X.6` and added to: - The [Removals](https://about.gitlab.com/handbook/marketing/blog/release-posts/#removals) section of the Release Post. @@ -165,7 +166,7 @@ The complexity of a single query is limited to a maximum of: - `200` for unauthenticated requests. - `250` for authenticated requests. -There is no way to discover the complexity of a query except by exceeding the limit. +The complexity score of a query and limit for the request [can be queried for](getting_started.md#query-complexity). If a query exceeds the complexity limit an error message response will be returned. diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index ffdf0ea5fd3..db93accc86a 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -52,6 +52,7 @@ Returns [`CiConfig`](#ciconfig). | <a id="queryciconfigcontent"></a>`content` | [`String!`](#string) | Contents of `.gitlab-ci.yml`. | | <a id="queryciconfigdryrun"></a>`dryRun` | [`Boolean`](#boolean) | Run pipeline creation simulation, or only do static check. | | <a id="queryciconfigprojectpath"></a>`projectPath` | [`ID!`](#id) | The project of the CI config. | +| <a id="queryciconfigsha"></a>`sha` | [`String`](#string) | Sha for the pipeline. | ### `Query.containerRepository` @@ -285,9 +286,15 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="queryprojectssort"></a>`sort` | [`String`](#string) | Sort order of results. | | <a id="queryprojectstopics"></a>`topics` | [`[String!]`](#string) | Filters projects by topics. | +### `Query.queryComplexity` + +Information about the complexity of the GraphQL query. + +Returns [`QueryComplexity`](#querycomplexity). + ### `Query.runner` -Find a runner. Available only when feature flag `runner_graphql_query` is enabled. +Find a runner. Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. Returns [`CiRunner`](#cirunner). @@ -324,7 +331,7 @@ Returns [`RunnerSetup`](#runnersetup). ### `Query.runners` -Find runners visible to the current user. Available only when feature flag `runner_graphql_query` is enabled. +Find runners visible to the current user. Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. Returns [`CiRunnerConnection`](#cirunnerconnection). @@ -779,6 +786,46 @@ Input type: `CiCdSettingsUpdateInput` | <a id="mutationcicdsettingsupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcicdsettingsupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.ciJobTokenScopeAddProject` + +Input type: `CiJobTokenScopeAddProjectInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationcijobtokenscopeaddprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcijobtokenscopeaddprojectprojectpath"></a>`projectPath` | [`ID!`](#id) | The project that the CI job token scope belongs to. | +| <a id="mutationcijobtokenscopeaddprojecttargetprojectpath"></a>`targetProjectPath` | [`ID!`](#id) | The project to be added to the CI job token scope. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationcijobtokenscopeaddprojectcijobtokenscope"></a>`ciJobTokenScope` | [`CiJobTokenScopeType`](#cijobtokenscopetype) | The CI job token's scope of access. | +| <a id="mutationcijobtokenscopeaddprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcijobtokenscopeaddprojecterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + +### `Mutation.ciJobTokenScopeRemoveProject` + +Input type: `CiJobTokenScopeRemoveProjectInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationcijobtokenscoperemoveprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcijobtokenscoperemoveprojectprojectpath"></a>`projectPath` | [`ID!`](#id) | The project that the CI job token scope belongs to. | +| <a id="mutationcijobtokenscoperemoveprojecttargetprojectpath"></a>`targetProjectPath` | [`ID!`](#id) | The project to be removed from the CI job token scope. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationcijobtokenscoperemoveprojectcijobtokenscope"></a>`ciJobTokenScope` | [`CiJobTokenScopeType`](#cijobtokenscopetype) | The CI job token's scope of access. | +| <a id="mutationcijobtokenscoperemoveprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcijobtokenscoperemoveprojecterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.clusterAgentDelete` Input type: `ClusterAgentDeleteInput` @@ -862,6 +909,30 @@ Input type: `CommitCreateInput` | <a id="mutationcommitcreatecontent"></a>`content` | [`[String!]`](#string) | Contents of the commit. | | <a id="mutationcommitcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.configureDependencyScanning` + +Configure Dependency Scanning for a project by enabling Dependency Scanning in a new or modified +`.gitlab-ci.yml` file in a new branch. The new branch and a URL to +create a Merge Request are a part of the response. + +Input type: `ConfigureDependencyScanningInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationconfiguredependencyscanningclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationconfiguredependencyscanningprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationconfiguredependencyscanningbranch"></a>`branch` | [`String`](#string) | Branch that has the new/modified `.gitlab-ci.yml` file. | +| <a id="mutationconfiguredependencyscanningclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationconfiguredependencyscanningerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationconfiguredependencyscanningsuccesspath"></a>`successPath` | [`String`](#string) | Redirect path to use when the response is successful. | + ### `Mutation.configureSast` Configure SAST for a project by enabling SAST in a new or modified @@ -1050,7 +1121,7 @@ Input type: `CreateComplianceFrameworkInput` ### `Mutation.createCustomEmoji` -Available only when feature flag `custom_emoji` is enabled. +Available only when feature flag `custom_emoji` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. Input type: `CreateCustomEmojiInput` @@ -1834,6 +1905,24 @@ Input type: `DestroyNoteInput` | <a id="mutationdestroynoteerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationdestroynotenote"></a>`note` | [`Note`](#note) | The note after mutation. | +### `Mutation.destroyPackage` + +Input type: `DestroyPackageInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationdestroypackageclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdestroypackageid"></a>`id` | [`PackagesPackageID!`](#packagespackageid) | ID of the Package. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationdestroypackageclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdestroypackageerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.destroySnippet` Input type: `DestroySnippetInput` @@ -2554,7 +2643,7 @@ Input type: `IssueSetWeightInput` | <a id="mutationissuesetweightclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationissuesetweightiid"></a>`iid` | [`String!`](#string) | The IID of the issue to mutate. | | <a id="mutationissuesetweightprojectpath"></a>`projectPath` | [`ID!`](#id) | The project the issue to mutate is in. | -| <a id="mutationissuesetweightweight"></a>`weight` | [`Int!`](#int) | The desired weight for the issue. | +| <a id="mutationissuesetweightweight"></a>`weight` | [`Int`](#int) | The desired weight for the issue. If set to null, weight is removed. | #### Fields @@ -3298,7 +3387,7 @@ Input type: `PrometheusIntegrationResetTokenInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationprometheusintegrationresettokenclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationprometheusintegrationresettokenid"></a>`id` | [`PrometheusServiceID!`](#prometheusserviceid) | The ID of the integration to mutate. | +| <a id="mutationprometheusintegrationresettokenid"></a>`id` | [`IntegrationsPrometheusID!`](#integrationsprometheusid) | The ID of the integration to mutate. | #### Fields @@ -3319,7 +3408,7 @@ Input type: `PrometheusIntegrationUpdateInput` | <a id="mutationprometheusintegrationupdateactive"></a>`active` | [`Boolean`](#boolean) | Whether the integration is receiving alerts. | | <a id="mutationprometheusintegrationupdateapiurl"></a>`apiUrl` | [`String`](#string) | Endpoint at which Prometheus can be queried. | | <a id="mutationprometheusintegrationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationprometheusintegrationupdateid"></a>`id` | [`PrometheusServiceID!`](#prometheusserviceid) | The ID of the integration to mutate. | +| <a id="mutationprometheusintegrationupdateid"></a>`id` | [`IntegrationsPrometheusID!`](#integrationsprometheusid) | The ID of the integration to mutate. | #### Fields @@ -3529,7 +3618,7 @@ Input type: `RepositionImageDiffNoteInput` ### `Mutation.runnerDelete` -Available only when feature flag `runner_graphql_query` is enabled. +Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. Input type: `RunnerDeleteInput` @@ -3549,7 +3638,7 @@ Input type: `RunnerDeleteInput` ### `Mutation.runnerUpdate` -Available only when feature flag `runner_graphql_query` is enabled. +Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. Input type: `RunnerUpdateInput` @@ -3564,6 +3653,8 @@ Input type: `RunnerUpdateInput` | <a id="mutationrunnerupdateid"></a>`id` | [`CiRunnerID!`](#cirunnerid) | ID of the runner to update. | | <a id="mutationrunnerupdatelocked"></a>`locked` | [`Boolean`](#boolean) | Indicates the runner is locked. | | <a id="mutationrunnerupdatemaximumtimeout"></a>`maximumTimeout` | [`Int`](#int) | Maximum timeout (in seconds) for jobs processed by the runner. | +| <a id="mutationrunnerupdateprivateprojectsminutescostfactor"></a>`privateProjectsMinutesCostFactor` | [`Float`](#float) | Private projects' "minutes cost factor" associated with the runner (GitLab.com only). | +| <a id="mutationrunnerupdatepublicprojectsminutescostfactor"></a>`publicProjectsMinutesCostFactor` | [`Float`](#float) | Public projects' "minutes cost factor" associated with the runner (GitLab.com only). | | <a id="mutationrunnerupdaterununtagged"></a>`runUntagged` | [`Boolean`](#boolean) | Indicates the runner is able to run untagged jobs. | | <a id="mutationrunnerupdatetaglist"></a>`tagList` | [`[String!]`](#string) | Tags associated with the runner. | @@ -3577,7 +3668,7 @@ Input type: `RunnerUpdateInput` ### `Mutation.runnersRegistrationTokenReset` -Available only when feature flag `runner_graphql_query` is enabled. +Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. Input type: `RunnersRegistrationTokenResetInput` @@ -3597,6 +3688,65 @@ Input type: `RunnersRegistrationTokenResetInput` | <a id="mutationrunnersregistrationtokenreseterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationrunnersregistrationtokenresettoken"></a>`token` | [`String`](#string) | The runner token after mutation. | +### `Mutation.scanExecutionPolicyCommit` + +Input type: `ScanExecutionPolicyCommitInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationscanexecutionpolicycommitclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationscanexecutionpolicycommitoperationmode"></a>`operationMode` | [`MutationOperationMode!`](#mutationoperationmode) | Changes the operation mode. | +| <a id="mutationscanexecutionpolicycommitpolicyyaml"></a>`policyYaml` | [`String!`](#string) | YAML snippet of the policy. | +| <a id="mutationscanexecutionpolicycommitprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationscanexecutionpolicycommitbranch"></a>`branch` | [`String`](#string) | Name of the branch to which the policy changes are committed. | +| <a id="mutationscanexecutionpolicycommitclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationscanexecutionpolicycommiterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + +### `Mutation.securityPolicyProjectAssign` + +Input type: `SecurityPolicyProjectAssignInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationsecuritypolicyprojectassignclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationsecuritypolicyprojectassignprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project. | +| <a id="mutationsecuritypolicyprojectassignsecuritypolicyprojectid"></a>`securityPolicyProjectId` | [`ProjectID!`](#projectid) | ID of the security policy project. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationsecuritypolicyprojectassignclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationsecuritypolicyprojectassignerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + +### `Mutation.securityPolicyProjectCreate` + +Input type: `SecurityPolicyProjectCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationsecuritypolicyprojectcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationsecuritypolicyprojectcreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationsecuritypolicyprojectcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationsecuritypolicyprojectcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationsecuritypolicyprojectcreateproject"></a>`project` | [`Project`](#project) | Security Policy Project that was created. | + ### `Mutation.terraformStateDelete` Input type: `TerraformStateDeleteInput` @@ -7345,7 +7495,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="boardepicancestorsenddate"></a>`endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | <a id="boardepicancestorsiid"></a>`iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | <a id="boardepicancestorsiidstartswith"></a>`iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | -| <a id="boardepicancestorsiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., [1, 2]. | +| <a id="boardepicancestorsiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., `[1, 2]`. | +| <a id="boardepicancestorsin"></a>`in` | [`[IssuableSearchableField!]`](#issuablesearchablefield) | Specify the fields to perform the search in. Defaults to `[TITLE, DESCRIPTION]`. Requires the `search` argument. | | <a id="boardepicancestorsincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include epics from ancestor groups. | | <a id="boardepicancestorsincludedescendantgroups"></a>`includeDescendantGroups` | [`Boolean`](#boolean) | Include epics from descendant groups. | | <a id="boardepicancestorslabelname"></a>`labelName` | [`[String!]`](#string) | Filter epics by labels. | @@ -7377,7 +7528,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="boardepicchildrenenddate"></a>`endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | <a id="boardepicchildreniid"></a>`iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | <a id="boardepicchildreniidstartswith"></a>`iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | -| <a id="boardepicchildreniids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., [1, 2]. | +| <a id="boardepicchildreniids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., `[1, 2]`. | +| <a id="boardepicchildrenin"></a>`in` | [`[IssuableSearchableField!]`](#issuablesearchablefield) | Specify the fields to perform the search in. Defaults to `[TITLE, DESCRIPTION]`. Requires the `search` argument. | | <a id="boardepicchildrenincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include epics from ancestor groups. | | <a id="boardepicchildrenincludedescendantgroups"></a>`includeDescendantGroups` | [`Boolean`](#boolean) | Include epics from descendant groups. | | <a id="boardepicchildrenlabelname"></a>`labelName` | [`[String!]`](#string) | Filter epics by labels. | @@ -7506,6 +7658,7 @@ Represents the total number of issues and their weights for a particular day. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="cibuildneedid"></a>`id` | [`ID!`](#id) | ID of the job we need to complete. | | <a id="cibuildneedname"></a>`name` | [`String`](#string) | Name of the job we need to complete. | ### `CiConfig` @@ -7581,6 +7734,7 @@ Represents the total number of issues and their weights for a particular day. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="cigroupdetailedstatus"></a>`detailedStatus` | [`DetailedStatus`](#detailedstatus) | Detailed status of the group. | +| <a id="cigroupid"></a>`id` | [`String!`](#string) | ID for a group. | | <a id="cigroupjobs"></a>`jobs` | [`CiJobConnection`](#cijobconnection) | Jobs in group. (see [Connections](#connections)) | | <a id="cigroupname"></a>`name` | [`String`](#string) | Name of the job group. | | <a id="cigroupsize"></a>`size` | [`Int`](#int) | Size of the group. | @@ -7614,7 +7768,7 @@ Represents the total number of issues and their weights for a particular day. | <a id="cijobrefpath"></a>`refPath` | [`String`](#string) | Path to the ref. | | <a id="cijobretryable"></a>`retryable` | [`Boolean!`](#boolean) | Indicates the job can be retried. | | <a id="cijobscheduledat"></a>`scheduledAt` | [`Time`](#time) | Schedule for the build. | -| <a id="cijobschedulingtype"></a>`schedulingType` | [`String`](#string) | Type of pipeline scheduling. Value is `dag` if the pipeline uses the `needs` keyword, and `stage` otherwise. | +| <a id="cijobschedulingtype"></a>`schedulingType` | [`String`](#string) | Type of job scheduling. Value is `dag` if the job uses the `needs` keyword, and `stage` otherwise. | | <a id="cijobshortsha"></a>`shortSha` | [`String!`](#string) | Short SHA1 ID of the commit. | | <a id="cijobstage"></a>`stage` | [`CiStage`](#cistage) | Stage of the job. | | <a id="cijobstartedat"></a>`startedAt` | [`Time`](#time) | When the job was started. | @@ -7633,6 +7787,14 @@ Represents the total number of issues and their weights for a particular day. | <a id="cijobartifactdownloadpath"></a>`downloadPath` | [`String`](#string) | URL for downloading the artifact's file. | | <a id="cijobartifactfiletype"></a>`fileType` | [`JobArtifactFileType`](#jobartifactfiletype) | File type of the artifact. | +### `CiJobTokenScopeType` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="cijobtokenscopetypeprojects"></a>`projects` | [`ProjectConnection!`](#projectconnection) | Allow list of projects that can be accessed by CI Job tokens created by this project. (see [Connections](#connections)) | + ### `CiRunner` #### Fields @@ -7644,18 +7806,20 @@ Represents the total number of issues and their weights for a particular day. | <a id="cirunnercontactedat"></a>`contactedAt` | [`Time`](#time) | Last contact from the runner. | | <a id="cirunnerdescription"></a>`description` | [`String`](#string) | Description of the runner. | | <a id="cirunnerid"></a>`id` | [`CiRunnerID!`](#cirunnerid) | ID of the runner. | -| <a id="cirunneripaddress"></a>`ipAddress` | [`String!`](#string) | IP address of the runner. | +| <a id="cirunneripaddress"></a>`ipAddress` | [`String`](#string) | IP address of the runner. | +| <a id="cirunnerjobcount"></a>`jobCount` | [`Int`](#int) | Number of jobs processed by the runner (limited to 1000, plus one to indicate that more items exist). | | <a id="cirunnerlocked"></a>`locked` | [`Boolean`](#boolean) | Indicates the runner is locked. | | <a id="cirunnermaximumtimeout"></a>`maximumTimeout` | [`Int`](#int) | Maximum timeout (in seconds) for jobs processed by the runner. | | <a id="cirunnerprivateprojectsminutescostfactor"></a>`privateProjectsMinutesCostFactor` | [`Float`](#float) | Private projects' "minutes cost factor" associated with the runner (GitLab.com only). | +| <a id="cirunnerprojectcount"></a>`projectCount` | [`Int`](#int) | Number of projects that the runner is associated with. | | <a id="cirunnerpublicprojectsminutescostfactor"></a>`publicProjectsMinutesCostFactor` | [`Float`](#float) | Public projects' "minutes cost factor" associated with the runner (GitLab.com only). | -| <a id="cirunnerrevision"></a>`revision` | [`String!`](#string) | Revision of the runner. | +| <a id="cirunnerrevision"></a>`revision` | [`String`](#string) | Revision of the runner. | | <a id="cirunnerrununtagged"></a>`runUntagged` | [`Boolean!`](#boolean) | Indicates the runner is able to run untagged jobs. | | <a id="cirunnerrunnertype"></a>`runnerType` | [`CiRunnerType!`](#cirunnertype) | Type of the runner. | | <a id="cirunnershortsha"></a>`shortSha` | [`String`](#string) | First eight characters of the runner's token used to authenticate new job requests. Used as the runner's unique ID. | | <a id="cirunnerstatus"></a>`status` | [`CiRunnerStatus!`](#cirunnerstatus) | Status of the runner. | | <a id="cirunnertaglist"></a>`tagList` | [`[String!]`](#string) | Tags associated with the runner. | -| <a id="cirunnerversion"></a>`version` | [`String!`](#string) | Version of the runner. | +| <a id="cirunnerversion"></a>`version` | [`String`](#string) | Version of the runner. | ### `CiStage` @@ -7665,8 +7829,10 @@ Represents the total number of issues and their weights for a particular day. | ---- | ---- | ----------- | | <a id="cistagedetailedstatus"></a>`detailedStatus` | [`DetailedStatus`](#detailedstatus) | Detailed status of the stage. | | <a id="cistagegroups"></a>`groups` | [`CiGroupConnection`](#cigroupconnection) | Group of jobs for the stage. (see [Connections](#connections)) | +| <a id="cistageid"></a>`id` | [`ID!`](#id) | ID of the stage. | | <a id="cistagejobs"></a>`jobs` | [`CiJobConnection`](#cijobconnection) | Jobs for the stage. (see [Connections](#connections)) | | <a id="cistagename"></a>`name` | [`String`](#string) | Name of the stage. | +| <a id="cistagestatus"></a>`status` | [`String`](#string) | Status of the pipeline stage. | ### `CiTemplate` @@ -8328,6 +8494,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="detailedstatusgroup"></a>`group` | [`String`](#string) | Group of the status. | | <a id="detailedstatushasdetails"></a>`hasDetails` | [`Boolean`](#boolean) | Indicates if the status has further details. | | <a id="detailedstatusicon"></a>`icon` | [`String`](#string) | Icon of the status. | +| <a id="detailedstatusid"></a>`id` | [`String!`](#string) | ID for a detailed status. | | <a id="detailedstatuslabel"></a>`label` | [`String`](#string) | Label of the status. | | <a id="detailedstatustext"></a>`text` | [`String`](#string) | Text of the status. | | <a id="detailedstatustooltip"></a>`tooltip` | [`String`](#string) | Tooltip associated with the status. | @@ -8373,6 +8540,9 @@ Snapshot. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="devopsadoptionsnapshotcodeownersusedcount"></a>`codeOwnersUsedCount` | [`Int`](#int) | Total number of projects with existing CODEOWNERS file. | +| <a id="devopsadoptionsnapshotcoveragefuzzingenabledcount"></a>`coverageFuzzingEnabledCount` | [`Int`](#int) | Total number of projects with enabled coverage fuzzing. | +| <a id="devopsadoptionsnapshotdastenabledcount"></a>`dastEnabledCount` | [`Int`](#int) | Total number of projects with enabled DAST. | +| <a id="devopsadoptionsnapshotdependencyscanningenabledcount"></a>`dependencyScanningEnabledCount` | [`Int`](#int) | Total number of projects with enabled dependency scanning. | | <a id="devopsadoptionsnapshotdeploysucceeded"></a>`deploySucceeded` | [`Boolean!`](#boolean) | At least one deployment succeeded. | | <a id="devopsadoptionsnapshotendtime"></a>`endTime` | [`Time!`](#time) | The end time for the snapshot where the data points were collected. | | <a id="devopsadoptionsnapshotissueopened"></a>`issueOpened` | [`Boolean!`](#boolean) | At least one issue was opened. | @@ -8381,9 +8551,11 @@ Snapshot. | <a id="devopsadoptionsnapshotpipelinesucceeded"></a>`pipelineSucceeded` | [`Boolean!`](#boolean) | At least one pipeline succeeded. | | <a id="devopsadoptionsnapshotrecordedat"></a>`recordedAt` | [`Time!`](#time) | The time the snapshot was recorded. | | <a id="devopsadoptionsnapshotrunnerconfigured"></a>`runnerConfigured` | [`Boolean!`](#boolean) | At least one runner was used. | -| <a id="devopsadoptionsnapshotsecurityscansucceeded"></a>`securityScanSucceeded` | [`Boolean!`](#boolean) | At least one security scan succeeded. | +| <a id="devopsadoptionsnapshotsastenabledcount"></a>`sastEnabledCount` | [`Int`](#int) | Total number of projects with enabled SAST. | +| <a id="devopsadoptionsnapshotsecurityscansucceeded"></a>`securityScanSucceeded` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 14.1. Substituted with specific security metrics. Always false. | | <a id="devopsadoptionsnapshotstarttime"></a>`startTime` | [`Time!`](#time) | The start time for the snapshot where the data points were collected. | | <a id="devopsadoptionsnapshottotalprojectscount"></a>`totalProjectsCount` | [`Int`](#int) | Total number of projects. | +| <a id="devopsadoptionsnapshotvulnerabilitymanagementusedcount"></a>`vulnerabilityManagementUsedCount` | [`Int`](#int) | Total number of projects with vulnerability management used at least once. | ### `DiffPosition` @@ -8446,6 +8618,7 @@ Aggregated summary of changes. | ---- | ---- | ----------- | | <a id="discussioncreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of the discussion's creation. | | <a id="discussionid"></a>`id` | [`DiscussionID!`](#discussionid) | ID of this discussion. | +| <a id="discussionnoteable"></a>`noteable` | [`NoteableType`](#noteabletype) | Object which the discussion belongs to. | | <a id="discussionnotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes in the discussion. (see [Connections](#connections)) | | <a id="discussionreplyid"></a>`replyId` | [`DiscussionID!`](#discussionid) | ID used to reply to this discussion. | | <a id="discussionresolvable"></a>`resolvable` | [`Boolean!`](#boolean) | Indicates if the object can be resolved. | @@ -8453,6 +8626,37 @@ Aggregated summary of changes. | <a id="discussionresolvedat"></a>`resolvedAt` | [`Time`](#time) | Timestamp of when the object was resolved. | | <a id="discussionresolvedby"></a>`resolvedBy` | [`UserCore`](#usercore) | User who resolved the object. | +### `Dora` + +All information related to DORA metrics. + +#### Fields with arguments + +##### `Dora.metrics` + +DORA metrics for the current group or project. + +Returns [`[DoraMetric!]`](#dorametric). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dorametricsenddate"></a>`endDate` | [`Date`](#date) | Date range to end at. Default is the current date. | +| <a id="dorametricsenvironmenttier"></a>`environmentTier` | [`DeploymentTier`](#deploymenttier) | The deployment tier of the environments to return. Defaults to `PRODUCTION`. | +| <a id="dorametricsinterval"></a>`interval` | [`DoraMetricBucketingInterval`](#dorametricbucketinginterval) | How the metric should be aggregrated. Defaults to `DAILY`. In the case of `ALL`, the `date` field in the response will be `null`. | +| <a id="dorametricsmetric"></a>`metric` | [`DoraMetricType!`](#dorametrictype) | The type of metric to return. | +| <a id="dorametricsstartdate"></a>`startDate` | [`Date`](#date) | Date range to start from. Default is 3 months ago. | + +### `DoraMetric` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dorametricdate"></a>`date` | [`String`](#string) | Date of the data point. | +| <a id="dorametricvalue"></a>`value` | [`Int`](#int) | Value of the data point. | + ### `Environment` Describes where code is deployed for a project. @@ -8556,7 +8760,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="epicancestorsenddate"></a>`endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | <a id="epicancestorsiid"></a>`iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | <a id="epicancestorsiidstartswith"></a>`iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | -| <a id="epicancestorsiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., [1, 2]. | +| <a id="epicancestorsiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., `[1, 2]`. | +| <a id="epicancestorsin"></a>`in` | [`[IssuableSearchableField!]`](#issuablesearchablefield) | Specify the fields to perform the search in. Defaults to `[TITLE, DESCRIPTION]`. Requires the `search` argument. | | <a id="epicancestorsincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include epics from ancestor groups. | | <a id="epicancestorsincludedescendantgroups"></a>`includeDescendantGroups` | [`Boolean`](#boolean) | Include epics from descendant groups. | | <a id="epicancestorslabelname"></a>`labelName` | [`[String!]`](#string) | Filter epics by labels. | @@ -8588,7 +8793,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="epicchildrenenddate"></a>`endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | <a id="epicchildreniid"></a>`iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | <a id="epicchildreniidstartswith"></a>`iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | -| <a id="epicchildreniids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., [1, 2]. | +| <a id="epicchildreniids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., `[1, 2]`. | +| <a id="epicchildrenin"></a>`in` | [`[IssuableSearchableField!]`](#issuablesearchablefield) | Specify the fields to perform the search in. Defaults to `[TITLE, DESCRIPTION]`. Requires the `search` argument. | | <a id="epicchildrenincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include epics from ancestor groups. | | <a id="epicchildrenincludedescendantgroups"></a>`includeDescendantGroups` | [`Boolean`](#boolean) | Include epics from descendant groups. | | <a id="epicchildrenlabelname"></a>`labelName` | [`[String!]`](#string) | Filter epics by labels. | @@ -8714,6 +8920,7 @@ Relationship between an epic and an issue. | <a id="epicissueblocked"></a>`blocked` | [`Boolean!`](#boolean) | Indicates the issue is blocked. | | <a id="epicissueblockedbycount"></a>`blockedByCount` | [`Int`](#int) | Count of issues blocking this issue. | | <a id="epicissueblockedbyissues"></a>`blockedByIssues` | [`IssueConnection`](#issueconnection) | Issues blocking this issue. (see [Connections](#connections)) | +| <a id="epicissueblockingcount"></a>`blockingCount` | [`Int!`](#int) | Count of issues this issue is blocking. | | <a id="epicissueclosedat"></a>`closedAt` | [`Time`](#time) | Timestamp of when the issue was closed. | | <a id="epicissueconfidential"></a>`confidential` | [`Boolean!`](#boolean) | Indicates the issue is confidential. | | <a id="epicissuecreatenoteemail"></a>`createNoteEmail` | [`String`](#string) | User specific email address for the issue. | @@ -8741,6 +8948,7 @@ Relationship between an epic and an issue. | <a id="epicissuemovedto"></a>`movedTo` | [`Issue`](#issue) | Updated Issue after it got moved to another project. | | <a id="epicissuenotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | | <a id="epicissueparticipants"></a>`participants` | [`UserCoreConnection`](#usercoreconnection) | List of participants in the issue. (see [Connections](#connections)) | +| <a id="epicissueprojectid"></a>`projectId` | [`Int!`](#int) | ID of the issue project. | | <a id="epicissuerelationpath"></a>`relationPath` | [`String`](#string) | URI path of the epic-issue relation. | | <a id="epicissuerelativeposition"></a>`relativePosition` | [`Int`](#int) | Relative position of the issue (used for positioning in epic tree and issue boards). | | <a id="epicissueseverity"></a>`severity` | [`IssuableSeverity`](#issuableseverity) | Severity level of the incident. | @@ -9063,9 +9271,10 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupbillablememberscount"></a>`billableMembersCount` | [`Int`](#int) | The number of billable users in the group. | | <a id="groupcontainerrepositoriescount"></a>`containerRepositoriesCount` | [`Int!`](#int) | Number of container repositories in the group. | | <a id="groupcontainslockedprojects"></a>`containsLockedProjects` | [`Boolean!`](#boolean) | Includes at least one project where the repository size exceeds the limit. | -| <a id="groupcustomemoji"></a>`customEmoji` | [`CustomEmojiConnection`](#customemojiconnection) | Custom emoji within this namespace. Available only when feature flag `custom_emoji` is enabled. (see [Connections](#connections)) | +| <a id="groupcustomemoji"></a>`customEmoji` | [`CustomEmojiConnection`](#customemojiconnection) | Custom emoji within this namespace. Available only when feature flag `custom_emoji` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. (see [Connections](#connections)) | | <a id="groupdescription"></a>`description` | [`String`](#string) | Description of the namespace. | | <a id="groupdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="groupdora"></a>`dora` | [`Dora`](#dora) | The group's DORA metrics. | | <a id="groupemailsdisabled"></a>`emailsDisabled` | [`Boolean`](#boolean) | Indicates if a group has email notifications disabled. | | <a id="groupepicboards"></a>`epicBoards` | [`EpicBoardConnection`](#epicboardconnection) | Find epic boards. (see [Connections](#connections)) | | <a id="groupepicsenabled"></a>`epicsEnabled` | [`Boolean`](#boolean) | Indicates if Epics are enabled for namespace. | @@ -9191,7 +9400,8 @@ Returns [`Epic`](#epic). | <a id="groupepicenddate"></a>`endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | <a id="groupepiciid"></a>`iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | <a id="groupepiciidstartswith"></a>`iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | -| <a id="groupepiciids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., [1, 2]. | +| <a id="groupepiciids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., `[1, 2]`. | +| <a id="groupepicin"></a>`in` | [`[IssuableSearchableField!]`](#issuablesearchablefield) | Specify the fields to perform the search in. Defaults to `[TITLE, DESCRIPTION]`. Requires the `search` argument. | | <a id="groupepicincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include epics from ancestor groups. | | <a id="groupepicincludedescendantgroups"></a>`includeDescendantGroups` | [`Boolean`](#boolean) | Include epics from descendant groups. | | <a id="groupepiclabelname"></a>`labelName` | [`[String!]`](#string) | Filter epics by labels. | @@ -9235,7 +9445,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupepicsenddate"></a>`endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | <a id="groupepicsiid"></a>`iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | <a id="groupepicsiidstartswith"></a>`iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | -| <a id="groupepicsiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., [1, 2]. | +| <a id="groupepicsiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., `[1, 2]`. | +| <a id="groupepicsin"></a>`in` | [`[IssuableSearchableField!]`](#issuablesearchablefield) | Specify the fields to perform the search in. Defaults to `[TITLE, DESCRIPTION]`. Requires the `search` argument. | | <a id="groupepicsincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include epics from ancestor groups. | | <a id="groupepicsincludedescendantgroups"></a>`includeDescendantGroups` | [`Boolean`](#boolean) | Include epics from descendant groups. | | <a id="groupepicslabelname"></a>`labelName` | [`[String!]`](#string) | Filter epics by labels. | @@ -9289,7 +9500,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupissuescreatedbefore"></a>`createdBefore` | [`Time`](#time) | Issues created before this date. | | <a id="groupissuesepicid"></a>`epicId` | [`String`](#string) | ID of an epic associated with the issues, "none" and "any" values are supported. | | <a id="groupissuesiid"></a>`iid` | [`String`](#string) | IID of the issue. For example, "1". | -| <a id="groupissuesiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, ["1", "2"]. | +| <a id="groupissuesiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, `["1", "2"]`. | | <a id="groupissuesincludesubgroups"></a>`includeSubgroups` | [`Boolean`](#boolean) | Include issues belonging to subgroups. | | <a id="groupissuesiterationid"></a>`iterationId` | [`[ID]`](#id) | List of iteration Global IDs applied to the issue. | | <a id="groupissuesiterationwildcardid"></a>`iterationWildcardId` | [`IterationWildcardId`](#iterationwildcardid) | Filter by iteration ID wildcard. | @@ -9428,6 +9639,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupmilestonesincludeancestors"></a>`includeAncestors` | [`Boolean`](#boolean) | Include milestones from all parent groups. | | <a id="groupmilestonesincludedescendants"></a>`includeDescendants` | [`Boolean`](#boolean) | Include milestones from all subgroups and subprojects. | | <a id="groupmilestonessearchtitle"></a>`searchTitle` | [`String`](#string) | A search string for the title. | +| <a id="groupmilestonessort"></a>`sort` | [`MilestoneSort`](#milestonesort) | Sort milestones by this criteria. | | <a id="groupmilestonesstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | <a id="groupmilestonesstate"></a>`state` | [`MilestoneStateEnum`](#milestonestateenum) | Filter milestones by state. | | <a id="groupmilestonestimeframe"></a>`timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | @@ -9763,6 +9975,7 @@ Returns [`VulnerabilitySeveritiesCount`](#vulnerabilityseveritiescount). | <a id="issueblocked"></a>`blocked` | [`Boolean!`](#boolean) | Indicates the issue is blocked. | | <a id="issueblockedbycount"></a>`blockedByCount` | [`Int`](#int) | Count of issues blocking this issue. | | <a id="issueblockedbyissues"></a>`blockedByIssues` | [`IssueConnection`](#issueconnection) | Issues blocking this issue. (see [Connections](#connections)) | +| <a id="issueblockingcount"></a>`blockingCount` | [`Int!`](#int) | Count of issues this issue is blocking. | | <a id="issueclosedat"></a>`closedAt` | [`Time`](#time) | Timestamp of when the issue was closed. | | <a id="issueconfidential"></a>`confidential` | [`Boolean!`](#boolean) | Indicates the issue is confidential. | | <a id="issuecreatenoteemail"></a>`createNoteEmail` | [`String`](#string) | User specific email address for the issue. | @@ -9789,6 +10002,7 @@ Returns [`VulnerabilitySeveritiesCount`](#vulnerabilityseveritiescount). | <a id="issuemovedto"></a>`movedTo` | [`Issue`](#issue) | Updated Issue after it got moved to another project. | | <a id="issuenotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | | <a id="issueparticipants"></a>`participants` | [`UserCoreConnection`](#usercoreconnection) | List of participants in the issue. (see [Connections](#connections)) | +| <a id="issueprojectid"></a>`projectId` | [`Int!`](#int) | ID of the issue project. | | <a id="issuerelativeposition"></a>`relativePosition` | [`Int`](#int) | Relative position of the issue (used for positioning in epic tree and issue boards). | | <a id="issueseverity"></a>`severity` | [`IssuableSeverity`](#issuableseverity) | Severity level of the incident. | | <a id="issuesladueat"></a>`slaDueAt` | [`Time`](#time) | Timestamp of when the issue SLA expires. | @@ -10671,6 +10885,7 @@ Represents a milestone. | <a id="milestonecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of milestone creation. | | <a id="milestonedescription"></a>`description` | [`String`](#string) | Description of the milestone. | | <a id="milestoneduedate"></a>`dueDate` | [`Time`](#time) | Timestamp of the milestone due date. | +| <a id="milestoneexpired"></a>`expired` | [`Boolean!`](#boolean) | Expired state of the milestone (a milestone is expired when the due date is past the current date). Defaults to `false` when due date has not been set. | | <a id="milestonegroupmilestone"></a>`groupMilestone` | [`Boolean!`](#boolean) | Indicates if milestone is at group level. | | <a id="milestoneid"></a>`id` | [`ID!`](#id) | ID of the milestone. | | <a id="milestoneiid"></a>`iid` | [`ID!`](#id) | Internal ID of the milestone. | @@ -10771,7 +10986,9 @@ Represents the network policy. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="networkpolicyenabled"></a>`enabled` | [`Boolean!`](#boolean) | Indicates whether this policy is enabled. | +| <a id="networkpolicyenvironments"></a>`environments` | [`EnvironmentConnection`](#environmentconnection) | Environments where this policy is applied. (see [Connections](#connections)) | | <a id="networkpolicyfromautodevops"></a>`fromAutoDevops` | [`Boolean!`](#boolean) | Indicates whether this policy is created from AutoDevops. | +| <a id="networkpolicykind"></a>`kind` | [`NetworkPolicyKind!`](#networkpolicykind) | Kind of the policy. | | <a id="networkpolicyname"></a>`name` | [`String!`](#string) | Name of the policy. | | <a id="networkpolicynamespace"></a>`namespace` | [`String!`](#string) | Namespace of the policy. | | <a id="networkpolicyupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the policy YAML was last updated. | @@ -11020,6 +11237,7 @@ Represents a file or directory in the project repository that has been locked. | <a id="pipelinepath"></a>`path` | [`String`](#string) | Relative path to the pipeline's page. | | <a id="pipelineproject"></a>`project` | [`Project`](#project) | Project the pipeline belongs to. | | <a id="pipelinequeuedduration"></a>`queuedDuration` | [`Duration`](#duration) | How long the pipeline was queued before starting. | +| <a id="pipelineref"></a>`ref` | [`String`](#string) | Reference to the branch from which the pipeline was triggered. | | <a id="pipelineretryable"></a>`retryable` | [`Boolean!`](#boolean) | Specifies if a pipeline can be retried. | | <a id="pipelinesecurityreportsummary"></a>`securityReportSummary` | [`SecurityReportSummary`](#securityreportsummary) | Vulnerability and scanned resource counts for each security scanner of the pipeline. | | <a id="pipelinesha"></a>`sha` | [`String!`](#string) | SHA of the pipeline's commit. | @@ -11084,6 +11302,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="pipelinesecurityreportfindingsreporttype"></a>`reportType` | [`[String!]`](#string) | Filter vulnerability findings by report type. | | <a id="pipelinesecurityreportfindingsscanner"></a>`scanner` | [`[String!]`](#string) | Filter vulnerability findings by Scanner.externalId. | | <a id="pipelinesecurityreportfindingsseverity"></a>`severity` | [`[String!]`](#string) | Filter vulnerability findings by severity. | +| <a id="pipelinesecurityreportfindingsstate"></a>`state` | [`[VulnerabilityState!]`](#vulnerabilitystate) | Filter vulnerability findings by state. | ##### `Pipeline.testSuite` @@ -11178,11 +11397,12 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectautoclosereferencedissues"></a>`autocloseReferencedIssues` | [`Boolean`](#boolean) | Indicates if issues referenced by merge requests and commits within the default branch are closed automatically. | | <a id="projectavatarurl"></a>`avatarUrl` | [`String`](#string) | URL to avatar image file of the project. | | <a id="projectcicdsettings"></a>`ciCdSettings` | [`ProjectCiCdSetting`](#projectcicdsetting) | CI/CD settings for the project. | +| <a id="projectcijobtokenscope"></a>`ciJobTokenScope` | [`CiJobTokenScopeType`](#cijobtokenscopetype) | The CI Job Tokens scope of access. | | <a id="projectclusteragents"></a>`clusterAgents` | [`ClusterAgentConnection`](#clusteragentconnection) | Cluster agents associated with the project. (see [Connections](#connections)) | | <a id="projectcodecoveragesummary"></a>`codeCoverageSummary` | [`CodeCoverageSummary`](#codecoveragesummary) | Code coverage summary associated with the project. | | <a id="projectcomplianceframeworks"></a>`complianceFrameworks` | [`ComplianceFrameworkConnection`](#complianceframeworkconnection) | Compliance frameworks associated with the project. (see [Connections](#connections)) | | <a id="projectcontainerexpirationpolicy"></a>`containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | The container expiration policy of the project. | -| <a id="projectcontainerregistryenabled"></a>`containerRegistryEnabled` | [`Boolean`](#boolean) | Indicates if the project stores Docker container images in a container registry. | +| <a id="projectcontainerregistryenabled"></a>`containerRegistryEnabled` | [`Boolean`](#boolean) | Indicates if Container Registry is enabled for the current user. | | <a id="projectcontainerrepositoriescount"></a>`containerRepositoriesCount` | [`Int!`](#int) | Number of container repositories in the project. | | <a id="projectcreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of the project creation. | | <a id="projectdastprofiles"></a>`dastProfiles` | [`DastProfileConnection`](#dastprofileconnection) | DAST Profiles associated with the project. (see [Connections](#connections)) | @@ -11190,6 +11410,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectdastsiteprofiles"></a>`dastSiteProfiles` | [`DastSiteProfileConnection`](#dastsiteprofileconnection) | DAST Site Profiles associated with the project. (see [Connections](#connections)) | | <a id="projectdescription"></a>`description` | [`String`](#string) | Short description of the project. | | <a id="projectdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="projectdora"></a>`dora` | [`Dora`](#dora) | The project's DORA metrics. | | <a id="projectforkscount"></a>`forksCount` | [`Int!`](#int) | Number of times the project has been forked. | | <a id="projectfullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the project. | | <a id="projectgrafanaintegration"></a>`grafanaIntegration` | [`GrafanaIntegration`](#grafanaintegration) | Grafana integration details for the project. | @@ -11263,7 +11484,7 @@ Returns [`AlertManagementAlert`](#alertmanagementalert). | <a id="projectalertmanagementalertiid"></a>`iid` | [`String`](#string) | IID of the alert. For example, "1". | | <a id="projectalertmanagementalertsearch"></a>`search` | [`String`](#string) | Search query for title, description, service, or monitoring_tool. | | <a id="projectalertmanagementalertsort"></a>`sort` | [`AlertManagementAlertSort`](#alertmanagementalertsort) | Sort alerts by this criteria. | -| <a id="projectalertmanagementalertstatuses"></a>`statuses` | [`[AlertManagementStatus!]`](#alertmanagementstatus) | Alerts with the specified statues. For example, [TRIGGERED]. | +| <a id="projectalertmanagementalertstatuses"></a>`statuses` | [`[AlertManagementStatus!]`](#alertmanagementstatus) | Alerts with the specified statues. For example, `[TRIGGERED]`. | ##### `Project.alertManagementAlertStatusCounts` @@ -11297,7 +11518,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectalertmanagementalertsiid"></a>`iid` | [`String`](#string) | IID of the alert. For example, "1". | | <a id="projectalertmanagementalertssearch"></a>`search` | [`String`](#string) | Search query for title, description, service, or monitoring_tool. | | <a id="projectalertmanagementalertssort"></a>`sort` | [`AlertManagementAlertSort`](#alertmanagementalertsort) | Sort alerts by this criteria. | -| <a id="projectalertmanagementalertsstatuses"></a>`statuses` | [`[AlertManagementStatus!]`](#alertmanagementstatus) | Alerts with the specified statues. For example, [TRIGGERED]. | +| <a id="projectalertmanagementalertsstatuses"></a>`statuses` | [`[AlertManagementStatus!]`](#alertmanagementstatus) | Alerts with the specified statues. For example, `[TRIGGERED]`. | ##### `Project.alertManagementHttpIntegrations` @@ -11381,7 +11602,7 @@ Returns [`CiTemplate`](#citemplate). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectcitemplatename"></a>`name` | [`String!`](#string) | Name of the CI/CD template to search for. | +| <a id="projectcitemplatename"></a>`name` | [`String!`](#string) | Name of the CI/CD template to search for. Template must be formatted as `Name.gitlab-ci.yml`. | ##### `Project.clusterAgent` @@ -11520,7 +11741,7 @@ Returns [`Issue`](#issue). | <a id="projectissuecreatedbefore"></a>`createdBefore` | [`Time`](#time) | Issues created before this date. | | <a id="projectissueepicid"></a>`epicId` | [`String`](#string) | ID of an epic associated with the issues, "none" and "any" values are supported. | | <a id="projectissueiid"></a>`iid` | [`String`](#string) | IID of the issue. For example, "1". | -| <a id="projectissueiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, ["1", "2"]. | +| <a id="projectissueiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, `["1", "2"]`. | | <a id="projectissueiterationid"></a>`iterationId` | [`[ID]`](#id) | List of iteration Global IDs applied to the issue. | | <a id="projectissueiterationwildcardid"></a>`iterationWildcardId` | [`IterationWildcardId`](#iterationwildcardid) | Filter by iteration ID wildcard. | | <a id="projectissuelabelname"></a>`labelName` | [`[String]`](#string) | Labels applied to this issue. | @@ -11553,7 +11774,7 @@ Returns [`IssueStatusCountsType`](#issuestatuscountstype). | <a id="projectissuestatuscountscreatedafter"></a>`createdAfter` | [`Time`](#time) | Issues created after this date. | | <a id="projectissuestatuscountscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Issues created before this date. | | <a id="projectissuestatuscountsiid"></a>`iid` | [`String`](#string) | IID of the issue. For example, "1". | -| <a id="projectissuestatuscountsiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, ["1", "2"]. | +| <a id="projectissuestatuscountsiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, `["1", "2"]`. | | <a id="projectissuestatuscountslabelname"></a>`labelName` | [`[String]`](#string) | Labels applied to this issue. | | <a id="projectissuestatuscountsmilestonetitle"></a>`milestoneTitle` | [`[String]`](#string) | Milestone applied to this issue. | | <a id="projectissuestatuscountsnot"></a>`not` | [`NegatedIssueFilterInput`](#negatedissuefilterinput) | Negated arguments. | @@ -11586,7 +11807,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectissuescreatedbefore"></a>`createdBefore` | [`Time`](#time) | Issues created before this date. | | <a id="projectissuesepicid"></a>`epicId` | [`String`](#string) | ID of an epic associated with the issues, "none" and "any" values are supported. | | <a id="projectissuesiid"></a>`iid` | [`String`](#string) | IID of the issue. For example, "1". | -| <a id="projectissuesiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, ["1", "2"]. | +| <a id="projectissuesiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, `["1", "2"]`. | | <a id="projectissuesiterationid"></a>`iterationId` | [`[ID]`](#id) | List of iteration Global IDs applied to the issue. | | <a id="projectissuesiterationwildcardid"></a>`iterationWildcardId` | [`IterationWildcardId`](#iterationwildcardid) | Filter by iteration ID wildcard. | | <a id="projectissueslabelname"></a>`labelName` | [`[String]`](#string) | Labels applied to this issue. | @@ -11749,6 +11970,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectmilestonesids"></a>`ids` | [`[ID!]`](#id) | Array of global milestone IDs, e.g., `"gid://gitlab/Milestone/1"`. | | <a id="projectmilestonesincludeancestors"></a>`includeAncestors` | [`Boolean`](#boolean) | Also return milestones in the project's parent group and its ancestors. | | <a id="projectmilestonessearchtitle"></a>`searchTitle` | [`String`](#string) | A search string for the title. | +| <a id="projectmilestonessort"></a>`sort` | [`MilestoneSort`](#milestonesort) | Sort milestones by this criteria. | | <a id="projectmilestonesstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | <a id="projectmilestonesstate"></a>`state` | [`MilestoneStateEnum`](#milestonestateenum) | Filter milestones by state. | | <a id="projectmilestonestimeframe"></a>`timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | @@ -11878,7 +12100,7 @@ Returns [`Requirement`](#requirement). | ---- | ---- | ----------- | | <a id="projectrequirementauthorusername"></a>`authorUsername` | [`[String!]`](#string) | Filter requirements by author username. | | <a id="projectrequirementiid"></a>`iid` | [`ID`](#id) | IID of the requirement, e.g., "1". | -| <a id="projectrequirementiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of requirements, e.g., [1, 2]. | +| <a id="projectrequirementiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of requirements, e.g., `[1, 2]`. | | <a id="projectrequirementlasttestreportstate"></a>`lastTestReportState` | [`RequirementStatusFilter`](#requirementstatusfilter) | The state of latest requirement test report. | | <a id="projectrequirementsearch"></a>`search` | [`String`](#string) | Search query for requirement title. | | <a id="projectrequirementsort"></a>`sort` | [`Sort`](#sort) | List requirements by sort order. | @@ -11900,7 +12122,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="projectrequirementsauthorusername"></a>`authorUsername` | [`[String!]`](#string) | Filter requirements by author username. | | <a id="projectrequirementsiid"></a>`iid` | [`ID`](#id) | IID of the requirement, e.g., "1". | -| <a id="projectrequirementsiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of requirements, e.g., [1, 2]. | +| <a id="projectrequirementsiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of requirements, e.g., `[1, 2]`. | | <a id="projectrequirementslasttestreportstate"></a>`lastTestReportState` | [`RequirementStatusFilter`](#requirementstatusfilter) | The state of latest requirement test report. | | <a id="projectrequirementssearch"></a>`search` | [`String`](#string) | Search query for requirement title. | | <a id="projectrequirementssort"></a>`sort` | [`Sort`](#sort) | List requirements by sort order. | @@ -12152,6 +12374,15 @@ Pypi metadata. | <a id="pypimetadataid"></a>`id` | [`PackagesPypiMetadatumID!`](#packagespypimetadatumid) | ID of the metadatum. | | <a id="pypimetadatarequiredpython"></a>`requiredPython` | [`String`](#string) | Required Python version of the Pypi package. | +### `QueryComplexity` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="querycomplexitylimit"></a>`limit` | [`Int`](#int) | GraphQL query complexity limit. See [GitLab documentation on this limit](https://docs.gitlab.com/ee/api/graphql/index.html#max-query-complexity). | +| <a id="querycomplexityscore"></a>`score` | [`Int`](#int) | GraphQL query complexity score. | + ### `RecentFailures` Recent failure history of a test case. @@ -12194,6 +12425,7 @@ Represents an asset link associated with a release. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="releaseassetlinkdirectassetpath"></a>`directAssetPath` | [`String`](#string) | Relative path for the direct asset link. | | <a id="releaseassetlinkdirectasseturl"></a>`directAssetUrl` | [`String`](#string) | Direct asset URL of the link. | | <a id="releaseassetlinkexternal"></a>`external` | [`Boolean`](#boolean) | Indicates the link points to an external resource. | | <a id="releaseassetlinkid"></a>`id` | [`ID!`](#id) | ID of the link. | @@ -12549,6 +12781,7 @@ Represents summary of a security report. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="securityreportsummaryapifuzzing"></a>`apiFuzzing` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `api_fuzzing` scan. | +| <a id="securityreportsummaryclusterimagescanning"></a>`clusterImageScanning` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `cluster_image_scanning` scan. | | <a id="securityreportsummarycontainerscanning"></a>`containerScanning` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `container_scanning` scan. | | <a id="securityreportsummarycoveragefuzzing"></a>`coverageFuzzing` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `coverage_fuzzing` scan. | | <a id="securityreportsummarydast"></a>`dast` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `dast` scan. | @@ -12814,6 +13047,7 @@ Represents the snippet blob. | <a id="snippetblobpath"></a>`path` | [`String`](#string) | Blob path. | | <a id="snippetblobplaindata"></a>`plainData` | [`String`](#string) | Blob plain highlighted data. | | <a id="snippetblobrawpath"></a>`rawPath` | [`String!`](#string) | Blob raw content endpoint path. | +| <a id="snippetblobrawplaindata"></a>`rawPlainData` | [`String`](#string) | The raw content of the blob, if the blob is text data. | | <a id="snippetblobrenderedastext"></a>`renderedAsText` | [`Boolean!`](#boolean) | Shows whether the blob is rendered as text. | | <a id="snippetblobrichdata"></a>`richData` | [`String`](#string) | Blob highlighted data. | | <a id="snippetblobrichviewer"></a>`richViewer` | [`SnippetBlobViewer`](#snippetblobviewer) | Blob content rich viewer. | @@ -12874,6 +13108,7 @@ Represents the Geo sync and verification state of a snippet repository. | ---- | ---- | ----------- | | <a id="statusactionbuttontitle"></a>`buttonTitle` | [`String`](#string) | Title for the button, for example: Retry this job. | | <a id="statusactionicon"></a>`icon` | [`String`](#string) | Icon used in the action button. | +| <a id="statusactionid"></a>`id` | [`String!`](#string) | ID for a status action. | | <a id="statusactionmethod"></a>`method` | [`String`](#string) | Method for the action, for example: :post. | | <a id="statusactionpath"></a>`path` | [`String`](#string) | Path for the action. | | <a id="statusactiontitle"></a>`title` | [`String`](#string) | Title for the action, for example: Retry. | @@ -13155,7 +13390,7 @@ Represents a recorded measurement (object count) for the Admins. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="usercalloutdismissedat"></a>`dismissedAt` | [`Time`](#time) | Date when the callout was dismissed. | -| <a id="usercalloutfeaturename"></a>`featureName` | [`UserCalloutFeatureNameEnum!`](#usercalloutfeaturenameenum) | Name of the feature that the callout is for. | +| <a id="usercalloutfeaturename"></a>`featureName` | [`UserCalloutFeatureNameEnum`](#usercalloutfeaturenameenum) | Name of the feature that the callout is for. | ### `UserCore` @@ -13406,7 +13641,7 @@ Represents a vulnerability. | <a id="vulnerabilitynotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | | <a id="vulnerabilityprimaryidentifier"></a>`primaryIdentifier` | [`VulnerabilityIdentifier`](#vulnerabilityidentifier) | Primary identifier of the vulnerability. | | <a id="vulnerabilityproject"></a>`project` | [`Project`](#project) | The project on which the vulnerability was found. | -| <a id="vulnerabilityreporttype"></a>`reportType` | [`VulnerabilityReportType`](#vulnerabilityreporttype) | Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, COVERAGE_FUZZING, API_FUZZING). `Scan Type` in the UI. | +| <a id="vulnerabilityreporttype"></a>`reportType` | [`VulnerabilityReportType`](#vulnerabilityreporttype) | Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, COVERAGE_FUZZING, API_FUZZING, CLUSTER_IMAGE_SCANNING). `Scan Type` in the UI. | | <a id="vulnerabilityresolvedat"></a>`resolvedAt` | [`Time`](#time) | Timestamp of when the vulnerability state was changed to resolved. | | <a id="vulnerabilityresolvedby"></a>`resolvedBy` | [`UserCore`](#usercore) | The user that resolved the vulnerability. | | <a id="vulnerabilityresolvedondefaultbranch"></a>`resolvedOnDefaultBranch` | [`Boolean!`](#boolean) | Indicates whether the vulnerability is fixed on the default branch or not. | @@ -13851,8 +14086,8 @@ Values for sorting alerts. | <a id="alertmanagementalertsortseverity_desc"></a>`SEVERITY_DESC` | Severity from more critical to less critical. | | <a id="alertmanagementalertsortstarted_at_asc"></a>`STARTED_AT_ASC` | Start time by ascending order. | | <a id="alertmanagementalertsortstarted_at_desc"></a>`STARTED_AT_DESC` | Start time by descending order. | -| <a id="alertmanagementalertsortstatus_asc"></a>`STATUS_ASC` | Status by order: Ignored > Resolved > Acknowledged > Triggered. | -| <a id="alertmanagementalertsortstatus_desc"></a>`STATUS_DESC` | Status by order: Triggered > Acknowledged > Resolved > Ignored. | +| <a id="alertmanagementalertsortstatus_asc"></a>`STATUS_ASC` | Status by order: `Ignored > Resolved > Acknowledged > Triggered`. | +| <a id="alertmanagementalertsortstatus_desc"></a>`STATUS_DESC` | Status by order: `Triggered > Acknowledged > Resolved > Ignored`. | | <a id="alertmanagementalertsortupdated_asc"></a>`UPDATED_ASC` | Updated at ascending order. | | <a id="alertmanagementalertsortupdated_desc"></a>`UPDATED_DESC` | Updated at descending order. | | <a id="alertmanagementalertsortupdated_time_asc"></a>`UPDATED_TIME_ASC` | Created time by ascending order. | @@ -14207,6 +14442,18 @@ Weight of the data visualization palette. | <a id="datavisualizationweightenumweight_900"></a>`WEIGHT_900` | 900 weight. | | <a id="datavisualizationweightenumweight_950"></a>`WEIGHT_950` | 950 weight. | +### `DeploymentTier` + +All environment deployment tiers. + +| Value | Description | +| ----- | ----------- | +| <a id="deploymenttierdevelopment"></a>`DEVELOPMENT` | Development. | +| <a id="deploymenttierother"></a>`OTHER` | Other. | +| <a id="deploymenttierproduction"></a>`PRODUCTION` | Production. | +| <a id="deploymenttierstaging"></a>`STAGING` | Staging. | +| <a id="deploymenttiertesting"></a>`TESTING` | Testing. | + ### `DesignCollectionCopyState` Copy state of a DesignCollection. @@ -14237,6 +14484,25 @@ Type of file the position refers to. | <a id="diffpositiontypeimage"></a>`image` | An image. | | <a id="diffpositiontypetext"></a>`text` | A text file. | +### `DoraMetricBucketingInterval` + +All possible ways that DORA metrics can be aggregated. + +| Value | Description | +| ----- | ----------- | +| <a id="dorametricbucketingintervalall"></a>`ALL` | All data points are combined into a single value. | +| <a id="dorametricbucketingintervaldaily"></a>`DAILY` | Data points are combined into chunks by day. | +| <a id="dorametricbucketingintervalmonthly"></a>`MONTHLY` | Data points are combined into chunks by month. | + +### `DoraMetricType` + +All supported DORA metric types. + +| Value | Description | +| ----- | ----------- | +| <a id="dorametrictypedeployment_frequency"></a>`DEPLOYMENT_FREQUENCY` | Deployment frequency. | +| <a id="dorametrictypelead_time_for_changes"></a>`LEAD_TIME_FOR_CHANGES` | Lead time for changes. | + ### `EntryType` Type of a tree entry. @@ -14257,6 +14523,8 @@ Roadmap sort values. | <a id="epicsortend_date_desc"></a>`END_DATE_DESC` | Sort by end date in descending order. | | <a id="epicsortstart_date_asc"></a>`START_DATE_ASC` | Sort by start date in ascending order. | | <a id="epicsortstart_date_desc"></a>`START_DATE_DESC` | Sort by start date in descending order. | +| <a id="epicsorttitle_asc"></a>`TITLE_ASC` | Sort by title in ascending order. | +| <a id="epicsorttitle_desc"></a>`TITLE_DESC` | Sort by title in descending order. | | <a id="epicsortend_date_asc"></a>`end_date_asc` **{warning-solid}** | **Deprecated** in 13.11. Use END_DATE_ASC. | | <a id="epicsortend_date_desc"></a>`end_date_desc` **{warning-solid}** | **Deprecated** in 13.11. Use END_DATE_DESC. | | <a id="epicsortstart_date_asc"></a>`start_date_asc` **{warning-solid}** | **Deprecated** in 13.11. Use START_DATE_ASC. | @@ -14268,9 +14536,9 @@ State of an epic. | Value | Description | | ----- | ----------- | -| <a id="epicstateall"></a>`all` | | -| <a id="epicstateclosed"></a>`closed` | | -| <a id="epicstateopened"></a>`opened` | | +| <a id="epicstateall"></a>`all` | All epics. | +| <a id="epicstateclosed"></a>`closed` | Closed epics. | +| <a id="epicstateopened"></a>`opened` | Open epics. | ### `EpicStateEvent` @@ -14306,7 +14574,6 @@ Event action. | Value | Description | | ----- | ----------- | | <a id="eventactionapproved"></a>`APPROVED` | Approved action. | -| <a id="eventactionarchived"></a>`ARCHIVED` | Archived action. | | <a id="eventactionclosed"></a>`CLOSED` | Closed action. | | <a id="eventactioncommented"></a>`COMMENTED` | Commented action. | | <a id="eventactioncreated"></a>`CREATED` | Created action. | @@ -14335,9 +14602,18 @@ Health status of an issue or epic. | Value | Description | | ----- | ----------- | -| <a id="healthstatusatrisk"></a>`atRisk` | | -| <a id="healthstatusneedsattention"></a>`needsAttention` | | -| <a id="healthstatusontrack"></a>`onTrack` | | +| <a id="healthstatusatrisk"></a>`atRisk` | At risk. | +| <a id="healthstatusneedsattention"></a>`needsAttention` | Needs attention. | +| <a id="healthstatusontrack"></a>`onTrack` | On track. | + +### `IssuableSearchableField` + +Fields to perform the search in. + +| Value | Description | +| ----- | ----------- | +| <a id="issuablesearchablefielddescription"></a>`DESCRIPTION` | Search in description field. | +| <a id="issuablesearchablefieldtitle"></a>`TITLE` | Search in title field. | ### `IssuableSeverity` @@ -14368,6 +14644,8 @@ Values for sorting issues. | Value | Description | | ----- | ----------- | +| <a id="issuesortblocking_issues_asc"></a>`BLOCKING_ISSUES_ASC` | Blocking issues count by ascending order. | +| <a id="issuesortblocking_issues_desc"></a>`BLOCKING_ISSUES_DESC` | Blocking issues count by descending order. | | <a id="issuesortcreated_asc"></a>`CREATED_ASC` | Created at ascending order. | | <a id="issuesortcreated_desc"></a>`CREATED_DESC` | Created at descending order. | | <a id="issuesortdue_date_asc"></a>`DUE_DATE_ASC` | Due date by ascending order. | @@ -14376,6 +14654,8 @@ Values for sorting issues. | <a id="issuesortlabel_priority_desc"></a>`LABEL_PRIORITY_DESC` | Label priority by descending order. | | <a id="issuesortmilestone_due_asc"></a>`MILESTONE_DUE_ASC` | Milestone due date by ascending order. | | <a id="issuesortmilestone_due_desc"></a>`MILESTONE_DUE_DESC` | Milestone due date by descending order. | +| <a id="issuesortpopularity_asc"></a>`POPULARITY_ASC` | Number of upvotes (awarded "thumbs up" emoji) by ascending order. | +| <a id="issuesortpopularity_desc"></a>`POPULARITY_DESC` | Number of upvotes (awarded "thumbs up" emoji) by descending order. | | <a id="issuesortpriority_asc"></a>`PRIORITY_ASC` | Priority by ascending order. | | <a id="issuesortpriority_desc"></a>`PRIORITY_DESC` | Priority by descending order. | | <a id="issuesortpublished_asc"></a>`PUBLISHED_ASC` | Published issues shown last. | @@ -14433,8 +14713,9 @@ State of a GitLab iteration. | ----- | ----------- | | <a id="iterationstateall"></a>`all` | | | <a id="iterationstateclosed"></a>`closed` | | +| <a id="iterationstatecurrent"></a>`current` | | | <a id="iterationstateopened"></a>`opened` | | -| <a id="iterationstatestarted"></a>`started` | | +| <a id="iterationstatestarted"></a>`started` **{warning-solid}** | **Deprecated** in 14.1. Use current instead. | | <a id="iterationstateupcoming"></a>`upcoming` | | ### `IterationWildcardId` @@ -14456,6 +14737,7 @@ Iteration ID wildcard values. | <a id="jobartifactfiletypearchive"></a>`ARCHIVE` | ARCHIVE job artifact file type. | | <a id="jobartifactfiletypebrowser_performance"></a>`BROWSER_PERFORMANCE` | BROWSER PERFORMANCE job artifact file type. | | <a id="jobartifactfiletypecluster_applications"></a>`CLUSTER_APPLICATIONS` | CLUSTER APPLICATIONS job artifact file type. | +| <a id="jobartifactfiletypecluster_image_scanning"></a>`CLUSTER_IMAGE_SCANNING` | CLUSTER IMAGE SCANNING job artifact file type. | | <a id="jobartifactfiletypecobertura"></a>`COBERTURA` | COBERTURA job artifact file type. | | <a id="jobartifactfiletypecodequality"></a>`CODEQUALITY` | CODE QUALITY job artifact file type. | | <a id="jobartifactfiletypecontainer_scanning"></a>`CONTAINER_SCANNING` | CONTAINER SCANNING job artifact file type. | @@ -14578,6 +14860,25 @@ Representation of whether a GitLab merge request can be merged. | <a id="mergestrategyenummerge_train"></a>`MERGE_TRAIN` | Use the merge_train merge strategy. | | <a id="mergestrategyenummerge_when_pipeline_succeeds"></a>`MERGE_WHEN_PIPELINE_SUCCEEDS` | Use the merge_when_pipeline_succeeds merge strategy. | +### `MilestoneSort` + +Values for sorting milestones. + +| Value | Description | +| ----- | ----------- | +| <a id="milestonesortcreated_asc"></a>`CREATED_ASC` | Created at ascending order. | +| <a id="milestonesortcreated_desc"></a>`CREATED_DESC` | Created at descending order. | +| <a id="milestonesortdue_date_asc"></a>`DUE_DATE_ASC` | Milestone due date by ascending order. | +| <a id="milestonesortdue_date_desc"></a>`DUE_DATE_DESC` | Milestone due date by descending order. | +| <a id="milestonesortexpired_last_due_date_asc"></a>`EXPIRED_LAST_DUE_DATE_ASC` | Group milestones in this order: non-expired milestones with due dates, non-expired milestones without due dates and expired milestones then sort by due date in ascending order. | +| <a id="milestonesortexpired_last_due_date_desc"></a>`EXPIRED_LAST_DUE_DATE_DESC` | Group milestones in this order: non-expired milestones with due dates, non-expired milestones without due dates and expired milestones then sort by due date in descending order. | +| <a id="milestonesortupdated_asc"></a>`UPDATED_ASC` | Updated at ascending order. | +| <a id="milestonesortupdated_desc"></a>`UPDATED_DESC` | Updated at descending order. | +| <a id="milestonesortcreated_asc"></a>`created_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_ASC`. | +| <a id="milestonesortcreated_desc"></a>`created_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_DESC`. | +| <a id="milestonesortupdated_asc"></a>`updated_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_ASC`. | +| <a id="milestonesortupdated_desc"></a>`updated_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_DESC`. | + ### `MilestoneStateEnum` Current state of milestone. @@ -14623,6 +14924,15 @@ Negated Iteration ID wildcard values. | ----- | ----------- | | <a id="negatediterationwildcardidcurrent"></a>`CURRENT` | Current iteration. | +### `NetworkPolicyKind` + +Kind of the network policy. + +| Value | Description | +| ----- | ----------- | +| <a id="networkpolicykindciliumnetworkpolicy"></a>`CiliumNetworkPolicy` | The policy kind of Cilium Network Policy. | +| <a id="networkpolicykindnetworkpolicy"></a>`NetworkPolicy` | The policy kind of Network Policy. | + ### `OncallRotationUnitEnum` Rotation length unit of an on-call rotation. @@ -14799,6 +15109,7 @@ Size of UI component in SAST configuration page. | Value | Description | | ----- | ----------- | | <a id="securityreporttypeenumapi_fuzzing"></a>`API_FUZZING` | API FUZZING scan report. | +| <a id="securityreporttypeenumcluster_image_scanning"></a>`CLUSTER_IMAGE_SCANNING` | CLUSTER IMAGE SCANNING scan report. | | <a id="securityreporttypeenumcontainer_scanning"></a>`CONTAINER_SCANNING` | CONTAINER SCANNING scan report. | | <a id="securityreporttypeenumcoverage_fuzzing"></a>`COVERAGE_FUZZING` | COVERAGE FUZZING scan report. | | <a id="securityreporttypeenumdast"></a>`DAST` | DAST scan report. | @@ -14813,6 +15124,7 @@ The type of the security scanner. | Value | Description | | ----- | ----------- | | <a id="securityscannertypeapi_fuzzing"></a>`API_FUZZING` | | +| <a id="securityscannertypecluster_image_scanning"></a>`CLUSTER_IMAGE_SCANNING` | | | <a id="securityscannertypecontainer_scanning"></a>`CONTAINER_SCANNING` | | | <a id="securityscannertypecoverage_fuzzing"></a>`COVERAGE_FUZZING` | | | <a id="securityscannertypedast"></a>`DAST` | | @@ -14964,6 +15276,7 @@ Name of the feature that the callout is for. | <a id="usercalloutfeaturenameenumactive_user_count_threshold"></a>`ACTIVE_USER_COUNT_THRESHOLD` | Callout feature name for active_user_count_threshold. | | <a id="usercalloutfeaturenameenumbuy_pipeline_minutes_notification_dot"></a>`BUY_PIPELINE_MINUTES_NOTIFICATION_DOT` | Callout feature name for buy_pipeline_minutes_notification_dot. | | <a id="usercalloutfeaturenameenumcanary_deployment"></a>`CANARY_DEPLOYMENT` | Callout feature name for canary_deployment. | +| <a id="usercalloutfeaturenameenumcloud_licensing_subscription_activation_banner"></a>`CLOUD_LICENSING_SUBSCRIPTION_ACTIVATION_BANNER` | Callout feature name for cloud_licensing_subscription_activation_banner. | | <a id="usercalloutfeaturenameenumcluster_security_warning"></a>`CLUSTER_SECURITY_WARNING` | Callout feature name for cluster_security_warning. | | <a id="usercalloutfeaturenameenumcustomize_homepage"></a>`CUSTOMIZE_HOMEPAGE` | Callout feature name for customize_homepage. | | <a id="usercalloutfeaturenameenumeoa_bronze_plan_banner"></a>`EOA_BRONZE_PLAN_BANNER` | Callout feature name for eoa_bronze_plan_banner. | @@ -14978,12 +15291,15 @@ Name of the feature that the callout is for. | <a id="usercalloutfeaturenameenumpipeline_needs_banner"></a>`PIPELINE_NEEDS_BANNER` | Callout feature name for pipeline_needs_banner. | | <a id="usercalloutfeaturenameenumpipeline_needs_hover_tip"></a>`PIPELINE_NEEDS_HOVER_TIP` | Callout feature name for pipeline_needs_hover_tip. | | <a id="usercalloutfeaturenameenumregistration_enabled_callout"></a>`REGISTRATION_ENABLED_CALLOUT` | Callout feature name for registration_enabled_callout. | +| <a id="usercalloutfeaturenameenumsecurity_configuration_devops_alert"></a>`SECURITY_CONFIGURATION_DEVOPS_ALERT` | Callout feature name for security_configuration_devops_alert. | | <a id="usercalloutfeaturenameenumsecurity_configuration_upgrade_banner"></a>`SECURITY_CONFIGURATION_UPGRADE_BANNER` | Callout feature name for security_configuration_upgrade_banner. | | <a id="usercalloutfeaturenameenumservice_templates_deprecated_callout"></a>`SERVICE_TEMPLATES_DEPRECATED_CALLOUT` | Callout feature name for service_templates_deprecated_callout. | | <a id="usercalloutfeaturenameenumsuggest_pipeline"></a>`SUGGEST_PIPELINE` | Callout feature name for suggest_pipeline. | | <a id="usercalloutfeaturenameenumsuggest_popover_dismissed"></a>`SUGGEST_POPOVER_DISMISSED` | Callout feature name for suggest_popover_dismissed. | | <a id="usercalloutfeaturenameenumtabs_position_highlight"></a>`TABS_POSITION_HIGHLIGHT` | Callout feature name for tabs_position_highlight. | | <a id="usercalloutfeaturenameenumthreat_monitoring_info"></a>`THREAT_MONITORING_INFO` | Callout feature name for threat_monitoring_info. | +| <a id="usercalloutfeaturenameenumtrial_status_reminder_d14"></a>`TRIAL_STATUS_REMINDER_D14` | Callout feature name for trial_status_reminder_d14. | +| <a id="usercalloutfeaturenameenumtrial_status_reminder_d3"></a>`TRIAL_STATUS_REMINDER_D3` | Callout feature name for trial_status_reminder_d3. | | <a id="usercalloutfeaturenameenumultimate_trial"></a>`ULTIMATE_TRIAL` | Callout feature name for ultimate_trial. | | <a id="usercalloutfeaturenameenumunfinished_tag_cleanup_callout"></a>`UNFINISHED_TAG_CLEANUP_CALLOUT` | Callout feature name for unfinished_tag_cleanup_callout. | | <a id="usercalloutfeaturenameenumweb_ide_alert_dismissed"></a>`WEB_IDE_ALERT_DISMISSED` | Callout feature name for web_ide_alert_dismissed. | @@ -15071,6 +15387,7 @@ The type of the security scan that found the vulnerability. | Value | Description | | ----- | ----------- | | <a id="vulnerabilityreporttypeapi_fuzzing"></a>`API_FUZZING` | | +| <a id="vulnerabilityreporttypecluster_image_scanning"></a>`CLUSTER_IMAGE_SCANNING` | | | <a id="vulnerabilityreporttypecontainer_scanning"></a>`CONTAINER_SCANNING` | | | <a id="vulnerabilityreporttypecoverage_fuzzing"></a>`COVERAGE_FUZZING` | | | <a id="vulnerabilityreporttypedast"></a>`DAST` | | @@ -15386,6 +15703,13 @@ An example `IncidentManagementOncallRotationID` is: `"gid://gitlab/IncidentManag Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1. +### `IntegrationsPrometheusID` + +A `IntegrationsPrometheusID` is a global ID. It is encoded as a string. + +An example `IntegrationsPrometheusID` is: `"gid://gitlab/Integrations::Prometheus/1"`. +The older format `"gid://gitlab/PrometheusService/1"` was deprecated in 14.1. + ### `IssuableID` A `IssuableID` is a global ID. It is encoded as a string. @@ -15531,12 +15855,6 @@ A `ProjectID` is a global ID. It is encoded as a string. An example `ProjectID` is: `"gid://gitlab/Project/1"`. -### `PrometheusServiceID` - -A `PrometheusServiceID` is a global ID. It is encoded as a string. - -An example `PrometheusServiceID` is: `"gid://gitlab/PrometheusService/1"`. - ### `ReleasesLinkID` A `ReleasesLinkID` is a global ID. It is encoded as a string. @@ -15636,6 +15954,16 @@ One of: - [`Issue`](#issue) - [`MergeRequest`](#mergerequest) +#### `NoteableType` + +Represents an object that supports notes. + +One of: + +- [`Design`](#design) +- [`Issue`](#issue) +- [`MergeRequest`](#mergerequest) + #### `PackageMetadata` Represents metadata associated with a Package. @@ -15804,7 +16132,7 @@ Implementations: | <a id="memberinterfaceupdatedat"></a>`updatedAt` | [`Time`](#time) | Date and time the membership was last updated. | | <a id="memberinterfaceuser"></a>`user` | [`UserCore`](#usercore) | User that is associated with the member object. | -#### `Noteable` +#### `NoteableInterface` Implementations: @@ -15822,8 +16150,8 @@ Implementations: | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="noteablediscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | -| <a id="noteablenotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | +| <a id="noteableinterfacediscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | +| <a id="noteableinterfacenotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | #### `PackageFileMetadata` @@ -16091,7 +16419,7 @@ Field that are available while modifying the custom mapping attributes for an HT | <a id="boardissueinputauthorusername"></a>`authorUsername` | [`String`](#string) | Filter by author username. | | <a id="boardissueinputepicid"></a>`epicId` | [`EpicID`](#epicid) | Filter by epic ID. Incompatible with epicWildcardId. | | <a id="boardissueinputepicwildcardid"></a>`epicWildcardId` | [`EpicWildcardId`](#epicwildcardid) | Filter by epic ID wildcard. Incompatible with epicId. | -| <a id="boardissueinputiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example ["1", "2"]. | +| <a id="boardissueinputiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example `["1", "2"]`. | | <a id="boardissueinputiterationid"></a>`iterationId` | [`[IterationID!]`](#iterationid) | Filter by a list of iteration IDs. Incompatible with iterationWildcardId. | | <a id="boardissueinputiterationtitle"></a>`iterationTitle` | [`String`](#string) | Filter by iteration title. | | <a id="boardissueinputiterationwildcardid"></a>`iterationWildcardId` | [`IterationWildcardId`](#iterationwildcardid) | Filter by iteration ID wildcard. | @@ -16245,7 +16573,7 @@ Represents an escalation rule. | <a id="negatedboardissueinputassigneeusername"></a>`assigneeUsername` | [`[String]`](#string) | Filter by assignee username. | | <a id="negatedboardissueinputauthorusername"></a>`authorUsername` | [`String`](#string) | Filter by author username. | | <a id="negatedboardissueinputepicid"></a>`epicId` | [`EpicID`](#epicid) | Filter by epic ID. Incompatible with epicWildcardId. | -| <a id="negatedboardissueinputiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example ["1", "2"]. | +| <a id="negatedboardissueinputiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example `["1", "2"]`. | | <a id="negatedboardissueinputiterationid"></a>`iterationId` | [`[IterationID!]`](#iterationid) | Filter by a list of iteration IDs. Incompatible with iterationWildcardId. | | <a id="negatedboardissueinputiterationtitle"></a>`iterationTitle` | [`String`](#string) | Filter by iteration title. | | <a id="negatedboardissueinputiterationwildcardid"></a>`iterationWildcardId` | [`NegatedIterationWildcardId`](#negatediterationwildcardid) | Filter by iteration ID wildcard. | @@ -16284,7 +16612,7 @@ Represents an escalation rule. | <a id="negatedissuefilterinputassigneeid"></a>`assigneeId` | [`String`](#string) | ID of a user not assigned to the issues. | | <a id="negatedissuefilterinputassigneeusernames"></a>`assigneeUsernames` | [`[String!]`](#string) | Usernames of users not assigned to the issue. | | <a id="negatedissuefilterinputepicid"></a>`epicId` | [`String`](#string) | ID of an epic not associated with the issues. | -| <a id="negatedissuefilterinputiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues to exclude. For example, [1, 2]. | +| <a id="negatedissuefilterinputiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues to exclude. For example, `[1, 2]`. | | <a id="negatedissuefilterinputiterationid"></a>`iterationId` | [`[ID!]`](#id) | List of iteration Global IDs not applied to the issue. | | <a id="negatedissuefilterinputiterationwildcardid"></a>`iterationWildcardId` | [`IterationWildcardId`](#iterationwildcardid) | Filter by negated iteration ID wildcard. | | <a id="negatedissuefilterinputlabelname"></a>`labelName` | [`[String!]`](#string) | Labels not applied to this issue. | diff --git a/doc/api/graphql/sample_issue_boards.md b/doc/api/graphql/sample_issue_boards.md index 86881465ed6..68c12aa26a2 100644 --- a/doc/api/graphql/sample_issue_boards.md +++ b/doc/api/graphql/sample_issue_boards.md @@ -4,10 +4,10 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Identify issue boards with GraphQL +# Identify issue boards with GraphQL **(FREE)** This page describes how you can use the GraphiQL explorer to identify -existing issue boards in the `gitlab-docs` documentation repository. +existing [issue boards](../../user/project/issue_board.md) in the `gitlab-docs` documentation repository. ## Set up the GraphiQL explorer diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index 63ba71797fc..463507bf583 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -34,7 +34,7 @@ GET /groups/:id/badges | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | no | Name of the badges to return (case-sensitive). | ```shell @@ -67,7 +67,7 @@ GET /groups/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | ```shell @@ -97,7 +97,7 @@ POST /groups/:id/badges | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link | | `image_url` | string | yes | URL of the badge image | @@ -130,7 +130,7 @@ PUT /groups/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | | `link_url` | string | no | URL of the badge link | | `image_url` | string | no | URL of the badge image | @@ -163,7 +163,7 @@ DELETE /groups/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | ```shell @@ -180,7 +180,7 @@ GET /groups/:id/badges/render | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link| | `image_url` | string | yes | URL of the badge image | diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index a0121388194..eaa7b57e520 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -4,16 +4,16 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group Issue Boards API +# Group issue boards API **(FREE)** -Every API call to group boards must be authenticated. +Every API call to [group issue boards](../user/project/issue_board.md#group-issue-boards) must be authenticated. If a user is not a member of a group and the group is private, a `GET` request results in `404` status code. ## List all group issue boards in a group -Lists Issue Boards in the given group. +Lists issue boards in the given group. ```plaintext GET /groups/:id/boards @@ -21,7 +21,7 @@ GET /groups/:id/boards | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/boards" @@ -138,7 +138,7 @@ GET /groups/:id/boards/:board_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -252,7 +252,7 @@ POST /groups/:id/boards | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the new board | ```shell @@ -291,7 +291,7 @@ PUT /groups/:id/boards/:board_id | Attribute | Type | Required | Description | | ---------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `name` | string | no | The new name of the board | | `hide_backlog_list` | boolean | no | Hide the Open list | @@ -359,7 +359,7 @@ DELETE /groups/:id/boards/:board_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -377,7 +377,7 @@ GET /groups/:id/boards/:board_id/lists | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -428,7 +428,7 @@ GET /groups/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | @@ -460,7 +460,7 @@ POST /groups/:id/boards/:board_id/lists | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `label_id` | integer | yes | The ID of a label | @@ -501,7 +501,7 @@ PUT /groups/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | | `position` | integer | yes | The position of the list | @@ -534,7 +534,7 @@ DELETE /groups/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index 6853e38cc32..83373368fc6 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -27,7 +27,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | Example request: @@ -96,7 +96,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | -------------- | -------- | ----------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `cluster_id` | integer | yes | The ID of the cluster | Example request: @@ -165,7 +165,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------------------------------------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `name` | string | yes | The name of the cluster | | `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | | `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | @@ -236,7 +236,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `cluster_id` | integer | yes | The ID of the cluster | | `name` | string | no | The name of the cluster | | `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | @@ -258,7 +258,7 @@ Example request: ```shell curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/groups/26/clusters/24" \ -H "Content-Type:application/json" \ ---request PUT --data '{"name":"new-cluster-name","domain":"new-domain.com","api_url":"https://new-api-url.com"}' +--request PUT --data '{"name":"new-cluster-name","domain":"new-domain.com","platform_kubernetes_attributes":{"api_url":"https://10.10.101.1:6433"}}' ``` Example response: @@ -321,7 +321,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | -------------- | -------- | ----------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `cluster_id` | integer | yes | The ID of the cluster | Example request: diff --git a/doc/api/group_iterations.md b/doc/api/group_iterations.md index 3d72e035383..af27b558dfe 100644 --- a/doc/api/group_iterations.md +++ b/doc/api/group_iterations.md @@ -26,7 +26,7 @@ GET /groups/:id/iterations?search=version | Attribute | Type | Required | Description | | ------------------- | ------- | -------- | ----------- | -| `state` | string | no | Return only `opened`, `upcoming`, `started`, `closed`, or `all` iterations. Defaults to `all`. | +| `state` | string | no | 'Return `opened`, `upcoming`, `current (previously started)`, `closed`, or `all` iterations. Filtering by `started` state is deprecated starting with 14.1, please use `current` instead.' | | `search` | string | no | Return only iterations with a title matching the provided string. | | `include_ancestors` | boolean | no | Include iterations from parent group and its ancestors. Defaults to `true`. | diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index 2aca98259e0..25102e32360 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -4,11 +4,13 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group Labels API +# Group labels API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21368) in GitLab 11.8. -This API supports managing of [group labels](../user/project/labels.md#project-labels-and-group-labels). It allows to list, create, update, and delete group labels. Furthermore, users can subscribe and unsubscribe to and from group labels. +This API supports managing [group labels](../user/project/labels.md#project-labels-and-group-labels). +It allows users to list, create, update, and delete group labels. Furthermore, users can subscribe to and +unsubscribe from group labels. NOTE: The `description_html` - was added to response JSON in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413). @@ -23,7 +25,7 @@ GET /groups/:id/labels | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | | `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced in GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543))_ | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | | `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | @@ -75,7 +77,7 @@ GET /groups/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | | `label_id` | integer or string | yes | The ID or title of a group's label. | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | | `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | @@ -112,9 +114,9 @@ POST /groups/:id/labels | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the label | -| `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | +| `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The description of the label, | ```shell @@ -150,10 +152,10 @@ PUT /groups/:id/labels/:label_id | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | | `new_name` | string | no | The new name of the label | -| `color` | string | no | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | +| `color` | string | no | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The description of the label. | ```shell @@ -191,7 +193,7 @@ DELETE /groups/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -212,7 +214,7 @@ POST /groups/:id/labels/:label_id/subscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -248,7 +250,7 @@ POST /groups/:id/labels/:label_id/unsubscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index 6425e022170..f816f2dc173 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.md @@ -18,7 +18,7 @@ GET /groups/:id/variables | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables" @@ -55,7 +55,7 @@ GET /groups/:id/variables/:key | Attribute | Type | required | Description | |-----------|---------|----------|-----------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | ```shell @@ -83,13 +83,13 @@ POST /groups/:id/variables | Attribute | Type | required | Description | |-----------------|---------|----------|-----------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.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 | | `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` | | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | -| `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/variables/README.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | +| `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -117,13 +117,13 @@ PUT /groups/:id/variables/:key | Attribute | Type | required | Description | |-----------------|---------|----------|-------------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` 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` | | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | -| `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/variables/README.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | +| `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -151,7 +151,7 @@ DELETE /groups/:id/variables/:key | Attribute | Type | required | Description | |-----------|---------|----------|-------------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | ```shell diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index 40d51f90b5a..a21af94da40 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -4,11 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group milestones API +# Group milestones API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12819) in GitLab 9.5. - -This page describes the group milestones API. +Use the group [milestones](../user/project/milestones/index.md) using the REST API. There's a separate [project milestones API](milestones.md) page. ## List group milestones @@ -29,7 +27,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the milestones having the given `iid` (Note: ignored if `include_parent_milestones` is set as `true`) | | `state` | string | no | Return only `active` or `closed` milestones | | `title` | string | no | Return only the milestones having the given `title` | @@ -73,7 +71,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the group milestone | ## Create new milestone @@ -88,7 +86,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | The title of a milestone | | `description` | string | no | The description of the milestone | | `due_date` | date | no | The due date of the milestone, in YYYY-MM-DD format (ISO 8601) | @@ -106,7 +104,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | | `title` | string | no | The title of a milestone | | `description` | string | no | The description of a milestone | @@ -116,7 +114,7 @@ Parameters: ## Delete group milestone -Only for users with Developer access to the group. +Only for users with the Developer role in the group. ```plaintext DELETE /groups/:id/milestones/:milestone_id @@ -126,7 +124,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the group's milestone | ## Get all issues assigned to a single milestone @@ -141,7 +139,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | Currently, this API endpoint doesn't return issues from any subgroups. @@ -161,7 +159,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | ## Get all burndown chart events for a single milestone **(PREMIUM)** @@ -179,5 +177,5 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md index d4e27a7200a..ce5803fed3c 100644 --- a/doc/api/group_protected_environments.md +++ b/doc/api/group_protected_environments.md @@ -40,7 +40,7 @@ GET /groups/:id/protected_environments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/protected_environments/" @@ -74,7 +74,7 @@ GET /groups/:id/protected_environments/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | | `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| ```shell @@ -107,7 +107,7 @@ POST /groups/:id/protected_environments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | | `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| | `deploy_access_levels` | array | yes | Array of access levels allowed to deploy, with each described by a hash. One of `user_id`, `group_id` or `access_level`. They take the form of `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}` respectively. | @@ -144,7 +144,7 @@ DELETE /groups/:id/protected_environments/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | | `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| ```shell diff --git a/doc/api/group_repository_storage_moves.md b/doc/api/group_repository_storage_moves.md index 2373fa25e15..53afe8d5ef3 100644 --- a/doc/api/group_repository_storage_moves.md +++ b/doc/api/group_repository_storage_moves.md @@ -16,19 +16,19 @@ example, or to migrate a Group Wiki. As group repository storage moves are processed, they transition through different states. Values of `state` are: -- `initial` -- `scheduled` -- `started` -- `finished` -- `failed` -- `replicated` -- `cleanup failed` +- `initial`: The record has been created but the background job has not yet been scheduled. +- `scheduled`: The background job has been scheduled. +- `started`: The group repositories are being copied to the destination storage. +- `replicated`: The group has been moved. +- `failed`: The group repositories failed to copy or the checksums did not match. +- `finished`: The group has been moved and the repositories on the source storage have been deleted. +- `cleanup failed`: The group has been moved but the repositories on the source storage could not be deleted. To ensure data integrity, groups are put in a temporary read-only state for the duration of the move. During this time, users receive a `The repository is temporarily read-only. Please try again later.` message if they try to push new commits. -This API requires you to [authenticate yourself](README.md#authentication) as an administrator. +This API requires you to [authenticate yourself](index.md#authentication) as an administrator. For other type of repositories you can read: @@ -42,7 +42,7 @@ GET /group_repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](README.md#pagination). +are [paginated](index.md#pagination). Example request: @@ -78,7 +78,7 @@ GET /groups/:group_id/repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](README.md#pagination). +are [paginated](index.md#pagination). Supported attributes: diff --git a/doc/api/group_wikis.md b/doc/api/group_wikis.md index 58192425786..e1470a2cdd7 100644 --- a/doc/api/group_wikis.md +++ b/doc/api/group_wikis.md @@ -22,7 +22,7 @@ GET /groups/:id/wikis | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `with_content` | boolean | no | Include pages' content | ```shell @@ -63,7 +63,7 @@ GET /groups/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | ```shell @@ -91,7 +91,7 @@ POST /projects/:id/wikis | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `content` | string | yes | The content of the wiki page | | `title` | string | yes | The title of the wiki page | | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | @@ -123,7 +123,7 @@ PUT /groups/:id/wikis/:slug | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `content` | string | yes if `title` is not provided | The content of the wiki page | | `title` | string | yes if `content` is not provided | The title of the wiki page | | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | @@ -156,7 +156,7 @@ DELETE /groups/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | ```shell @@ -176,7 +176,7 @@ POST /groups/:id/wikis/attachments | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `file` | string | yes | The attachment to be uploaded | | `branch` | string | no | The name of the branch. Defaults to the wiki repository default branch | diff --git a/doc/api/groups.md b/doc/api/groups.md index de2c6c95bcd..23a8dba954f 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Get a list of visible groups for the authenticated user. When accessed without authentication, only public groups are returned. -By default, this request returns 20 results at a time because the API results [are paginated](README.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). Parameters: @@ -20,7 +20,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 administrators); Attributes `owned` and `min_access_level` have precedence | | `search` | string | no | Return the list of authorized groups matching the search criteria | -| `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` | +| `order_by` | string | no | Order groups by `name`, `path`, `id`, or `similarity` (if searching, [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332889) in GitLab 14.1). Default is `name` | | `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | | `statistics` | boolean | no | Include group statistics (administrators only) | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | @@ -122,13 +122,13 @@ GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_valu Get a list of visible direct subgroups in this group. When accessed without authentication, only public groups are returned. -By default, this request returns 20 results at a time because the API results [are paginated](README.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). Parameters: | Attribute | Type | Required | Description | | ------------------------ | ----------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) of the immediate parent group | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) of the immediate parent group | | `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 administrators); Attributes `owned` and `min_access_level` have precedence | | `search` | string | no | Return the list of authorized groups matching the search criteria | @@ -180,13 +180,13 @@ GET /groups/:id/subgroups Get a list of visible descendant groups of this group. When accessed without authentication, only public groups are returned. -By default, this request returns 20 results at a time because the API results [are paginated](README.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). Parameters: | Attribute | Type | Required | Description | | ------------------------ | ----------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) of the immediate parent group | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) of the immediate parent group | | `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 administrators). Attributes `owned` and `min_access_level` have precedence | | `search` | string | no | Return the list of authorized groups matching the search criteria | @@ -260,7 +260,7 @@ GET /groups/:id/descendant_groups Get a list of projects in this group. When accessed without authentication, only public projects are returned. -By default, this request returns 20 results at a time because the API results [are paginated](README.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). ```plaintext GET /groups/:id/projects @@ -270,7 +270,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `archived` | boolean | no | Limit by archived status | | `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | | `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `similarity` (1), or `last_activity_at` fields. Default is `created_at` | @@ -346,7 +346,7 @@ To distinguish between a project in the group and a project shared to the group, Get a list of projects shared to this group. When accessed without authentication, only public shared projects are returned. -By default, this request returns 20 results at a time because the API results [are paginated](README.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). ```plaintext GET /groups/:id/projects/shared @@ -356,7 +356,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `archived` | boolean | no | Limit by archived status | | `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | | `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | @@ -489,7 +489,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------ | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only). | | `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use the [list a group's projects endpoint](#list-a-groups-projects).) | @@ -535,6 +535,7 @@ Example response: "expires_at": null } ], + "prevent_sharing_groups_outside_hierarchy": false, "projects": [ // Deprecated and will be removed in API v5 { "id": 7, @@ -673,6 +674,8 @@ Example response: } ``` +The `prevent_sharing_groups_outside_hierarchy` attribute is present only on top-level groups. + Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters: @@ -835,8 +838,8 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the target group](README.md#namespaced-path-encoding) | -| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the target group](index.md#namespaced-path-encoding) | +| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -851,31 +854,32 @@ Updates the project group. Only available to group owners and administrators. PUT /groups/:id ``` -| Attribute | Type | Required | Description | -| ------------------------------------ | ------- | -------- | ----------- | -| `id` | integer | yes | The ID of the group. | -| `name` | string | no | The name of the group. | -| `path` | string | no | The path of the group. | -| `description` | string | no | The description of the group. | -| `membership_lock` | boolean | no | **(PREMIUM)** Prevent adding new members to project membership within this group. | -| `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group. | -| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. | -| `require_two_factor_authentication` | boolean | no | Require all users in this group to setup Two-factor authentication. | -| `two_factor_grace_period` | integer | no | Time before Two-factor authentication is enforced (in hours). | -| `project_creation_level` | string | no | Determine if developers can create projects in the group. Can be `noone` (No one), `maintainer` (Maintainers), or `developer` (Developers + Maintainers). | -| `auto_devops_enabled` | boolean | no | Default to Auto DevOps pipeline for all projects within this group. | -| `subgroup_creation_level` | string | no | Allowed to [create subgroups](../user/group/subgroups/index.md#creating-a-subgroup). Can be `owner` (Owners), or `maintainer` (Maintainers). | -| `emails_disabled` | boolean | no | Disable email notifications | -| `avatar` | mixed | no | Image file for avatar of the group. [Introduced in GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/36681) | -| `mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned | -| `lfs_enabled` (optional) | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group. | -| `request_access_enabled` | boolean | no | Allow users to request member access. | -| `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). | -| `file_template_project_id` | integer | no | **(PREMIUM)** The ID of a project to load custom file templates from. | -| `shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | -| `extra_shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | -| `prevent_forking_outside_group` | boolean | no | **(PREMIUM)** When enabled, users can **not** fork projects from this group to external namespaces -| `shared_runners_setting` | string | no | See [Options for `shared_runners_setting`](#options-for-shared_runners_setting). Enable or disable shared runners for a group's subgroups and projects. | +| Attribute | Type | Required | Description | +| ------------------------------------------ | ------- | -------- | ----------- | +| `id` | integer | yes | The ID of the group. | +| `name` | string | no | The name of the group. | +| `path` | string | no | The path of the group. | +| `description` | string | no | The description of the group. | +| `membership_lock` | boolean | no | **(PREMIUM)** Prevent adding new members to project membership within this group. | +| `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group. | +| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. | +| `require_two_factor_authentication` | boolean | no | Require all users in this group to setup Two-factor authentication. | +| `two_factor_grace_period` | integer | no | Time before Two-factor authentication is enforced (in hours). | +| `project_creation_level` | string | no | Determine if developers can create projects in the group. Can be `noone` (No one), `maintainer` (Maintainers), or `developer` (Developers + Maintainers). | +| `auto_devops_enabled` | boolean | no | Default to Auto DevOps pipeline for all projects within this group. | +| `subgroup_creation_level` | string | no | Allowed to [create subgroups](../user/group/subgroups/index.md#creating-a-subgroup). Can be `owner` (Owners), or `maintainer` (Maintainers). | +| `emails_disabled` | boolean | no | Disable email notifications | +| `avatar` | mixed | no | Image file for avatar of the group. [Introduced in GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/36681) | +| `mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned | +| `lfs_enabled` (optional) | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group. | +| `request_access_enabled` | boolean | no | Allow users to request member access. | +| `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). | +| `file_template_project_id` | integer | no | **(PREMIUM)** The ID of a project to load custom file templates from. | +| `shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | +| `extra_shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | +| `prevent_forking_outside_group` | boolean | no | **(PREMIUM)** When enabled, users can **not** fork projects from this group to external namespaces +| `shared_runners_setting` | string | no | See [Options for `shared_runners_setting`](#options-for-shared_runners_setting). Enable or disable shared runners for a group's subgroups and projects. | +| `prevent_sharing_groups_outside_hierarchy` | boolean | no | See [Prevent group sharing outside the group hierarchy](../user/group/index.md#prevent-group-sharing-outside-the-group-hierarchy). This attribute is only available on top-level groups. [Introduced in GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/333721) | NOTE: The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). @@ -910,6 +914,7 @@ Example response: "file_template_project_id": 1, "parent_id": null, "created_at": "2020-01-15T12:36:29.590Z", + "prevent_sharing_groups_outside_hierarchy": false, "projects": [ // Deprecated and will be removed in API v5 { "id": 9, @@ -954,6 +959,8 @@ Example response: } ``` +The `prevent_sharing_groups_outside_hierarchy` attribute is present in the response only for top-level groups. + ### Disable the results limit **(FREE SELF)** The 100 results limit can break integrations developed using GitLab 12.4 and earlier. @@ -1010,7 +1017,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | The response is `202 Accepted` if the user has authorization. @@ -1031,7 +1038,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | ## Search for group @@ -1067,7 +1074,7 @@ GET /groups/:id/hooks | Attribute | Type | Required | Description | | --------- | --------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | ### Get group hook @@ -1075,7 +1082,7 @@ Get a specific hook for a group. | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of a group hook | ```plaintext @@ -1115,7 +1122,7 @@ POST /groups/:id/hooks | Attribute | Type | Required | Description | | -----------------------------| -------------- | ---------| ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `url` | string | yes | The hook URL | | `push_events` | boolean | no | Trigger hook on push events | | `issues_events` | boolean | no | Trigger hook on issues events | @@ -1143,7 +1150,7 @@ PUT /groups/:id/hooks/:hook_id | Attribute | Type | Required | Description | | ---------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of the group hook | | `url` | string | yes | The hook URL | | `push_events` | boolean | no | Trigger hook on push events | @@ -1173,7 +1180,7 @@ DELETE /groups/:id/hooks/:hook_id | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of the group hook. | ## Group Audit Events **(PREMIUM)** @@ -1210,7 +1217,7 @@ GET /groups/:id/ldap_group_links | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | ### Add LDAP group link with CN or filter **(PREMIUM SELF)** @@ -1222,7 +1229,7 @@ POST /groups/:id/ldap_group_links | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `cn` | string | no | The CN of an LDAP group | | `filter` | string | no | The LDAP filter for the group | | `group_access` | integer | yes | Minimum [access level](members.md#valid-access-levels) for members of the LDAP group | @@ -1241,7 +1248,7 @@ DELETE /groups/:id/ldap_group_links/:cn | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `cn` | string | yes | The CN of an LDAP group | Deletes an LDAP group link for a specific LDAP provider. Deprecated. Scheduled for removal in a future release. @@ -1252,7 +1259,7 @@ DELETE /groups/:id/ldap_group_links/:provider/:cn | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `cn` | string | yes | The CN of an LDAP group | | `provider` | string | yes | LDAP provider for the LDAP group link | @@ -1266,7 +1273,7 @@ DELETE /groups/:id/ldap_group_links | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `cn` | string | no | The CN of an LDAP group | | `filter` | string | no | The LDAP filter for the group | | `provider` | string | yes | LDAP provider for the LDAP group link | @@ -1314,7 +1321,7 @@ POST /groups/:id/share | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `group_id` | integer | yes | The ID of the group to share with | | `group_access` | integer | yes | The [access level](members.md#valid-access-levels) to grant the group | | `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 | @@ -1329,7 +1336,7 @@ DELETE /groups/:id/share/:group_id | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `group_id` | integer | yes | The ID of the group to share with | ## Push Rules **(PREMIUM)** @@ -1348,7 +1355,7 @@ GET /groups/:id/push_rule | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the group or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID of the group or [URL-encoded path of the group](index.md#namespaced-path-encoding) | ```json { @@ -1391,15 +1398,15 @@ POST /groups/:id/push_rule | Attribute | Type | Required | Description | | --------------------------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `deny_delete_tag` | boolean | no | Deny deleting a tag | | `member_check` | boolean | no | Allows only GitLab users to author commits | | `prevent_secrets` | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | -| `commit_message_regex` | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | -| `commit_message_negative_regex` | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, e.g. `ssh\:\/\/` | -| `branch_name_regex` | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | -| `author_email_regex` | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | -| `file_name_regex` | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, e.g. `(jar|exe)$` | +| `commit_message_regex` | string | no | All commit messages must match the regular expression provided in this attribute, for example, `Fixed \d+\..*` | +| `commit_message_negative_regex` | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, for example, `ssh\:\/\/` | +| `branch_name_regex` | string | no | All branch names must match the regular expression provided in this attribute, for example, `(feature|hotfix)\/*` | +| `author_email_regex` | string | no | All commit author emails must match the regular expression provided in this attribute, for example, `@my-company.com$` | +| `file_name_regex` | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, for example, `(jar|exe)$` | | `max_file_size` | integer | no | Maximum file size (MB) allowed | | `commit_committer_check` | boolean | no | Only commits pushed using verified emails are allowed | | `reject_unsigned_commits` | boolean | no | Only commits signed through GPG are allowed | @@ -1438,15 +1445,15 @@ PUT /groups/:id/push_rule | Attribute | Type | Required | Description | | --------------------------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `deny_delete_tag` | boolean | no | Deny deleting a tag | | `member_check` | boolean | no | Restricts commits to be authored by existing GitLab users only | | `prevent_secrets` | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | -| `commit_message_regex` | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | -| `commit_message_negative_regex` | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, e.g. `ssh\:\/\/` | -| `branch_name_regex` | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | -| `author_email_regex` | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | -| `file_name_regex` | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, e.g. `(jar|exe)$` | +| `commit_message_regex` | string | no | All commit messages must match the regular expression provided in this attribute, for example, `Fixed \d+\..*` | +| `commit_message_negative_regex` | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, for example, `ssh\:\/\/` | +| `branch_name_regex` | string | no | All branch names must match the regular expression provided in this attribute, for example, `(feature|hotfix)\/*` | +| `author_email_regex` | string | no | All commit author emails must match the regular expression provided in this attribute, for example, `@my-company.com$` | +| `file_name_regex` | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, for example, `(jar|exe)$` | | `max_file_size` | integer | no | Maximum file size (MB) allowed | | `commit_committer_check` | boolean | no | Only commits pushed using verified emails are allowed | | `reject_unsigned_commits` | boolean | no | Only commits signed through GPG are allowed | @@ -1485,4 +1492,4 @@ DELETE /groups/:id/push_rule | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | diff --git a/doc/api/import.md b/doc/api/import.md index e1585d02ae3..d556c8af971 100644 --- a/doc/api/import.md +++ b/doc/api/import.md @@ -20,7 +20,7 @@ POST /import/github | `repo_id` | integer | yes | GitHub repository ID | | `new_name` | string | no | New repository name | | `target_namespace` | string | yes | Namespace to import repository into. Supports subgroups like `/namespace/subgroup`. | -| `github_hostname` | string | no | Custom GitHub enterprise hostname. Defaults to GitHub.com if `github_hostname` is not set. | +| `github_hostname` | string | no | Custom GitHub Enterprise hostname. Do not set for GitHub.com. | ```shell curl --request POST \ @@ -31,7 +31,8 @@ curl --request POST \ "personal_access_token": "aBc123abC12aBc123abC12abC123+_A/c123", "repo_id": "12345", "target_namespace": "group/subgroup", - "new_name": "NEW-NAME" + "new_name": "NEW-NAME", + "github_hostname": "https://github.example.com" }' ``` diff --git a/doc/api/index.md b/doc/api/index.md new file mode 100644 index 00000000000..f1059904ac3 --- /dev/null +++ b/doc/api/index.md @@ -0,0 +1,847 @@ +--- +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# API Docs **(FREE)** + +Use the GitLab APIs to automate GitLab. + +You can also use a partial [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/openapi/openapi.yaml), +to test the API directly from the GitLab user interface. +Contributions are welcome. + +## REST API + +A REST API is available in GitLab. +Usage instructions are below. +For a list of the available resources and their endpoints, see +[REST API resources](api_resources.md). + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an introduction and basic steps, see +[How to make GitLab API calls](https://www.youtube.com/watch?v=0LsMC3ZiXkA). + +## SCIM API **(PREMIUM SAAS)** + +GitLab provides an [SCIM API](scim.md) that both 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/`. + +## GraphQL API + +A [GraphQL API](graphql/index.md) is available in GitLab. + +With GraphQL, you can make an API request for only what you need, +and it's versioned by default. + +GraphQL co-exists with the current v4 REST API. If we have a v5 API, this should +be a compatibility layer on top of GraphQL. + +There were some patenting and licensing concerns with GraphQL. However, these +have been resolved to our satisfaction. The reference implementations +were re-licensed under MIT, and the OWF license used for the GraphQL specification. + +When GraphQL is fully implemented, GitLab: + +- Can delete controller-specific endpoints. +- Will no longer maintain two different APIs. + +## Compatibility guidelines + +The HTTP API is versioned with a single number, which is currently `4`. This number +symbolizes the major version number, as described by [SemVer](https://semver.org/). +Because of this, backward-incompatible changes require this version number to +change. + +The minor version isn't explicit, which allows for a stable API +endpoint. New features can be added to the API in the same +version number. + +New features and bug fixes are released in tandem with GitLab. Apart +from incidental patch and security releases, GitLab is released on the 22nd of each +month. Major API version changes, and removal of entire API versions, are done in tandem +with major GitLab releases. + +All deprecations and changes between versions are in the documentation. +For the changes between v3 and v4, see the [v3 to v4 documentation](v3_to_v4.md). + +### Current status + +Only API version v4 is available. Version v3 was removed in +[GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819). + +## How to use the API + +API requests must include both `api` and the API version. The API +version is defined in [`lib/api.rb`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/api/api.rb). +For example, the root of the v4 API is at `/api/v4`. + +### Valid API request + +If you have a GitLab instance at `gitlab.example.com`: + +```shell +curl "https://gitlab.example.com/api/v4/projects" +``` + +The API uses JSON to serialize data. You don't need to specify `.json` at the +end of the API URL. + +### API request to expose HTTP response headers + +If you want to expose HTTP response headers, use the `--include` option: + +```shell +curl --include "https://gitlab.example.com/api/v4/projects" +HTTP/2 200 +... +``` + +This request can help you investigate an unexpected response. + +### API request that includes the exit code + +If you want to expose the HTTP exit code, include the `--fail` option: + +```shell +curl --fail "https://gitlab.example.com/api/v4/does-not-exist" +curl: (22) The requested URL returned error: 404 +``` + +The HTTP exit code can help you diagnose the success or failure of your REST request. + +## Authentication + +Most API requests require authentication, or only return public data when +authentication isn't provided. When authentication is not required, the documentation +for each endpoint specifies this. For example, the +[`/projects/:id` endpoint](projects.md#get-single-project) does not require authentication. + +There are several ways you can authenticate with the GitLab API: + +- [OAuth2 tokens](#oauth2-tokens) +- [Personal access tokens](../user/profile/personal_access_tokens.md) +- [Project access tokens](../user/project/settings/project_access_tokens.md) +- [Session cookie](#session-cookie) +- [GitLab CI/CD job token](#gitlab-cicd-job-token) **(Specific endpoints only)** + +Project access tokens are supported by: + +- Self-managed GitLab Free and higher. +- GitLab SaaS Premium and higher. + +If you are an administrator, you or your application can authenticate as a specific user. +To do so, use: + +- [Impersonation tokens](#impersonation-tokens) +- [Sudo](#sudo) + +If authentication information is not valid or is missing, GitLab returns an error +message with a status code of `401`: + +```json +{ + "message": "401 Unauthorized" +} +``` + +### OAuth2 tokens + +You can use an [OAuth2 token](oauth2.md) to authenticate with the API by passing +it in either the `access_token` parameter or the `Authorization` header. + +Example of using the OAuth2 token in a parameter: + +```shell +curl "https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN" +``` + +Example of using the OAuth2 token in a header: + +```shell +curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/projects" +``` + +Read more about [GitLab as an OAuth2 provider](oauth2.md). + +### Personal/project access tokens + +You can use access tokens to authenticate with the API by passing it in either +the `private_token` parameter or the `PRIVATE-TOKEN` header. + +Example of using the personal or project access token in a parameter: + +```shell +curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>" +``` + +Example of using the personal or project access token in a header: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects" +``` + +You can also use personal or project access tokens with OAuth-compliant headers: + +```shell +curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects" +``` + +### Session cookie + +Signing in to the main GitLab application sets a `_gitlab_session` cookie. The +API uses this cookie for authentication if it's present. Using the API to +generate a new session cookie isn't supported. + +The primary user of this authentication method is the web frontend of GitLab +itself. The web frontend can use the API as the authenticated user to get a +list of projects without explicitly passing an access token. + +### GitLab CI/CD job token + +When a pipeline job is about to run, GitLab generates a unique token and injects it as the +[`CI_JOB_TOKEN` predefined variable](../ci/variables/predefined_variables.md). + +You can use a GitLab CI/CD job token to authenticate with specific API endpoints: + +- Packages: + - [Package Registry](../user/packages/package_registry/index.md). To push to the + Package Registry, you can use [deploy tokens](../user/project/deploy_tokens/index.md). + - [Container Registry](../user/packages/container_registry/index.md) + (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`). + - [Container Registry API](container_registry.md) (scoped to the job's project, when the `ci_job_token_scope` feature flag is enabled) +- [Get job artifacts](job_artifacts.md#get-job-artifacts). +- [Get job token's job](jobs.md#get-job-tokens-job). +- [Pipeline triggers](pipeline_triggers.md), using the `token=` parameter. +- [Release creation](releases/index.md#create-a-release). +- [Terraform plan](../user/infrastructure/index.md). + +The token has the same permissions to access the API as the user that triggers the +pipeline. Therefore, this user must be assigned to [a role that has the required privileges](../user/permissions.md). + +The token is valid only while the pipeline job runs. After the job finishes, you can't +use the token anymore. + +A job token can access a project's resources without any configuration, but it might +give extra permissions that aren't necessary. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) +to redesign the feature for more strategic control of the access permissions. + +#### GitLab CI/CD job token security + +To make sure that this token doesn't leak, GitLab: + +- Masks the job token in job logs. +- Grants permissions to the job token only when the job is running. + +To make sure that this token doesn't leak, you should also configure +your [runners](../ci/runners/README.md) to be secure. Avoid: + +- Using Docker's `privileged` mode if the machines are re-used. +- Using the [`shell` executor](https://docs.gitlab.com/runner/executors/shell.html) when jobs + run on the same machine. + +If you have an insecure GitLab Runner configuration, you increase the risk that someone +tries to steal tokens from other jobs. + +#### Limit GitLab CI/CD job token access + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.1. +> - [Deployed behind a feature flag](../user/feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-ci-job-token-scope-limit). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../user/feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +You can limit the access scope of a project's CI/CD job token to increase the +job token's security. A job token might give extra permissions that aren't necessary +to access specific resources. Limiting the job token access scope reduces the risk of a leaked +token being used to access private data that the user associated to the job can access. + +Control the job token access scope with an allowlist of other projects authorized +to be accessed by authenticating with the current project's job token. By default +the token scope only allows access to the same project where the token comes from. +Other projects can be added and removed by maintainers with access to both projects. + +This setting is enabled by default for all new projects, and disabled by default in projects +created before GitLab 14.1. It is strongly recommended that project maintainers enable this +setting at all times, and configure the allowlist for cross-project access if needed. + +For example, when the setting is enabled, jobs in a pipeline in project `A` have +a `CI_JOB_TOKEN` scope limited to project `A`. If the job needs to use the token +to make an API request to project `B`, then `B` must be added to the allowlist for `A`. + +To enable and configure the job token scope limit: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Token Access**. +1. Toggle **Limit CI_JOB_TOKEN access** to enabled. +1. (Optional) Add existing projects to the token's access scope. The user adding a + project must have the [maintainer role](../user/permissions.md) in both projects. + +If the job token scope limit is disabled, the token can potentially be used to authenticate +API requests to all projects accessible to the user that triggered the job. + +There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve +the feature with more strategic control of the access permissions. + +##### Enable or disable CI job token scope limit **(FREE SELF)** + +The GitLab CI/CD job token access scope limit is under development and not ready for production +use. It is deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:ci_scoped_job_token) +``` + +To disable it: + +```ruby +Feature.disable(:ci_scoped_job_token) +``` + +### Impersonation tokens + +Impersonation tokens are a type of [personal access token](../user/profile/personal_access_tokens.md). +They can be created only by an administrator, and are used to authenticate with the +API as a specific user. + +Use impersonation tokens an alternative to: + +- The user's password or one of their personal access tokens. +- The [Sudo](#sudo) feature. The user's or administrator's password or token + may not be known, or may change over time. + +For more information, see the [users API](users.md#create-an-impersonation-token) +documentation. + +Impersonation tokens are used exactly like regular personal access tokens, and +can be passed in either the `private_token` parameter or the `PRIVATE-TOKEN` +header. + +#### Disable impersonation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/40385) in GitLab 11.6. + +By default, impersonation is enabled. To disable impersonation: + +**For Omnibus installations** + +1. Edit the `/etc/gitlab/gitlab.rb` file: + + ```ruby + gitlab_rails['impersonation_enabled'] = false + ``` + +1. Save the file, and then [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab for the changes to take effect. + +To re-enable impersonation, remove this configuration, and then reconfigure +GitLab. + +**For installations from source** + +1. Edit the `config/gitlab.yml` file: + + ```yaml + gitlab: + impersonation_enabled: false + ``` + +1. Save the file, and then [restart](../administration/restart_gitlab.md#installations-from-source) + GitLab for the changes to take effect. + +To re-enable impersonation, remove this configuration, and then restart GitLab. + +### Sudo + +All API requests support performing an API request as if you were another user, +provided you're authenticated as an administrator with an OAuth or personal +access token that has the `sudo` scope. The API requests are executed with the +permissions of the impersonated user. + +As an [administrator](../user/permissions.md), pass the `sudo` parameter either +by using query string or a header with an ID or username (case insensitive) of +the user you want to perform the operation as. If passed as a header, the header +name must be `Sudo`. + +If a non administrative access token is provided, GitLab returns an error +message with a status code of `403`: + +```json +{ + "message": "403 Forbidden - Must be admin to use sudo" +} +``` + +If an access token without the `sudo` scope is provided, an error message is +be returned with a status code of `403`: + +```json +{ + "error": "insufficient_scope", + "error_description": "The request requires higher privileges than provided by the access token.", + "scope": "sudo" +} +``` + +If the sudo user ID or username cannot be found, an error message is +returned with a status code of `404`: + +```json +{ + "message": "404 User with ID or username '123' Not Found" +} +``` + +Example of a valid API request and a request using cURL with sudo request, +providing a username: + +```plaintext +GET /projects?private_token=<your_access_token>&sudo=username +``` + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects" +``` + +Example of a valid API request and a request using cURL with sudo request, +providing an ID: + +```plaintext +GET /projects?private_token=<your_access_token>&sudo=23 +``` + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects" +``` + +## Status codes + +The API is designed to return different status codes according to context and +action. This way, if a request results in an error, you can get +insight into what went wrong. + +The following table gives an overview of how the API functions generally behave. + +| Request type | Description | +|---------------|-------------| +| `GET` | Access one or more resources and return the result as JSON. | +| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. | +| `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. | +| `DELETE` | Returns `204 No Content` if the resource was deleted successfully. | + +The following table shows the possible return codes for API requests. + +| Return values | Description | +|--------------------------|-------------| +| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, and the resource(s) itself is returned as JSON. | +| `204 No Content` | The server has successfully fulfilled the request, and there is no additional content to send in the response payload body. | +| `201 Created` | The `POST` request was successful, and the resource is returned as JSON. | +| `304 Not Modified` | The resource hasn't been modified since the last request. | +| `400 Bad Request` | A required attribute of the API request is missing. For example, the title of an issue is not given. | +| `401 Unauthorized` | The user isn't authenticated. A valid [user token](#authentication) is necessary. | +| `403 Forbidden` | The request isn't allowed. For example, the user isn't allowed to delete a project. | +| `404 Not Found` | A resource couldn't be accessed. For example, an ID for a resource couldn't be found. | +| `405 Method Not Allowed` | The request isn't supported. | +| `409 Conflict` | A conflicting resource already exists. For example, creating a project with a name that already exists. | +| `412` | The request was denied. This can happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. | +| `422 Unprocessable` | The entity couldn't be processed. | +| `429 Too Many Requests` | The user exceeded the [application rate limits](../administration/instance_limits.md#rate-limits). | +| `500 Server Error` | While handling the request, something went wrong on the server. | + +## Pagination + +GitLab supports the following pagination methods: + +- Offset-based pagination. This is the default method and is available on all endpoints. +- Keyset-based pagination. Added to selected endpoints but being + [progressively rolled out](https://gitlab.com/groups/gitlab-org/-/epics/2039). + +For large collections, for performance reasons we recommend keyset pagination +(when available) instead of offset pagination. + +### Offset-based pagination + +Sometimes, the returned result spans many pages. When listing resources, you can +pass the following parameters: + +| Parameter | Description | +|------------|-------------| +| `page` | Page number (default: `1`). | +| `per_page` | Number of items to list per page (default: `20`, max: `100`). | + +In the following example, we list 50 [namespaces](namespaces.md) per page: + +```shell +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces?per_page=50" +``` + +#### Pagination `Link` header + +[`Link` headers](https://www.w3.org/wiki/LinkHeader) are returned with each +response. They have `rel` set to `prev`, `next`, `first`, or `last` and contain +the relevant URL. Be sure to use these links instead of generating your own URLs. + +For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers). + +In the following cURL example, we limit the output to three items per page +(`per_page=3`) and we request the second page (`page=2`) of [comments](notes.md) +of the issue with ID `8` which belongs to the project with ID `9`: + +```shell +curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2" +``` + +The response is: + +```http +HTTP/2 200 OK +cache-control: no-cache +content-length: 1103 +content-type: application/json +date: Mon, 18 Jan 2016 09:43:18 GMT +link: <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="last" +status: 200 OK +vary: Origin +x-next-page: 3 +x-page: 2 +x-per-page: 3 +x-prev-page: 1 +x-request-id: 732ad4ee-9870-4866-a199-a9db0cde3c86 +x-runtime: 0.108688 +x-total: 8 +x-total-pages: 3 +``` + +#### Other pagination headers + +GitLab also returns the following additional pagination headers: + +| Header | Description | +|-----------------|-------------| +| `x-next-page` | The index of the next page. | +| `x-page` | The index of the current page (starting at 1). | +| `x-per-page` | The number of items per page. | +| `X-prev-page` | The index of the previous page. | +| `x-total` | The total number of items. | +| `x-total-pages` | The total number of pages. | + +For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers). + +### Keyset-based pagination + +Keyset-pagination allows for more efficient retrieval of pages and - in contrast +to offset-based pagination - runtime is independent of the size of the +collection. + +This method is controlled by the following parameters: + +| Parameter | Description | +|--------------| ------------| +| `pagination` | `keyset` (to enable keyset pagination). | +| `per_page` | Number of items to list per page (default: `20`, max: `100`). | + +In the following example, we list 50 [projects](projects.md) per page, ordered +by `id` ascending. + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc" +``` + +The response header includes a link to the next page. For example: + +```http +HTTP/1.1 200 OK +... +Links: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next" +Link: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next" +Status: 200 OK +... +``` + +WARNING: +The `Links` header is scheduled to be removed in GitLab 14.0 to be aligned with the +[W3C `Link` specification](https://www.w3.org/wiki/LinkHeader). The `Link` +header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714) +and should be used instead. + +The link to the next page contains an additional filter `id_after=42` that +excludes already-retrieved records. The type of filter depends on the +`order_by` option used, and we may have more than one additional filter. + +When the end of the collection is reached and there are no additional +records to retrieve, the `Link` header is absent and the resulting array is +empty. + +We recommend using only the given link to retrieve the next page instead of +building your own URL. Apart from the headers shown, we don't expose additional +pagination headers. + +Keyset-based pagination is supported only for selected resources and ordering +options: + +| Resource | Order | +|-------------------------|-------| +| [Projects](projects.md) | `order_by=id` only. | + +## Path parameters + +If an endpoint has path parameters, the documentation displays them with a +preceding colon. + +For example: + +```plaintext +DELETE /projects/:id/share/:group_id +``` + +The `:id` path parameter needs to be replaced with the project ID, and the +`:group_id` needs to be replaced with the ID of the group. The colons `:` +shouldn't be included. + +The resulting cURL request for a project with ID `5` and a group ID of `17` is then: + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17" +``` + +Path parameters that are required to be URL-encoded must be followed. If not, +it doesn't match an API endpoint and responds with a 404. If there's +something in front of the API (for example, Apache), ensure that it doesn't decode +the URL-encoded path parameters. + +## Namespaced path encoding + +If using namespaced API requests, make sure that the `NAMESPACE/PROJECT_PATH` is +URL-encoded. + +For example, `/` is represented by `%2F`: + +```plaintext +GET /api/v4/projects/diaspora%2Fdiaspora +``` + +A project's _path_ isn't necessarily the same as its _name_. A project's path is +found in the project's URL or in the project's settings, under +**General > Advanced > Change path**. + +## File path, branches, and tags name encoding + +If a file path, branch or tag contains a `/`, make sure it is URL-encoded. + +For example, `/` is represented by `%2F`: + +```plaintext +GET /api/v4/projects/1/repository/files/src%2FREADME.md?ref=master +GET /api/v4/projects/1/branches/my%2Fbranch/commits +GET /api/v4/projects/1/repository/tags/my%2Ftag +``` + +## Request Payload + +API Requests can use parameters sent as [query strings](https://en.wikipedia.org/wiki/Query_string) +or as a [payload body](https://tools.ietf.org/html/draft-ietf-httpbis-p3-payload-14#section-3.2). +GET requests usually send a query string, while PUT or POST requests usually +send the payload body: + +- Query string: + + ```shell + curl --request POST "https://gitlab/api/v4/projects?name=<example-name>&description=<example-description>" + ``` + +- Request payload (JSON): + + ```shell + curl --request POST --header "Content-Type: application/json" \ + --data '{"name":"<example-name>", "description":"<example-description"}' "https://gitlab/api/v4/projects" + ``` + +URL encoded query strings have a length limitation. Requests that are too large +result in a `414 Request-URI Too Large` error message. This can be resolved by +using a payload body instead. + +## Encoding API parameters of `array` and `hash` types + +You can request the API with `array` and `hash` types parameters: + +### `array` + +`import_sources` is a parameter of type `array`: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +-d "import_sources[]=github" \ +-d "import_sources[]=bitbucket" \ +"https://gitlab.example.com/api/v4/some_endpoint" +``` + +### `hash` + +`override_params` is a parameter of type `hash`: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +--form "namespace=email" \ +--form "path=impapi" \ +--form "file=@/path/to/somefile.txt" +--form "override_params[visibility]=private" \ +--form "override_params[some_other_param]=some_value" \ +"https://gitlab.example.com/api/v4/projects/import" +``` + +### Array of hashes + +`variables` is a parameter of type `array` containing hash key/value pairs +`[{ 'key': 'UPLOAD_TO_S3', 'value': 'true' }]`: + +```shell +curl --globoff --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +"https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[][key]=VAR1&variables[][value]=hello&variables[][key]=VAR2&variables[][value]=world" + +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +--header "Content-Type: application/json" \ +--data '{ "ref": "master", "variables": [ {"key": "VAR1", "value": "hello"}, {"key": "VAR2", "value": "world"} ] }' \ +"https://gitlab.example.com/api/v4/projects/169/pipeline" +``` + +## `id` vs `iid` + +Some resources have two similarly-named fields. For example, [issues](issues.md), +[merge requests](merge_requests.md), and [project milestones](merge_requests.md). +The fields are: + +- `id`: ID that is unique across all projects. +- `iid`: Additional, internal ID (displayed in the web UI) that's unique in the + scope of a single project. + +If a resource has both the `iid` field and the `id` field, the `iid` field is +usually used instead of `id` to fetch the resource. + +For example, suppose a project with `id: 42` has an issue with `id: 46` and +`iid: 5`. In this case: + +- A valid API request to retrieve the issue is `GET /projects/42/issues/5`. +- An invalid API request to retrieve the issue is `GET /projects/42/issues/46`. + +Not all resources with the `iid` field are fetched by `iid`. For guidance +regarding which field to use, see the documentation for the specific resource. + +## Data validation and error reporting + +When working with the API you may encounter validation errors, in which case +the API returns an HTTP `400` error. + +Such errors appear in the following cases: + +- A required attribute of the API request is missing (for example, the title of + an issue isn't given). +- An attribute did not pass the validation (for example, the user bio is too + long). + +When an attribute is missing, you receive something like: + +```http +HTTP/1.1 400 Bad Request +Content-Type: application/json +{ + "message":"400 (Bad request) \"title\" not given" +} +``` + +When a validation error occurs, error messages are different. They hold +all details of validation errors: + +```http +HTTP/1.1 400 Bad Request +Content-Type: application/json +{ + "message": { + "bio": [ + "is too long (maximum is 255 characters)" + ] + } +} +``` + +This makes error messages more machine-readable. The format can be described as +follows: + +```json +{ + "message": { + "<property-name>": [ + "<error-message>", + "<error-message>", + ... + ], + "<embed-entity>": { + "<property-name>": [ + "<error-message>", + "<error-message>", + ... + ], + } + } +} +``` + +## Unknown route + +When you attempt to access an API URL that doesn't exist, you receive a +404 Not Found message. + +```http +HTTP/1.1 404 Not Found +Content-Type: application/json +{ + "error": "404 Not Found" +} +``` + +## Encoding `+` in ISO 8601 dates + +If you need to include a `+` in a query parameter, you may need to use `%2B` +instead, due to a [W3 recommendation](http://www.w3.org/Addressing/URL/4_URI_Recommentations.html) +that causes a `+` to be interpreted as a space. For example, in an ISO 8601 date, +you may want to include a specific time in ISO 8601 format, such as: + +```plaintext +2017-10-17T23:11:13.000+05:30 +``` + +The correct encoding for the query parameter would be: + +```plaintext +2017-10-17T23:11:13.000%2B05:30 +``` + +## Clients + +There are many unofficial GitLab API Clients for most of the popular programming +languages. For a complete list, visit the [GitLab website](https://about.gitlab.com/partners/technology-partners/#api-clients). + +## Rate limits + +For administrator documentation on rate limit settings, see +[Rate limits](../security/rate_limits.md). To find the settings that are +specifically used by GitLab.com, see +[GitLab.com-specific rate limits](../user/gitlab_com/index.md#gitlabcom-specific-rate-limits). + +## Content type + +The GitLab API supports the `application/json` content type by default, though +some API endpoints also support `text/plain`. + +In [GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/250342), +API endpoints do not support `text/plain` by default, unless it's explicitly documented. diff --git a/doc/api/instance_clusters.md b/doc/api/instance_clusters.md index 1c4996975f7..ae94fdb137c 100644 --- a/doc/api/instance_clusters.md +++ b/doc/api/instance_clusters.md @@ -160,7 +160,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------------------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- | | `name` | string | yes | The name of the cluster | -| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | +| `domain` | string | no | The [base domain](../user/project/clusters/gitlab_managed_clusters.md#base-domain) of the cluster | | `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` | | `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | | `enabled` | boolean | no | Determines if cluster is active or not, defaults to `true` | @@ -228,7 +228,7 @@ Parameters: | ------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------ | | `cluster_id` | integer | yes | The ID of the cluster | | `name` | string | no | The name of the cluster | -| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | +| `domain` | string | no | The [base domain](../user/project/clusters/gitlab_managed_clusters.md#base-domain) of the cluster | | `environment_scope` | string | no | The associated environment to the cluster | | `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | | `enabled` | boolean | no | Determines if cluster is active or not | diff --git a/doc/api/invitations.md b/doc/api/invitations.md index 36ff2d5bda4..c79295912fa 100644 --- a/doc/api/invitations.md +++ b/doc/api/invitations.md @@ -37,7 +37,7 @@ POST /projects/:id/invitations | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | | `email` | string | yes | The email of the new member or multiple emails separated by commas | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format YEAR-MONTH-DAY | @@ -84,7 +84,7 @@ GET /projects/:id/invitations | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | | `page` | integer | no | Page to retrieve | | `per_page`| integer | no | Number of member invitations to return per page | | `query` | string | no | A query string to search for invited members by invite email. Query text must match email address exactly. When empty, returns all invitations. | @@ -121,9 +121,9 @@ PUT /projects/:id/invitations/:email | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user. | | `email` | string | yes | The email address to which the invitation was previously sent. | -| `access_level` | integer | no | A valid access level (defaults: `30`, developer access level). | +| `access_level` | integer | no | A valid access level (defaults: `30`, the Developer role). | | `expires_at` | string | no | A date string in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`). | ```shell @@ -151,7 +151,7 @@ DELETE /projects/:id/invitations/:email | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | | `email` | string | yes | The email address to which the invitation was previously sent | ```shell diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index 4dfa9b2f532..d4f59d10316 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.md @@ -22,7 +22,7 @@ Parameters: | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```json @@ -74,9 +74,9 @@ POST /projects/:id/issues/:issue_iid/links | Attribute | Type | Required | Description | |---------------------|----------------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | -| `target_project_id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) of a target project | +| `target_project_id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) of a target project | | `target_issue_iid` | integer/string | yes | The internal ID of a target project's issue | | `link_type` | string | no | The type of the relation ("relates_to", "blocks", "is_blocked_by"), defaults to "relates_to"). | @@ -162,7 +162,7 @@ DELETE /projects/:id/issues/:issue_iid/links/:issue_link_id | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `issue_link_id` | integer/string | yes | The ID of an issue relationship | | `link_type` | string | no | The type of the relation (`relates_to`, `blocks`, `is_blocked_by`), defaults to `relates_to` | diff --git a/doc/api/issues.md b/doc/api/issues.md index f321c00e7f2..6de8912c1af 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -4,7 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issues API +# Issues API **(FREE)** + +Interact with [GitLab Issues](../user/project/issues/index.md) using the REST API. If a user is not a member of a private project, a `GET` request on that project results in a `404` status code. @@ -14,7 +16,7 @@ request on that project results in a `404` status code. By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](README.md#pagination). +Read more on [pagination](index.md#pagination). WARNING: The `reference` attribute in responses is deprecated in favor of `references`. @@ -266,7 +268,7 @@ GET /groups/:id/issues?state=opened | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _(Introduced in [GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/260375))_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | @@ -470,7 +472,7 @@ GET /projects/:id/issues?state=opened | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _(Introduced in [GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/260375))_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | @@ -822,7 +824,7 @@ GET /projects/:id/issues/:issue_iid | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -990,7 +992,7 @@ POST /projects/:id/issues | `due_date` | string | no | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11` | | `epic_id` **(PREMIUM)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | | `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157)) | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `iid` | integer/string | no | The internal ID of the project's issue (requires administrator or project owner rights) | | `issue_type` | string | no | The type of issue. One of `issue`, `incident`, or `test_case`. Default is `issue`. | | `labels` | string | no | Comma-separated label names for an issue | @@ -1160,7 +1162,7 @@ PUT /projects/:id/issues/:issue_iid | `due_date` | string | no | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11` | | `epic_id` **(PREMIUM)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | | `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157)) | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `issue_type` | string | no | Updates the type of issue. One of `issue`, `incident`, or `test_case`. | | `labels` | string | no | Comma-separated label names for an issue. Set to an empty string to unassign all labels. | @@ -1307,7 +1309,7 @@ DELETE /projects/:id/issues/:issue_iid | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1326,7 +1328,7 @@ PUT /projects/:id/issues/:issue_iid/reorder | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of the project's issue | | `move_after_id` | integer | no | The ID of a project's issue that should be placed after this issue | | `move_before_id` | integer | no | The ID of a project's issue that should be placed before this issue | @@ -1350,7 +1352,7 @@ POST /projects/:id/issues/:issue_iid/move | Attribute | Type | Required | Description | |-----------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `to_project_id` | integer | yes | The ID of the new project | @@ -1496,7 +1498,7 @@ POST /projects/:id/issues/:issue_iid/subscribe | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1641,7 +1643,7 @@ POST /projects/:id/issues/:issue_iid/unsubscribe | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1714,7 +1716,7 @@ POST /projects/:id/issues/:issue_iid/todo | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1838,7 +1840,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :---------- | :------------- | :------- | :---------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `body` | String | yes | The content of a note. Must contain `/promote` at the start of a new line. | @@ -1889,7 +1891,7 @@ POST /projects/:id/issues/:issue_iid/time_estimate | Attribute | Type | Required | Description | |-------------|---------|----------|------------------------------------------| | `duration` | string | yes | The duration in human format. e.g: 3h30m | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1917,7 +1919,7 @@ POST /projects/:id/issues/:issue_iid/reset_time_estimate | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1946,7 +1948,7 @@ POST /projects/:id/issues/:issue_iid/add_spent_time | Attribute | Type | Required | Description | |-------------|---------|----------|------------------------------------------| | `duration` | string | yes | The duration in human format. e.g: 3h30m | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1974,7 +1976,7 @@ POST /projects/:id/issues/:issue_iid/reset_spent_time | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2003,7 +2005,7 @@ GET /projects/:id/issues/:issue_iid/time_stats | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2034,7 +2036,7 @@ GET /projects/:id/issues/:issue_iid/related_merge_requests | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2194,7 +2196,7 @@ GET /projects/:id/issues/:issue_iid/closed_by | Attribute | Type | Required | Description | | ----------- | ---------------| -------- | ---------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project issue | ```shell @@ -2271,7 +2273,7 @@ GET /projects/:id/issues/:issue_iid/participants | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2315,7 +2317,7 @@ GET /projects/:id/issues/:issue_iid/user_agent_detail | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2347,7 +2349,7 @@ POST /projects/:id/issues/:issue_iid/metric_images | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `file` | file | yes | The image file to be uploaded | | `url` | string | no | The URL to view more metric information | @@ -2379,7 +2381,7 @@ GET /projects/:id/issues/:issue_iid/metric_images | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2417,7 +2419,7 @@ DELETE /projects/:id/issues/:issue_iid/metric_images/:image_id | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `image_id` | integer | yes | The ID of the image | diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md index de5f26141f5..a760424f6a2 100644 --- a/doc/api/issues_statistics.md +++ b/doc/api/issues_statistics.md @@ -4,9 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issues Statistics API +# Issues statistics API **(FREE)** -Every API call to issues_statistics must be authenticated. +Every API call to the [issues](../user/project/issues/index.md) statistics API must be authenticated. If a user is not a member of a project and the project is private, a `GET` request on that project results in a `404` status code. @@ -90,7 +90,7 @@ GET /groups/:id/issues_statistics?confidential=true | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | @@ -146,7 +146,7 @@ GET /projects/:id/issues_statistics?confidential=true | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the milestone having the given `iid` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | diff --git a/doc/api/iterations.md b/doc/api/iterations.md index be52ef0ea47..c39c397f27e 100644 --- a/doc/api/iterations.md +++ b/doc/api/iterations.md @@ -28,7 +28,7 @@ GET /projects/:id/iterations?search=version | Attribute | Type | Required | Description | | ------------------- | ------- | -------- | ----------- | -| `state` | string | no | Return only `opened`, `upcoming`, `started`, `closed`, or `all` iterations. Defaults to `all`. | +| `state` | string | no | 'Return `opened`, `upcoming`, `current (previously started)`, `closed`, or `all` iterations. Filtering by `started` state is deprecated starting with 14.1, please use `current` instead.' | | `search` | string | no | Return only iterations with a title matching the provided string. | | `include_ancestors` | boolean | no | Include iterations from parent group and its ancestors. Defaults to `true`. | diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index 54404559577..5e2312891ef 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -18,9 +18,9 @@ GET /projects/:id/jobs/:job_id/artifacts | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: @@ -28,7 +28,7 @@ Example request using the `PRIVATE-TOKEN` header: 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 +To use this in a [`script` definition](../ci/yaml/index.md#script) inside `.gitlab-ci.yml` **(PREMIUM)**, you can use either: - The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable. @@ -70,7 +70,7 @@ is the same as [getting the job's artifacts](#get-job-artifacts), but by defining the job's name instead of its ID. NOTE: -If a pipeline is [parent of other child pipelines](../ci/parent_child_pipelines.md), artifacts +If a pipeline is [parent of other child pipelines](../ci/pipelines/parent_child_pipelines.md), artifacts are searched in hierarchical order from parent to child. For example, if both parent and child pipelines have a job with the same name, the artifact from the parent pipeline is returned. @@ -82,10 +82,10 @@ Parameters | 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](index.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. | | `job` | string | yes | The name of the job. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: @@ -93,7 +93,7 @@ Example request using the `PRIVATE-TOKEN` header: curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test" ``` -To use this in a [`script` definition](../ci/yaml/README.md#script) inside +To use this in a [`script` definition](../ci/yaml/index.md#script) inside `.gitlab-ci.yml` **(PREMIUM)**, you can use either: - The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable. @@ -143,10 +143,10 @@ Parameters | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | The unique job identifier. | | `artifact_path` | string | yes | Path to a file inside the artifacts archive. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request: @@ -172,7 +172,7 @@ pipeline for the given reference name from inside the job's artifacts archive. The file is extracted from the archive and streamed to the client. In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201784) and later, artifacts -for [parent and child pipelines](../ci/parent_child_pipelines.md) are searched in hierarchical +for [parent and child pipelines](../ci/pipelines/parent_child_pipelines.md) are searched in hierarchical order from parent to child. For example, if both parent and child pipelines have a job with the same name, the artifact from the parent pipeline is returned. @@ -184,11 +184,11 @@ Parameters: | 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](index.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. | | `artifact_path` | string | yes | Path to a file inside the artifacts archive. | | `job` | string | yes | The name of the job. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request: @@ -216,7 +216,7 @@ Parameters | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | Example request: @@ -270,7 +270,7 @@ DELETE /projects/:id/jobs/:job_id/artifacts | Attribute | Type | Required | Description | |-----------|----------------|----------|-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `job_id` | integer | yes | ID of a job. | Example request: diff --git a/doc/api/jobs.md b/doc/api/jobs.md index b92f2a72c03..42774b80b27 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -16,7 +16,7 @@ GET /projects/:id/jobs | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `scope` | string **or** array of strings | no | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | ```shell @@ -159,7 +159,7 @@ GET /projects/:id/pipelines/:pipeline_id/jobs | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `pipeline_id` | integer | yes | ID of a pipeline. Can also be obtained in CI jobs via the [predefined CI variable](../ci/variables/predefined_variables.md) `CI_PIPELINE_ID`. | | `scope` | string **or** array of strings | no | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | | `include_retried` | boolean | no | Include retried jobs in the response. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/272627) in GitLab 13.9. | @@ -295,7 +295,7 @@ Example of response ``` In GitLab 13.3 and later, this endpoint [returns data for any pipeline](pipelines.md#single-pipeline-requests) -including [child pipelines](../ci/parent_child_pipelines.md). +including [child pipelines](../ci/pipelines/parent_child_pipelines.md). In GitLab 13.5 and later, this endpoint does not return retried jobs in the response by default. Additionally, jobs are sorted by ID in descending order (newest first). @@ -314,7 +314,7 @@ GET /projects/:id/pipelines/:pipeline_id/bridges | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `pipeline_id` | integer | yes | ID of a pipeline. | | `scope` | string **or** array of strings | no | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | @@ -554,7 +554,7 @@ GET /projects/:id/jobs/:job_id | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | ```shell @@ -631,7 +631,7 @@ GET /projects/:id/jobs/:job_id/trace | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | ```shell @@ -655,7 +655,7 @@ POST /projects/:id/jobs/:job_id/cancel | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | ```shell @@ -705,7 +705,7 @@ POST /projects/:id/jobs/:job_id/retry | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | ```shell @@ -757,7 +757,7 @@ Parameters | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | Example of request @@ -810,7 +810,7 @@ POST /projects/:id/jobs/:job_id/play | 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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | ```shell diff --git a/doc/api/labels.md b/doc/api/labels.md index 5abab7a79c4..1606df03afb 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -4,7 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Labels API +# Labels API **(FREE)** + +Interact with [labels](../user/project/labels.md) using the REST API. NOTE: The `description_html` - was added to response JSON in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413). @@ -13,7 +15,7 @@ The `description_html` - was added to response JSON in [GitLab 12.7](https://git Get all labels for a given project. -By default, this request returns 20 results at a time because the API results [are paginated](README.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). ```plaintext GET /projects/:id/labels @@ -21,7 +23,7 @@ GET /projects/:id/labels | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced in GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543))_ | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | | `search` | string | no | Keyword to filter labels by. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | @@ -117,7 +119,7 @@ GET /projects/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label. | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | @@ -154,9 +156,9 @@ POST /projects/:id/labels | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the label | -| `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | +| `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The description of the label | | `priority` | integer | no | The priority of the label. Must be greater or equal than zero or `null` to remove the priority. | @@ -193,7 +195,7 @@ DELETE /projects/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -214,10 +216,10 @@ PUT /projects/:id/labels/:label_id | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | | `new_name` | string | yes if `color` is not provided | The new name of the label | -| `color` | string | yes if `new_name` is not provided | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | +| `color` | string | yes if `new_name` is not provided | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The new description of the label | | `priority` | integer | no | The new priority of the label. Must be greater or equal than zero or `null` to remove the priority. | @@ -263,7 +265,7 @@ PUT /projects/:id/labels/:label_id/promote | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -301,7 +303,7 @@ POST /projects/:id/labels/:label_id/subscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label | ```shell @@ -339,7 +341,7 @@ POST /projects/:id/labels/:label_id/unsubscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label | ```shell diff --git a/doc/api/lint.md b/doc/api/lint.md index 57d11d15adc..a47bb028248 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -87,8 +87,8 @@ Example responses: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29568) in GitLab 13.5. The CI lint returns an expanded version of the configuration. The expansion does not -work for CI configuration added with [`include: local`](../ci/yaml/README.md#includelocal), -or with [`extends:`](../ci/yaml/README.md#extends). +work for CI configuration added with [`include: local`](../ci/yaml/index.md#includelocal), +or with [`extends:`](../ci/yaml/index.md#extends). Example contents of a `.gitlab-ci.yml` passed to the CI Lint API with `include_merged_yaml` set as true: diff --git a/doc/api/managed_licenses.md b/doc/api/managed_licenses.md index 4be4f83b4ce..3967fe52a03 100644 --- a/doc/api/managed_licenses.md +++ b/doc/api/managed_licenses.md @@ -16,7 +16,7 @@ GET /projects/:id/managed_licenses | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/managed_licenses" @@ -49,7 +49,7 @@ GET /projects/:id/managed_licenses/:managed_license_id | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `managed_license_id` | integer/string | yes | The ID or URL-encoded name of the license belonging to the project | ```shell @@ -76,7 +76,7 @@ POST /projects/:id/managed_licenses | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the managed license | | `approval_status` | string | yes | The approval status. "approved" or "blacklisted" | @@ -104,7 +104,7 @@ DELETE /projects/:id/managed_licenses/:managed_license_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `managed_license_id` | integer/string | yes | The ID or URL-encoded name of the license belonging to the project | ```shell @@ -123,7 +123,7 @@ PATCH /projects/:id/managed_licenses/:managed_license_id | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `managed_license_id` | integer/string | yes | The ID or URL-encoded name of the license belonging to the project | | `approval_status` | string | yes | The approval status. "approved" or "blacklisted" | diff --git a/doc/api/markdown.md b/doc/api/markdown.md index 157714c2791..d83b7420829 100644 --- a/doc/api/markdown.md +++ b/doc/api/markdown.md @@ -14,14 +14,14 @@ Available only in APIv4. ## Render an arbitrary Markdown document ```plaintext -POST /api/v4/markdown +POST /markdown ``` | Attribute | Type | Required | Description | | --------- | ------- | ------------- | ------------------------------------------ | | `text` | string | yes | The Markdown text to render | | `gfm` | boolean | no | Render text using GitLab Flavored Markdown. Default is `false` | -| `project` | string | no | Use `project` as a context when creating references using GitLab Flavored Markdown. [Authentication](README.md#authentication) is required if a project is not public. | +| `project` | string | no | Use `project` as a context when creating references using GitLab Flavored Markdown. [Authentication](index.md#authentication) is required if a project is not public. | ```shell curl --header Content-Type:application/json --data '{"text":"Hello world! :tada:", "gfm":true, "project":"group_example/project_example"}' "https://gitlab.example.com/api/v4/markdown" diff --git a/doc/api/members.md b/doc/api/members.md index 627c9a12b5e..560fc8262c0 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -43,7 +43,7 @@ GET /projects/:id/members | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | | `query` | string | no | A query string to search for members | | `user_ids` | array of integers | no | Filter the results on the given user IDs | @@ -104,7 +104,7 @@ GET /projects/:id/members/all | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | | `query` | string | no | A query string to search for members | | `user_ids` | array of integers | no | Filter the results on the given user IDs | @@ -169,7 +169,7 @@ GET /projects/:id/members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell @@ -208,7 +208,7 @@ GET /projects/:id/members/all/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell @@ -244,7 +244,7 @@ This API endpoint works on top-level groups only. It does not work on subgroups. NOTE: Unlike other API endpoints, billable members is updated once per day at 12:00 UTC. -This function takes [pagination](README.md#pagination) parameters `page` and `per_page` to restrict the list of users. +This function takes [pagination](index.md#pagination) parameters `page` and `per_page` to restrict the list of users. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/262875) in GitLab 13.7, the `search` and `sort` parameters allow you to search for billable group members by name and sort the results, @@ -256,22 +256,24 @@ GET /groups/:id/billable_members | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `search` | string | no | A query string to search for group members by name, username, or email. | | `sort` | string | no | A query string containing parameters that specify the sort attribute and order. See supported values below.| The supported values for the `sort` attribute are: -| Value | Description | -| ------------------- | ------------------------ | -| `access_level_asc` | Access level, ascending | -| `access_level_desc` | Access level, descending | -| `last_joined` | Last joined | -| `name_asc` | Name, ascending | -| `name_desc` | Name, descending | -| `oldest_joined` | Oldest joined | -| `oldest_sign_in` | Oldest sign in | -| `recent_sign_in` | Recent sign in | +| Value | Description | +| ----------------------- | ---------------------------- | +| `access_level_asc` | Access level, ascending | +| `access_level_desc` | Access level, descending | +| `last_joined` | Last joined | +| `name_asc` | Name, ascending | +| `name_desc` | Name, descending | +| `oldest_joined` | Oldest joined | +| `oldest_sign_in` | Oldest sign in | +| `recent_sign_in` | Recent sign in | +| `last_activity_on_asc` | Last active date, ascending | +| `last_activity_on_desc` | Last active date, descending | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/billable_members" @@ -333,7 +335,7 @@ This API endpoint works on top-level groups only. It does not work on subgroups. This API endpoint requires permission to admin memberships for the group. -This API endpoint takes [pagination](README.md#pagination) parameters `page` and `per_page` to restrict the list of memberships. +This API endpoint takes [pagination](index.md#pagination) parameters `page` and `per_page` to restrict the list of memberships. ```plaintext GET /groups/:id/billable_members/:user_id/memberships @@ -341,7 +343,7 @@ GET /groups/:id/billable_members/:user_id/memberships | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the billable member | ```shell @@ -393,7 +395,7 @@ DELETE /groups/:id/billable_members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell @@ -411,7 +413,7 @@ POST /projects/:id/members | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer/string | yes | The user ID of the new member or multiple IDs separated by commas | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format `YEAR-MONTH-DAY` | @@ -452,7 +454,7 @@ PUT /projects/:id/members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format `YEAR-MONTH-DAY` | @@ -492,7 +494,7 @@ POST /groups/:id/members/:user_id/override | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell @@ -529,7 +531,7 @@ DELETE /groups/:id/members/:user_id/override | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell @@ -564,7 +566,7 @@ DELETE /projects/:id/members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | | `skip_subresources` | boolean | false | Whether the deletion of direct memberships of the removed member in subgroups and projects should be skipped. Default is `false`. | | `unassign_issuables` | boolean | false | Whether the removed member should be unassigned from any issues or merge requests inside a given group or project. Default is `false`. | diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 8947e5b382f..7bcf4d4c875 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -29,7 +29,7 @@ GET /projects/:id/approvals | Attribute | Type | Required | Description | | --------- | ------- | -------- | ------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | ```json { @@ -58,7 +58,7 @@ POST /projects/:id/approvals | Attribute | Type | Required | Description | | ------------------------------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `approvals_before_merge` | integer | no | How many approvals are required before an MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. | | `reset_approvals_on_push` | boolean | no | Reset approvals on a new push | | `disable_overriding_approvers_per_merge_request` | boolean | no | Allow/Disallow overriding approvers per MR | @@ -93,7 +93,7 @@ GET /projects/:id/approval_rules | Attribute | Type | Required | Description | |----------------------|---------|----------|-----------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | ```json [ @@ -192,7 +192,7 @@ GET /projects/:id/approval_rules/:approval_rule_id | Attribute | Type | Required | Description | |----------------------|---------|----------|-----------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `approval_rule_id` | integer | yes | The ID of a approval rule | ```json @@ -291,7 +291,7 @@ POST /projects/:id/approval_rules | Attribute | Type | Required | Description | |------------------------|---------|----------|------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | | `user_ids` | Array | no | The ids of users as approvers | @@ -396,7 +396,7 @@ PUT /projects/:id/approval_rules/:approval_rule_id | Attribute | Type | Required | Description | |------------------------|---------|----------|------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `approval_rule_id` | integer | yes | The ID of a approval rule | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | @@ -500,7 +500,7 @@ DELETE /projects/:id/approval_rules/:approval_rule_id | Attribute | Type | Required | Description | |----------------------|---------|----------|-----------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `approval_rule_id` | integer | yes | The ID of a approval rule ## Merge Request-level MR approvals @@ -523,7 +523,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/approvals | Attribute | Type | Required | Description | |---------------------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of MR | ```json @@ -570,7 +570,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals | Attribute | Type | Required | Description | |----------------------|---------|----------|--------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of MR | | `approvals_required` | integer | yes | Approvals required before MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. | @@ -612,7 +612,7 @@ This includes additional information about the users who have already approved | Attribute | Type | Required | Description | |----------------------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of MR | ```json @@ -679,7 +679,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/approval_rules | Attribute | Type | Required | Description | |---------------------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of MR | ```json @@ -757,7 +757,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approval_rules | Attribute | Type | Required | Description | |----------------------------|---------|----------|------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of MR | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | @@ -847,7 +847,7 @@ These are system generated rules. | Attribute | Type | Required | Description | |----------------------|---------|----------|------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The ID of MR | | `approval_rule_id` | integer | yes | The ID of a approval rule | | `name` | string | yes | The name of the approval rule | @@ -931,7 +931,7 @@ These are system generated rules. | Attribute | Type | Required | Description | |---------------------|---------|----------|---------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of the merge request | | `approval_rule_id` | integer | yes | The ID of an approval rule | @@ -951,7 +951,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve | Attribute | Type | Required | Description | |---------------------|---------|----------|-------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of the merge request | | `sha` | string | no | The `HEAD` of the merge request | | `approval_password` **(PREMIUM)** | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-authentication-for-approvals) is enabled in the project settings. | @@ -1015,5 +1015,5 @@ POST /projects/:id/merge_requests/:merge_request_iid/unapprove | Attribute | Type | Required | Description | |---------------------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | diff --git a/doc/api/merge_request_context_commits.md b/doc/api/merge_request_context_commits.md index cd38d972320..b40d67ab4e3 100644 --- a/doc/api/merge_request_context_commits.md +++ b/doc/api/merge_request_context_commits.md @@ -17,7 +17,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/context_commits Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The internal ID of the merge request ```json @@ -49,7 +49,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/context_commits Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The internal ID of the merge request ```plaintext @@ -88,7 +88,7 @@ DELETE /projects/:id/merge_requests/:merge_request_iid/context_commits Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The internal ID of the merge request | Attribute | Type | Required | Description | diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 57754f62d5a..bc8c0397a3a 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -265,7 +265,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `iids[]` | integer array | no | Return the request having the given `iid`. | | `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`. | @@ -453,7 +453,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | | `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`. | @@ -623,7 +623,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `render_html` | integer | no | If `true` response includes rendered HTML for title and description. | | `include_diverged_commits_count` | boolean | no | If `true` response includes the commits behind the target branch. | @@ -790,7 +790,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | ```json @@ -826,7 +826,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | ```json @@ -864,7 +864,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `access_raw_diffs` | boolean | no | Retrieve change diffs via Gitaly. | @@ -988,7 +988,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | ```json @@ -1006,15 +1006,15 @@ Parameters: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31722) in GitLab 12.3. -Create a new [pipeline for a merge request](../ci/merge_request_pipelines/index.md). +Create a new [pipeline for a merge request](../ci/pipelines/merge_request_pipelines.md). A pipeline created via this endpoint doesn't run a regular branch/tag pipeline. It requires `.gitlab-ci.yml` to be configured with `only: [merge_requests]` to create jobs. The new pipeline can be: - A detached merge request pipeline. -- A [pipeline for merged results](../ci/merge_request_pipelines/pipelines_for_merged_results/index.md) - if the [project setting is enabled](../ci/merge_request_pipelines/pipelines_for_merged_results/index.md#enable-pipelines-for-merged-results). +- A [pipeline for merged results](../ci/pipelines/pipelines_for_merged_results.md) + if the [project setting is enabled](../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results). ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/pipelines @@ -1024,7 +1024,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | ```json @@ -1076,7 +1076,7 @@ POST /projects/:id/merge_requests | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `source_branch` | string | yes | The source branch. | | `target_branch` | string | yes | The target branch. | | `title` | string | yes | Title of MR. | @@ -1226,7 +1226,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The ID of a merge request. | | `target_branch` | string | no | The target branch. | | `title` | string | no | Title of MR. | @@ -1397,7 +1397,7 @@ DELETE /projects/:id/merge_requests/:merge_request_iid | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | ```shell @@ -1424,7 +1424,7 @@ Parameters: | Attribute | Type | Required | Description | |--------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_commit_message` | string | no | Custom merge commit message. | | `squash_commit_message` | string | no | Custom squash commit message. | @@ -1596,7 +1596,7 @@ Parameters: | Attribute | Type | Required | Description | |--------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | ```json @@ -1619,7 +1619,7 @@ Parameters: | Attribute | Type | Required | Description | |--------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | ```json @@ -1776,7 +1776,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/rebase | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `skip_ci` | boolean | no | Set to `true` to skip creating a CI pipeline. | @@ -1839,7 +1839,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/closes_issues | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | ```shell @@ -1915,7 +1915,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/subscribe | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | ```shell @@ -2075,7 +2075,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/unsubscribe | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | ```shell @@ -2235,7 +2235,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/todo | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | ```shell @@ -2478,7 +2478,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/time_estimate | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `duration` | string | yes | The duration in human format, such as `3h30m`. | @@ -2507,7 +2507,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_time_estimate | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of a project's merge_request. | ```shell @@ -2535,7 +2535,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/add_spent_time | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `duration` | string | yes | The duration in human format, such as `3h30m` | @@ -2564,7 +2564,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_spent_time | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of a project's merge_request. | ```shell @@ -2590,7 +2590,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/time_stats | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | ```shell diff --git a/doc/api/merge_trains.md b/doc/api/merge_trains.md index f74f7785d30..2b52166d954 100644 --- a/doc/api/merge_trains.md +++ b/doc/api/merge_trains.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Merge Trains API **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36146) in GitLab 12.9. -> - Using this API you can consume [Merge Train](../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md) entries. +> - Using this API you can consume [Merge Train](../ci/pipelines/merge_trains.md) entries. Every API call to merge trains must be authenticated with Developer or higher [permissions](../user/permissions.md). @@ -20,7 +20,7 @@ If Merge Trains is not available for the project, a `403` status code is returne By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](README.md#pagination). +Read more on [pagination](index.md#pagination). ## List Merge Trains for a project @@ -33,7 +33,7 @@ GET /projects/:id/merge_trains?scope=complete | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `scope` | string | no | Return Merge Trains filtered by the given scope. Available scopes are `active` (to be merged) and `complete` (have been merged). | | `sort` | string | no | Return Merge Trains sorted in `asc` or `desc` order. Default is `desc`. | diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index 6f360cddd61..603d307f4b7 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -22,7 +22,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `dashboard_path` | string | yes | URL-encoded path to file defining the dashboard which should be marked as favorite. | ```shell @@ -53,7 +53,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `dashboard_path` | string | no | URL-encoded path to file defining the dashboard which should no longer be marked as favorite. When not supplied, all dashboards within given projects are removed from favorites. | ```shell diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 15927ad852e..183d8b4799b 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -4,9 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project milestones API +# Project milestones API **(FREE)** -This page describes the project milestones API. +Use project [milestones](../user/project/milestones/index.md) with the REST API. There's a separate [group milestones API](group_milestones.md) page. ## List project milestones @@ -27,7 +27,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------------------------- | ------ | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | optional | Return only the milestones having the given `iid` (Note: ignored if `include_parent_milestones` is set as `true`) | | `state` | string | optional | Return only `active` or `closed` milestones | | `title` | string | optional | Return only the milestones having the given `title` | @@ -68,7 +68,7 @@ GET /projects/:id/milestones/:milestone_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `milestone_id` (required) - The ID of the project's milestone ## Create new milestone @@ -81,7 +81,7 @@ POST /projects/:id/milestones Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `title` (required) - The title of a milestone - `description` (optional) - The description of the milestone - `due_date` (optional) - The due date of the milestone @@ -97,7 +97,7 @@ PUT /projects/:id/milestones/:milestone_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `milestone_id` (required) - The ID of a project milestone - `title` (optional) - The title of a milestone - `description` (optional) - The description of a milestone @@ -107,7 +107,7 @@ Parameters: ## Delete project milestone -Only for users with Developer access to the project. +Only for users with the Developer role in the project. ```plaintext DELETE /projects/:id/milestones/:milestone_id @@ -115,7 +115,7 @@ DELETE /projects/:id/milestones/:milestone_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `milestone_id` (required) - The ID of the project's milestone ## Get all issues assigned to a single milestone @@ -128,7 +128,7 @@ GET /projects/:id/milestones/:milestone_id/issues Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `milestone_id` (required) - The ID of a project milestone ## Get all merge requests assigned to a single milestone @@ -141,14 +141,14 @@ GET /projects/:id/milestones/:milestone_id/merge_requests Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `milestone_id` (required) - The ID of a project milestone ## Promote project milestone to a group milestone > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53861) in GitLab 11.9 -Only for users with Developer access to the group. +Only for users with the Developer role in the group. ```plaintext POST /projects/:id/milestones/:milestone_id/promote @@ -156,7 +156,7 @@ POST /projects/:id/milestones/:milestone_id/promote Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `milestone_id` (required) - The ID of a project milestone ## Get all burndown chart events for a single milestone **(PREMIUM)** @@ -172,5 +172,5 @@ GET /projects/:id/milestones/:milestone_id/burndown_events Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `milestone_id` (required) - The ID of a project milestone diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 50b28e67c0a..ac8ea95ef30 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -11,7 +11,7 @@ Usernames and group names fall under a special category called namespaces. For users and groups supported API calls see the [users](users.md) and [groups](groups.md) documentation respectively. -[Pagination](README.md#pagination) is used. +[Pagination](index.md#pagination) is used. ## List namespaces @@ -79,15 +79,14 @@ Example response: ] ``` -Users on GitLab.com [Bronze or higher](https://about.gitlab.com/pricing/#gitlab-com) may also see -the `plan` parameter associated with a namespace: +Owners also see the `plan` property associated with a namespace: ```json [ { "id": 1, "name": "user1", - "plan": "bronze", + "plan": "silver", ... } ] @@ -114,7 +113,7 @@ once a day. ``` NOTE: -Only group maintainers/owners are presented with `members_count_with_descendants`, as well as `plan` **(BRONZE ONLY)**. +Only group owners are presented with `members_count_with_descendants` and `plan`. ## Search for namespace @@ -168,7 +167,7 @@ GET /namespaces/:id | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the namespace](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the namespace](index.md#namespaced-path-encoding) | Example request: diff --git a/doc/api/notes.md b/doc/api/notes.md index 0fb13e56f78..6a3db0a2aab 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -34,7 +34,7 @@ Some system notes are not part of this API, but are recorded as separate events: By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](README.md#pagination). +Read more on [pagination](index.md#pagination). ## Rate limits @@ -54,7 +54,7 @@ GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | `issue_iid` | integer | yes | The IID of an issue | `sort` | string | no | Return issue notes sorted in `asc` or `desc` order. Default is `desc` | `order_by` | string | no | Return issue notes ordered by `created_at` or `updated_at` fields. Default is `created_at` @@ -120,7 +120,7 @@ GET /projects/:id/issues/:issue_iid/notes/:note_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) - `issue_iid` (required) - The IID of a project issue - `note_id` (required) - The ID of an issue note @@ -138,7 +138,7 @@ POST /projects/:id/issues/:issue_iid/notes Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) - `issue_iid` (required) - The IID of an issue - `body` (required) - The content of a note. Limited to 1,000,000 characters. - `confidential` (optional) - The confidential flag of a note. Default is false. @@ -158,7 +158,7 @@ PUT /projects/:id/issues/:issue_iid/notes/:note_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). - `issue_iid` (required) - The IID of an issue. - `note_id` (required) - The ID of a note. - `body` (optional) - The content of a note. Limited to 1,000,000 characters. @@ -180,7 +180,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `note_id` | integer | yes | The ID of a note | @@ -203,7 +203,7 @@ GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | `snippet_id` | integer | yes | The ID of a project snippet | `sort` | string | no | Return snippet notes sorted in `asc` or `desc` order. Default is `desc` | `order_by` | string | no | Return snippet notes ordered by `created_at` or `updated_at` fields. Default is `created_at` @@ -222,7 +222,7 @@ GET /projects/:id/snippets/:snippet_id/notes/:note_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) - `snippet_id` (required) - The ID of a project snippet - `note_id` (required) - The ID of a snippet note @@ -260,7 +260,7 @@ POST /projects/:id/snippets/:snippet_id/notes Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) - `snippet_id` (required) - The ID of a snippet - `body` (required) - The content of a note. Limited to 1,000,000 characters. - `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) @@ -279,7 +279,7 @@ PUT /projects/:id/snippets/:snippet_id/notes/:note_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) - `snippet_id` (required) - The ID of a snippet - `note_id` (required) - The ID of a note - `body` (required) - The content of a note. Limited to 1,000,000 characters. @@ -300,7 +300,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of a snippet | | `note_id` | integer | yes | The ID of a note | @@ -321,7 +321,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=upda | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | `merge_request_iid` | integer | yes | The IID of a project merge request | `sort` | string | no | Return merge request notes sorted in `asc` or `desc` order. Default is `desc` | `order_by` | string | no | Return merge request notes ordered by `created_at` or `updated_at` fields. Default is `created_at` @@ -340,7 +340,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) - `merge_request_iid` (required) - The IID of a project merge request - `note_id` (required) - The ID of a merge request note @@ -383,7 +383,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/notes Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) - `merge_request_iid` (required) - The IID of a merge request - `body` (required) - The content of a note. Limited to 1,000,000 characters. - `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) @@ -398,7 +398,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) - `merge_request_iid` (required) - The IID of a merge request - `note_id` (required) - The ID of a note - `body` (required) - The content of a note. Limited to 1,000,000 characters. @@ -419,7 +419,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `note_id` | integer | yes | The ID of a note | @@ -440,7 +440,7 @@ GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of a group epic | | `sort` | string | no | Return epic notes sorted in `asc` or `desc` order. Default is `desc` | | `order_by` | string | no | Return epic notes ordered by `created_at` or `updated_at` fields. Default is `created_at` | @@ -461,7 +461,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `note_id` | integer | yes | The ID of a note | @@ -502,7 +502,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | @@ -522,7 +522,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `note_id` | integer | yes | The ID of a note | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | @@ -543,7 +543,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `note_id` | integer | yes | The ID of a note | diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 69bed193f07..390ba7dbd79 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -4,22 +4,20 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Notification settings API +# Notification settings API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5632) in GitLab 8.12. +Change [notification settings](../user/profile/notifications.md) using the REST API. ## Valid notification levels The notification levels are defined in the `NotificationSetting.level` model enumeration. Currently, these levels are recognized: -```plaintext -disabled -participating -watch -global -mention -custom -``` +- `disabled` +- `participating` +- `watch` +- `global` +- `mention` +- `custom` If the `custom` level is used, specific email events can be controlled. Available events are returned by `NotificationSetting.email_events`. Currently, these events are recognized: @@ -123,7 +121,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](README.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](index.md#namespaced-path-encoding). | Example response: @@ -149,7 +147,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](index.md#namespaced-path-encoding) | | `level` | string | no | The global notification level | | `new_note` | boolean | no | Enable/disable this notification | | `new_issue` | boolean | no | Enable/disable this notification | diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index f5c75aac0d9..1b06e554e5e 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -218,7 +218,7 @@ https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIREC This prompts the user to approve the applications access to their account based on the scopes specified in `REQUESTED_SCOPES` and then redirect back to the `REDIRECT_URI` you provided. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes) - is a space separated list of scopes you want to have access to (e.g. `scope=read_user+profile` + is a space separated list of scopes you want to have access to (for example, `scope=read_user+profile` would request `read_user` and `profile` scopes). The redirect includes a fragment with `access_token` as well as token details in GET parameters, for example: diff --git a/doc/api/openapi/openapi.yaml b/doc/api/openapi/openapi.yaml index 46267129b32..cc6a161c783 100644 --- a/doc/api/openapi/openapi.yaml +++ b/doc/api/openapi/openapi.yaml @@ -15,7 +15,7 @@ info: When viewing this on gitlab.com, you can test API calls directly from the browser against the `gitlab.com` instance, if you are logged in. - The feature uses the current [GitLab session cookie](https://docs.gitlab.com/ee/api/README.html#session-cookie), + The feature uses the current [GitLab session cookie](https://docs.gitlab.com/ee/api/index.html#session-cookie), so each request is made using your account. Instructions for using this tool can be found in [Interactive API Documentation](openapi_interactive.md). diff --git a/doc/api/openapi/openapi_interactive.md b/doc/api/openapi/openapi_interactive.md index 05fd7b20b75..c9434147609 100644 --- a/doc/api/openapi/openapi_interactive.md +++ b/doc/api/openapi/openapi_interactive.md @@ -14,7 +14,7 @@ The [OpenAPI specification](https://swagger.io/specification/) (formerly called standard, language-agnostic interface to RESTful APIs. OpenAPI definition files are written in the YAML format, which is automatically rendered by the GitLab browser into a more human-readable interface. -For general information about the GitLab APIs, see [API Docs](../README.md). +For general information about the GitLab APIs, see [API Docs](../index.md). ## Overview diff --git a/doc/api/packages.md b/doc/api/packages.md index c257105f72e..73092e68c82 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -23,10 +23,10 @@ GET /projects/:id/packages | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `order_by`| string | no | The field to use as order. One of `created_at` (default), `name`, `version`, or `type`. | | `sort` | string | no | The direction of the order, either `asc` (default) for ascending order or `desc` for descending order. | -| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, `nuget`, or `golang`. (_Introduced in GitLab 12.9_) +| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, `nuget`, `helm`, or `golang`. (_Introduced in GitLab 12.9_) | `package_name` | string | no | Filter the project packages with a fuzzy search by name. (_Introduced in GitLab 12.9_) | `include_versionless` | boolean | no | When set to true, versionless packages are included in the response. (_Introduced in GitLab 13.8_) | `status` | string | no | Filter the returned packages by status. One of `default` (default), `hidden`, or `processing`. (_Introduced in GitLab 13.9_) @@ -69,7 +69,7 @@ Example response: ] ``` -By default, the `GET` request returns 20 results, because the API is [paginated](README.md#pagination). +By default, the `GET` request returns 20 results, because the API is [paginated](index.md#pagination). Although you can filter packages by status, working with packages that have a `processing` status can result in malformed data or broken packages. @@ -87,11 +87,11 @@ GET /groups/:id/packages | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the group](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | | `exclude_subgroups` | boolean | false | If the parameter is included as true, packages from projects from subgroups are not listed. Default is `false`. | | `order_by`| string | no | The field to use as order. One of `created_at` (default), `name`, `version`, `type`, or `project_path`. | | `sort` | string | no | The direction of the order, either `asc` (default) for ascending order or `desc` for descending order. | -| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, `nuget`, or `golang`. (_Introduced in GitLab 12.9_) | +| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, `nuget`, `helm`, or `golang`. (_Introduced in GitLab 12.9_) | | `package_name` | string | no | Filter the project packages with a fuzzy search by name. (_[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30980) in GitLab 13.0_) | `include_versionless` | boolean | no | When set to true, versionless packages are included in the response. (_Introduced in GitLab 13.8_) | `status` | string | no | Filter the returned packages by status. One of `default` (default), `hidden`, or `processing`. (_Introduced in GitLab 13.9_) @@ -164,7 +164,7 @@ Example response: ] ``` -By default, the `GET` request returns 20 results, because the API is [paginated](README.md#pagination). +By default, the `GET` request returns 20 results, because the API is [paginated](index.md#pagination). The `_links` object contains the following properties: @@ -186,7 +186,7 @@ GET /projects/:id/packages/:package_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `package_id` | integer | yes | ID of a package. | ```shell @@ -268,7 +268,7 @@ GET /projects/:id/packages/:package_id/package_files | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `package_id` | integer | yes | ID of a package. | ```shell @@ -327,7 +327,7 @@ Example response: ] ``` -By default, the `GET` request returns 20 results, because the API is [paginated](README.md#pagination). +By default, the `GET` request returns 20 results, because the API is [paginated](index.md#pagination). ## Delete a project package @@ -341,7 +341,7 @@ DELETE /projects/:id/packages/:package_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `package_id` | integer | yes | ID of a package. | ```shell @@ -369,7 +369,7 @@ DELETE /projects/:id/packages/:package_id/package_files/:package_file_id | Attribute | Type | Required | Description | | ----------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `package_id` | integer | yes | ID of a package. | | `package_file_id` | integer | yes | ID of a package file. | diff --git a/doc/api/packages/debian.md b/doc/api/packages/debian.md new file mode 100644 index 00000000000..cd97bd609df --- /dev/null +++ b/doc/api/packages/debian.md @@ -0,0 +1,151 @@ +--- +stage: Package +group: Package +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Debian API + +This is the API documentation for [Debian](../../user/packages/debian_repository/index.md). + +WARNING: +This API is used by the Debian related package clients such as [dput](https://manpages.debian.org/stable/dput-ng/dput.1.en.html) +and [apt-get](https://manpages.debian.org/stable/apt/apt-get.8.en.html), +and is generally not meant for manual consumption. This API is under development and is not ready +for production use due to limited functionality. + +For instructions on how to upload and install Debian packages from the GitLab +package registry, see the [Debian registry documentation](../../user/packages/debian_repository/index.md). + +NOTE: +These endpoints do not adhere to the standard API authentication methods. +See the [Debian registry documentation](../../user/packages/debian_repository/index.md) +for details on which headers and token types are supported. + +## Enable the Debian API + +The Debian API for GitLab is behind a feature flag that is disabled by default. GitLab +administrators with access to the GitLab Rails console can enable this API for your instance. + +To enable it: + +```ruby +Feature.enable(:debian_packages) +``` + +To disable it: + +```ruby +Feature.disable(:debian_packages) +``` + +## Upload a package file + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62028) in GitLab 14.0. + +Upload a Debian package file: + +```plaintext +PUT projects/:id/packages/debian/:file_name +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | string | yes | The ID or full path of the project. | +| `file_name` | string | yes | The name of the Debian package file. | + +```shell +curl --request PUT \ + --upload-file path/to/mypkg.deb \ + --header "Private-Token: <personal_access_token>" \ + "https://gitlab.example.com/api/v4/projects/1/packages/debian/mypkg.deb" +``` + +## Route prefix + +The remaining endpoints described are two sets of identical routes that each make requests in +different scopes: + +- Use the project-level prefix to make requests in a single project's scope. +- Use the group-level prefix to make requests in a single group's scope. + +The examples in this document all use the project-level prefix. + +### Project-level + +```plaintext + /projects/:id/packages/debian` +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | string | yes | The project ID or full project path. | + +### Group-level + +```plaintext + /groups/:id/-/packages/debian` +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | string | yes | The project ID or full group path. | + +## Download a distribution Release file + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64067) in GitLab 14.1. + +Download a Debian package file. + +```plaintext +GET <route-prefix>/dists/*distribution/Release +``` + +| Attribute | Type | Required | Description | +| ----------------- | ------ | -------- | ----------- | +| `distribution` | string | yes | The codename or suite of the Debian distribution. | + +```shell +curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/Release" +``` + +Write the output to a file: + +```shell +curl --header "Private-Token: <personal_access_token>" \ + "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/Release" \ + --remote-name +``` + +This writes the downloaded file to `Release` in the current directory. + +## Download a signed distribution Release file + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64067) in GitLab 14.1. + +Download a Debian package file. + +Signed releases are [not supported](https://gitlab.com/groups/gitlab-org/-/epics/6057#note_582697034). +Therefore, this endpoint downloads the unsigned release file. + +```plaintext +GET <route-prefix>/dists/*distribution/InRelease +``` + +| Attribute | Type | Required | Description | +| ----------------- | ------ | -------- | ----------- | +| `distribution` | string | yes | The codename or suite of the Debian distribution. | + +```shell +curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/InRelease" +``` + +Write the output to a file: + +```shell +curl --header "Private-Token: <personal_access_token>" \ + "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/InRelease" \ + --remote-name +``` + +This writes the downloaded file to `InRelease` in the current directory. diff --git a/doc/api/packages/debian_group_distributions.md b/doc/api/packages/debian_group_distributions.md new file mode 100644 index 00000000000..ba61bf49e01 --- /dev/null +++ b/doc/api/packages/debian_group_distributions.md @@ -0,0 +1,222 @@ +--- +stage: Package +group: Package +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Debian group distributions API **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5835) in GitLab 14.0. + +See the [Debian package registry documentation](../../user/packages/debian_repository/index.md) +for more information about working with Debian packages. + +## Enable Debian repository feature + +Debian repository support is gated behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can opt to enable it. + +To enable it: + +```ruby +Feature.enable(:debian_packages) +``` + +To disable it: + +```ruby +Feature.disable(:debian_packages) +``` + +## List all Debian distributions in a group + +Lists Debian distributions in the given group. + +```plaintext +GET /groups/:id/debian_distributions +``` + +| Attribute | Type | Required | Description | +| ---------- | --------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding). | +| `codename` | string | no | Filter with specific `codename`. | +| `suite` | string | no | Filter with specific `suite`. | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions" +``` + +Example response: + +```json +[ + { + "id": 1, + "codename": "unstable", + "suite": null, + "origin": null, + "label": null, + "version": null, + "description": null, + "valid_time_duration_seconds": null, + "components": [ + "main" + ], + "architectures": [ + "all", + "amd64" + ] + } +] +``` + +## Single Debian group distribution + +Gets a single Debian group distribution. + +```plaintext +GET /groups/:id/debian_distributions/:codename +``` + +| Attribute | Type | Required | Description | +| ---------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `codename` | integer | yes | The `codename` of a distribution. | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions/unstable" +``` + +Example response: + +```json +{ + "id": 1, + "codename": "unstable", + "suite": null, + "origin": null, + "label": null, + "version": null, + "description": null, + "valid_time_duration_seconds": null, + "components": [ + "main" + ], + "architectures": [ + "all", + "amd64" + ] +} +``` + +## Create a Debian group distribution + +Creates a Debian group distribution. + +```plaintext +POST /groups/:id/debian_distributions +``` + +| Attribute | Type | Required | Description | +| ----------------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `codename` | string | yes | The codename of a Debian distribution. | +| `suite` | string | no | The suite of the new Debian distribution. | +| `origin` | string | no | The origin of the new Debian distribution. | +| `label` | string | no | The label of the new Debian distribution. | +| `version` | string | no | The version of the new Debian distribution. | +| `description` | string | no | The description of the new Debian distribution. | +| `valid_time_duration_seconds` | integer | no | The valid time duration (in seconds) of the new Debian distribution. | +| `components` | architectures | no | The new Debian distribution's list of components. | +| `architectures` | architectures | no | The new Debian distribution's list of architectures. | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions?codename=unstable" +``` + +Example response: + +```json +{ + "id": 1, + "codename": "unstable", + "suite": null, + "origin": null, + "label": null, + "version": null, + "description": null, + "valid_time_duration_seconds": null, + "components": [ + "main" + ], + "architectures": [ + "all", + "amd64" + ] +} +``` + +## Update a Debian group distribution + +Updates a Debian group distribution. + +```plaintext +PUT /groups/:id/debian_distributions/:codename +``` + +| Attribute | Type | Required | Description | +| ----------------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `codename` | string | yes | The Debian distribution's new codename. | +| `suite` | string | no | The Debian distribution's new suite. | +| `origin` | string | no | The Debian distribution's new origin. | +| `label` | string | no | The Debian distribution's new label. | +| `version` | string | no | The Debian distribution's new version. | +| `description` | string | no | The Debian distribution's new description. | +| `valid_time_duration_seconds` | integer | no | The Debian distribution's new valid time duration (in seconds). | +| `components` | architectures | no | The Debian distribution's new list of components. | +| `architectures` | architectures | no | The Debian distribution's new list of architectures. | + +```shell +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions/unstable?suite=new-suite&valid_time_duration_seconds=604800" +``` + +Example response: + +```json +{ + "id": 1, + "codename": "unstable", + "suite": "new-suite", + "origin": null, + "label": null, + "version": null, + "description": null, + "valid_time_duration_seconds": 604800, + "components": [ + "main" + ], + "architectures": [ + "all", + "amd64" + ] +} +``` + +## Delete a Debian group distribution + +Deletes a Debian group distribution. + +```plaintext +DELETE /groups/:id/debian_distributions/:codename +``` + +| Attribute | Type | Required | Description | +| ---------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `codename` | integer | yes | The codename of the Debian distribution. | + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions/unstable" +``` diff --git a/doc/api/packages/debian_project_distributions.md b/doc/api/packages/debian_project_distributions.md new file mode 100644 index 00000000000..aad5558dcba --- /dev/null +++ b/doc/api/packages/debian_project_distributions.md @@ -0,0 +1,222 @@ +--- +stage: Package +group: Package +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Debian project distributions API **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5835) in GitLab 14.0. + +See the [Debian package registry documentation](../../user/packages/debian_repository/index.md) +for more information about working with Debian packages. + +## Enable Debian repository feature + +Debian repository support is gated behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can opt to enable it. + +To enable it: + +```ruby +Feature.enable(:debian_packages) +``` + +To disable it: + +```ruby +Feature.disable(:debian_packages) +``` + +## List all Debian distributions in a project + +Lists Debian distributions in the given project. + +```plaintext +GET /projects/:id/debian_distributions +``` + +| Attribute | Type | Required | Description | +| ---------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `codename` | string | no | Filter with a specific `codename`. | +| `suite` | string | no | Filter with a specific `suite`. | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions" +``` + +Example response: + +```json +[ + { + "id": 1, + "codename": "unstable", + "suite": null, + "origin": null, + "label": null, + "version": null, + "description": null, + "valid_time_duration_seconds": null, + "components": [ + "main" + ], + "architectures": [ + "all", + "amd64" + ] + } +] +``` + +## Single Debian project distribution + +Gets a single Debian project distribution. + +```plaintext +GET /projects/:id/debian_distributions/:codename +``` + +| Attribute | Type | Required | Description | +| ---------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `codename` | integer | yes | The `codename` of a distribution. | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions/unstable" +``` + +Example response: + +```json +{ + "id": 1, + "codename": "unstable", + "suite": null, + "origin": null, + "label": null, + "version": null, + "description": null, + "valid_time_duration_seconds": null, + "components": [ + "main" + ], + "architectures": [ + "all", + "amd64" + ] +} +``` + +## Create a Debian project distribution + +Creates a Debian project distribution. + +```plaintext +POST /projects/:id/debian_distributions +``` + +| Attribute | Type | Required | Description | +| ----------------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `codename` | string | yes | The Debian distribution's codename. | +| `suite` | string | no | The new Debian distribution's suite. | +| `origin` | string | no | The new Debian distribution's origin. | +| `label` | string | no | The new Debian distribution's label. | +| `version` | string | no | The new Debian distribution's version. | +| `description` | string | no | The new Debian distribution's description. | +| `valid_time_duration_seconds` | integer | no | The new Debian distribution's valid time duration (in seconds). | +| `components` | architectures | no | The new Debian distribution's list of components. | +| `architectures` | architectures | no | The new Debian distribution's list of architectures. | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions?codename=unstable" +``` + +Example response: + +```json +{ + "id": 1, + "codename": "unstable", + "suite": null, + "origin": null, + "label": null, + "version": null, + "description": null, + "valid_time_duration_seconds": null, + "components": [ + "main" + ], + "architectures": [ + "all", + "amd64" + ] +} +``` + +## Update a Debian project distribution + +Updates a Debian project distribution. + +```plaintext +PUT /projects/:id/debian_distributions/:codename +``` + +| Attribute | Type | Required | Description | +| ----------------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `codename` | string | yes | The Debian distribution's codename. | +| `suite` | string | no | The Debian distribution's new suite. | +| `origin` | string | no | The Debian distribution's new origin. | +| `label` | string | no | The Debian distribution's new label. | +| `version` | string | no | The Debian distribution's new version. | +| `description` | string | no | The Debian distribution's new description. | +| `valid_time_duration_seconds` | integer | no | The Debian distribution's new valid time duration (in seconds). | +| `components` | architectures | no | The Debian distribution's new list of components. | +| `architectures` | architectures | no | The Debian distribution's new list of architectures. | + +```shell +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions/unstable?suite=new-suite&valid_time_duration_seconds=604800" +``` + +Example response: + +```json +{ + "id": 1, + "codename": "unstable", + "suite": "new-suite", + "origin": null, + "label": null, + "version": null, + "description": null, + "valid_time_duration_seconds": 604800, + "components": [ + "main" + ], + "architectures": [ + "all", + "amd64" + ] +} +``` + +## Delete a Debian project distribution + +Deletes a Debian project distribution. + +```plaintext +DELETE /projects/:id/debian_distributions/:codename +``` + +| Attribute | Type | Required | Description | +| ---------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `codename` | integer | yes | The Debian distribution's codename. | + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions/unstable" +``` diff --git a/doc/api/packages/helm.md b/doc/api/packages/helm.md new file mode 100644 index 00000000000..a76fa9d3755 --- /dev/null +++ b/doc/api/packages/helm.md @@ -0,0 +1,96 @@ +--- +stage: Package +group: Package +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Helm API + +This is the API documentation for [Helm](../../user/packages/helm_repository/index.md). + +WARNING: +This API is used by the Helm-related package clients such as [Helm](https://helm.sh/) +and [`helm-push`](https://github.com/chartmuseum/helm-push/#readme), +and is generally not meant for manual consumption. This API is under development and is not ready +for production use due to limited functionality. + +For instructions on how to upload and install Helm packages from the GitLab +Package Registry, see the [Helm registry documentation](../../user/packages/helm_repository/index.md). + +NOTE: +These endpoints do not adhere to the standard API authentication methods. +See the [Helm registry documentation](../../user/packages/helm_repository/index.md) +for details on which headers and token types are supported. + +## Download a chart index + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62757) in GitLab 14.1. + +Download a chart index: + +```plaintext +GET projects/:id/packages/helm/:channel/index.yaml +``` + +| Attribute | Type | Required | Description | +| --------- | ------ | -------- | ----------- | +| `id` | string | yes | The ID or full path of the project. | +| `channel` | string | yes | Helm repository channel. | + +```shell +curl --user <username>:<personal_access_token> \ + https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/index.yaml +``` + +Write the output to a file: + +```shell +curl --user <username>:<personal_access_token> \ + https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/index.yaml \ + --remote-name +``` + +## Download a chart + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61014) in GitLab 14.0. + +Download a chart: + +```plaintext +GET projects/:id/packages/helm/:channel/charts/:file_name.tgz +``` + +| Attribute | Type | Required | Description | +| ----------- | ------ | -------- | ----------- | +| `id` | string | yes | The ID or full path of the project. | +| `channel` | string | yes | Helm repository channel. | +| `file_name` | string | yes | Chart file name. | + +```shell +curl --user <username>:<personal_access_token> \ + https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/charts/mychart.tgz \ + --remote-name +``` + +## Upload a chart + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64814) in GitLab 14.1. + +Upload a chart: + +```plaintext +POST projects/:id/packages/helm/api/:channel/charts +``` + +| Attribute | Type | Required | Description | +| --------- | ------ | -------- | ----------- | +| `id` | string | yes | The ID or full path of the project. | +| `channel` | string | yes | Helm repository channel. | +| `chart` | file | yes | Chart (as `multipart/form-data`). | + +```shell +curl --request POST \ + --form 'chart=@mychart.tgz' \ + --user <username>:<personal_access_token> \ + https://gitlab.example.com/api/v4/projects/1/packages/helm/api/stable/charts +``` diff --git a/doc/api/packages/nuget.md b/doc/api/packages/nuget.md index bbcb2cb9bc4..d19e2dfa65b 100644 --- a/doc/api/packages/nuget.md +++ b/doc/api/packages/nuget.md @@ -102,6 +102,30 @@ curl --request PUT \ "https://gitlab.example.com/api/v4/projects/1/packages/nuget" ``` +## Upload a symbol package file + +> Introduced in GitLab 12.8. + +Upload a NuGet symbol package file (`.snupkg`): + +```plaintext +PUT projects/:id/packages/nuget/symbolpackage +``` + +| Attribute | Type | Required | Description | +| ----------------- | ------ | -------- | ----------- | +| `id` | string | yes | The ID or full path of the project. | +| `package_name` | string | yes | The name of the package. | +| `package_version` | string | yes | The version of the package. | +| `package_filename`| string | yes | The name of the file. | + +```shell +curl --request PUT \ + --upload-file path/to/mynugetpkg.1.3.0.17.snupkg \ + --user <username>:<personal_access_token> \ + "https://gitlab.example.com/api/v4/projects/1/packages/nuget/symbolpackage" +``` + ## Route prefix For the remaining routes, there are two sets of identical routes that each make requests in @@ -193,6 +217,11 @@ Example response: "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget", "@type": "PackagePublish/2.0.0", "comment": "Push and delete (or unlist) packages." + }, + { + "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/symbolpackage", + "@type": "SymbolPackagePublish/4.9.0", + "comment": "Push symbol packages." } ] } diff --git a/doc/api/packages/pypi.md b/doc/api/packages/pypi.md index 77ba028c447..dd301e9fab8 100644 --- a/doc/api/packages/pypi.md +++ b/doc/api/packages/pypi.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w This is the API documentation for [PyPI Packages](../../user/packages/pypi_repository/index.md). WARNING: -This API is used by the [PyPI package manager client](https://pypi.apache.org/) +This API is used by the [PyPI package manager client](https://pypi.org/) and is generally not meant for manual consumption. For instructions on how to upload and install PyPI packages from the GitLab diff --git a/doc/api/pages.md b/doc/api/pages.md index 0a79d23b51e..ef6523520de 100644 --- a/doc/api/pages.md +++ b/doc/api/pages.md @@ -20,7 +20,7 @@ DELETE /projects/:id/pages | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --request 'DELETE' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/2/pages" diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index fbea365e3d5..46d92db9853 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -47,7 +47,7 @@ GET /projects/:id/pages/domains | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains" @@ -83,7 +83,7 @@ GET /projects/:id/pages/domains/:domain | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `domain` | string | yes | The custom domain indicated by the user | ```shell @@ -125,7 +125,7 @@ POST /projects/:id/pages/domains | Attribute | Type | Required | Description | | -------------------| -------------- | -------- | ---------------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `domain` | string | yes | The custom domain indicated by the user | | `auto_ssl_enabled` | boolean | no | Enables [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates issued by Let's Encrypt for custom domains. | | `certificate` | file/string | no | The certificate in PEM format with intermediates following in most specific to least specific order.| @@ -178,7 +178,7 @@ PUT /projects/:id/pages/domains/:domain | Attribute | Type | Required | Description | | ------------------ | -------------- | -------- | ---------------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `domain` | string | yes | The custom domain indicated by the user | | `auto_ssl_enabled` | boolean | no | Enables [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates issued by Let's Encrypt for custom domains. | | `certificate` | file/string | no | The certificate in PEM format with intermediates following in most specific to least specific order.| @@ -256,7 +256,7 @@ DELETE /projects/:id/pages/domains/:domain | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `domain` | string | yes | The custom domain indicated by the user | ```shell diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index afb5d434fe7..74f96e5374e 100644 --- a/doc/api/pipeline_schedules.md +++ b/doc/api/pipeline_schedules.md @@ -18,7 +18,7 @@ GET /projects/:id/pipeline_schedules | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `scope` | string | no | The scope of pipeline schedules, one of: `active`, `inactive` | ```shell @@ -59,7 +59,7 @@ GET /projects/:id/pipeline_schedules/:pipeline_schedule_id | Attribute | Type | required | Description | |--------------|---------|----------|--------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | ```shell @@ -111,7 +111,7 @@ POST /projects/:id/pipeline_schedules | Attribute | Type | required | Description | |-----------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `description` | string | yes | The description of the pipeline schedule. | | `ref` | string | yes | The branch or tag name that is triggered. | | `cron` | string | yes | The [cron](https://en.wikipedia.org/wiki/Cron) schedule, for example: `0 1 * * *`. | @@ -157,7 +157,7 @@ PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id | Attribute | Type | required | Description | |------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID. | | `description` | string | no | The description of the pipeline schedule. | | `ref` | string | no | The branch or tag name that is triggered. | @@ -208,7 +208,7 @@ POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/take_ownership | Attribute | Type | required | Description | |---------------|---------|----------|--------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | ```shell @@ -253,7 +253,7 @@ DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id | Attribute | Type | required | Description | |----------------|---------|----------|--------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | ```shell @@ -301,7 +301,7 @@ POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/play | Attribute | Type | required | Description | | ---------------- | --------- | ---------- | -------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | Example request: @@ -330,7 +330,7 @@ POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables | Attribute | Type | required | Description | |------------------------|----------------|----------|--------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | | `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 | @@ -359,7 +359,7 @@ PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key | Attribute | Type | required | Description | |------------------------|----------------|----------|--------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | | `key` | string | yes | The `key` of a variable | | `value` | string | yes | The `value` of a variable | @@ -389,7 +389,7 @@ DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key | Attribute | Type | required | Description | |------------------------|----------------|----------|--------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | | `key` | string | yes | The `key` of a variable | diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md index 94122a40b2d..2fe3f487ebc 100644 --- a/doc/api/pipeline_triggers.md +++ b/doc/api/pipeline_triggers.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Pipeline triggers API **(FREE)** -You can read more about [triggering pipelines through the API](../ci/triggers/README.md). +You can read more about [triggering pipelines through the API](../ci/triggers/index.md). ## List project triggers @@ -18,7 +18,7 @@ GET /projects/:id/triggers | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers" @@ -48,7 +48,7 @@ GET /projects/:id/triggers/:trigger_id | Attribute | Type | required | Description | |--------------|---------|----------|--------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `trigger_id` | integer | yes | The trigger ID | ```shell @@ -77,7 +77,7 @@ POST /projects/:id/triggers | Attribute | Type | required | Description | |---------------|---------|----------|--------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `description` | string | yes | The trigger name | ```shell @@ -107,7 +107,7 @@ PUT /projects/:id/triggers/:trigger_id | Attribute | Type | required | Description | |---------------|---------|----------|--------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `trigger_id` | integer | yes | The trigger ID | | `description` | string | no | The trigger name | @@ -138,7 +138,7 @@ DELETE /projects/:id/triggers/:trigger_id | Attribute | Type | required | Description | |----------------|---------|----------|--------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `trigger_id` | integer | yes | The trigger ID | ```shell diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 57c356ccf29..7d433923865 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36494) in GitLab 13.3. Endpoints that request information about a single pipeline return data for any pipeline. -Before 13.3, requests for [child pipelines](../ci/parent_child_pipelines.md) returned +Before 13.3, requests for [child pipelines](../ci/pipelines/parent_child_pipelines.md) returned a 404 error. ## Pipelines pagination @@ -19,7 +19,7 @@ a 404 error. By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](README.md#pagination). +Read more on [pagination](index.md#pagination). ## List project pipelines @@ -29,7 +29,7 @@ GET /projects/:id/pipelines | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `scope` | string | no | The scope of pipelines, one of: `running`, `pending`, `finished`, `branches`, `tags` | | `status` | string | no | The status of pipelines, one of: `created`, `waiting_for_resource`, `preparing`, `pending`, `running`, `success`, `failed`, `canceled`, `skipped`, `manual`, `scheduled` | | `ref` | string | no | The ref of pipelines | @@ -81,7 +81,7 @@ GET /projects/:id/pipelines/:pipeline_id | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell @@ -128,7 +128,7 @@ GET /projects/:id/pipelines/:pipeline_id/variables | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell @@ -164,7 +164,7 @@ GET /projects/:id/pipelines/:pipeline_id/test_report | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | Sample request: @@ -215,7 +215,7 @@ POST /projects/:id/pipeline | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `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](index.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', 'variable_type': 'file', 'value': 'true' }]` | @@ -263,7 +263,7 @@ POST /projects/:id/pipelines/:pipeline_id/retry | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell @@ -310,7 +310,7 @@ POST /projects/:id/pipelines/:pipeline_id/cancel | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell @@ -359,7 +359,7 @@ DELETE /projects/:id/pipelines/:pipeline_id | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell diff --git a/doc/api/plan_limits.md b/doc/api/plan_limits.md index 105cf13f9de..c89c7b46d54 100644 --- a/doc/api/plan_limits.md +++ b/doc/api/plan_limits.md @@ -38,10 +38,12 @@ Example response: { "conan_max_file_size": 3221225472, "generic_packages_max_file_size": 5368709120, + "helm_max_file_size": 5242880, "maven_max_file_size": 3221225472, "npm_max_file_size": 524288000, "nuget_max_file_size": 524288000, - "pypi_max_file_size": 3221225472 + "pypi_max_file_size": 3221225472, + "terraform_module_max_file_size": 1073741824 } ``` @@ -58,10 +60,12 @@ PUT /application/plan_limits | `plan_name` | string | yes | Name of the plan to update. | | `conan_max_file_size` | integer | no | Maximum Conan package file size in bytes. | | `generic_packages_max_file_size` | integer | no | Maximum generic package file size in bytes. | +| `helm_max_file_size` | integer | no | Maximum Helm chart file size in bytes. | | `maven_max_file_size` | integer | no | Maximum Maven package file size in bytes. | | `npm_max_file_size` | integer | no | Maximum NPM package file size in bytes. | | `nuget_max_file_size` | integer | no | Maximum NuGet package file size in bytes. | | `pypi_max_file_size` | integer | no | Maximum PyPI package file size in bytes. | +| `terraform_module_max_file_size` | integer | no | Maximum Terraform Module package file size in bytes. | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/plan_limits?plan_name=default&conan_max_file_size=3221225472" @@ -73,9 +77,11 @@ Example response: { "conan_max_file_size": 3221225472, "generic_packages_max_file_size": 5368709120, + "helm_max_file_size": 5242880, "maven_max_file_size": 3221225472, "npm_max_file_size": 524288000, "nuget_max_file_size": 524288000, - "pypi_max_file_size": 3221225472 + "pypi_max_file_size": 3221225472, + "terraform_module_max_file_size": 1073741824 } ``` diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index c6bcaa1ae9c..7726261a329 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -31,7 +31,7 @@ GET /projects/:id/badges | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | no | Name of the badges to return (case-sensitive). | ```shell @@ -73,7 +73,7 @@ GET /projects/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | ```shell @@ -103,7 +103,7 @@ POST /projects/:id/badges | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link | | `image_url` | string | yes | URL of the badge image | | `name` | string | no | Name of the badge | @@ -138,7 +138,7 @@ PUT /projects/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | | `link_url` | string | no | URL of the badge link | | `image_url` | string | no | URL of the badge image | @@ -172,7 +172,7 @@ DELETE /projects/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | ```shell @@ -189,7 +189,7 @@ GET /projects/:id/badges/render | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link| | `image_url` | string | yes | URL of the badge image | diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index f31b3ccd0bb..2b4976510bb 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -22,7 +22,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------- | -------- | ----------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | Example request: @@ -92,7 +92,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | ------- | -------- | ----------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | Example request: @@ -186,9 +186,9 @@ Parameters: | Attribute | Type | Required | Description | | ---------------------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the cluster | -| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | +| `domain` | string | no | The [base domain](../user/project/clusters/gitlab_managed_clusters.md#base-domain) of the cluster | | `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | | `enabled` | boolean | no | Determines if cluster is active or not, defaults to `true` | | `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster. Defaults to `true` | @@ -283,10 +283,10 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------ | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | | `name` | string | no | The name of the cluster | -| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | +| `domain` | string | no | The [base domain](../user/project/clusters/gitlab_managed_clusters.md#base-domain) of the cluster | | `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | | `enabled` | boolean | no | Determines if cluster is active or not | | `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster | @@ -395,7 +395,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | ------- | -------- | ----------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | Example request: diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index b20ce9896dc..92b1558551d 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -31,7 +31,7 @@ POST /projects/:id/export | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `description` | string | no | Overrides the project description | | `upload` | hash | no | Hash that contains the information to upload the exported project to a web server | | `upload[url]` | string | yes | The URL to upload the project | @@ -62,7 +62,7 @@ GET /projects/:id/export | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/export" @@ -110,7 +110,7 @@ GET /projects/:id/export/download | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \ @@ -258,7 +258,7 @@ GET /projects/:id/import | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/import" diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 0b7193ad5bc..e596b25ca22 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -17,7 +17,7 @@ GET /projects/:id/variables | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID of a project or [URL-encoded 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 [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" @@ -48,7 +48,7 @@ GET /projects/:id/variables/:key | Attribute | Type | required | Description | |-----------|---------|----------|-----------------------| -| `id` | integer/string | yes | The ID of a project or [URL-encoded 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 [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | @@ -76,7 +76,7 @@ POST /projects/:id/variables | Attribute | Type | required | Description | |---------------------|---------|----------|-----------------------| -| `id` | integer/string | yes | The ID of a project or [URL-encoded 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 [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.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 | | `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` | @@ -110,7 +110,7 @@ PUT /projects/:id/variables/:key | Attribute | Type | required | Description | |---------------------|---------|----------|-------------------------| -| `id` | integer/string | yes | The ID of a project or [URL-encoded 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 [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` 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` | @@ -145,7 +145,7 @@ DELETE /projects/:id/variables/:key | Attribute | Type | required | Description | |-----------|---------|----------|-------------------------| -| `id` | integer/string | yes | The ID of a project or [URL-encoded 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 [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index 31c306bb14f..fe2750fa4bf 100644 --- a/doc/api/project_repository_storage_moves.md +++ b/doc/api/project_repository_storage_moves.md @@ -16,19 +16,19 @@ for example. As project repository storage moves are processed, they transition through different states. Values of `state` are: -- `initial` -- `scheduled` -- `started` -- `finished` -- `failed` -- `replicated` -- `cleanup failed` +- `initial`: The record has been created but the background job has not yet been scheduled. +- `scheduled`: The background job has been scheduled. +- `started`: The project repositories are being copied to the destination storage. +- `replicated`: The project has been moved. +- `failed`: The project repositories failed to copy or the checksums did not match. +- `finished`: The project has been moved and the repositories on the source storage have been deleted. +- `cleanup failed`: The project has been moved but the repositories on the source storage could not be deleted. To ensure data integrity, projects are put in a temporary read-only state for the duration of the move. During this time, users receive a `The repository is temporarily read-only. Please try again later.` message if they try to push new commits. -This API requires you to [authenticate yourself](README.md#authentication) as an administrator. +This API requires you to [authenticate yourself](index.md#authentication) as an administrator. For other repository types see: @@ -42,7 +42,7 @@ GET /project_repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](README.md#pagination). +are [paginated](index.md#pagination). Example request: @@ -80,7 +80,7 @@ GET /projects/:project_id/repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](README.md#pagination). +are [paginated](index.md#pagination). Parameters: diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 156d3c57a43..0ac2297e3c1 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -36,7 +36,7 @@ GET /projects/:id/snippets Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user ## Single snippet @@ -48,7 +48,7 @@ GET /projects/:id/snippets/:snippet_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project's snippet ```json @@ -85,7 +85,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------------|:----------------|:---------|:----------------------------------------------------------------------------------------------------------------| -| `id` | integer | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | Title of a snippet | | `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | | `content` | string | no | Deprecated: Use `files` instead. Content of a snippet | @@ -132,7 +132,7 @@ Parameters: | Attribute | Type | Required | Description | |:----------------------|:----------------|:---------|:----------------------------------------------------------------------------------------------------------------| -| `id` | integer | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `snippet_id` | integer | yes | The ID of a project's snippet | | `title` | string | no | Title of a snippet | | `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | @@ -183,7 +183,7 @@ DELETE /projects/:id/snippets/:snippet_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project's snippet Example request: @@ -203,7 +203,7 @@ GET /projects/:id/snippets/:snippet_id/raw Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project's snippet Example request: @@ -223,7 +223,7 @@ GET /projects/:id/snippets/:snippet_id/files/:ref/:file_path/raw Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project's snippet - `ref` (required) - The name of a branch, tag or commit, such as `main` - `file_path` (required) - The URL-encoded path to the file, such as `snippet%2Erb` @@ -247,7 +247,7 @@ GET /projects/:id/snippets/:snippet_id/user_agent_detail | Attribute | Type | Required | Description | |---------------|---------|----------|--------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | | `snippet_id` | Integer | yes | The ID of a snippet | Example request: diff --git a/doc/api/project_statistics.md b/doc/api/project_statistics.md index 6a987b60f64..a16bcc513f9 100644 --- a/doc/api/project_statistics.md +++ b/doc/api/project_statistics.md @@ -21,7 +21,7 @@ GET /projects/:id/statistics | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `id` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer / string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | Example response: diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index 186b6a956a4..d4af0e8d78d 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -33,7 +33,7 @@ GET /projects/:id/templates/:type | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `id` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer / string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `type` | string | yes | The type of the template. Accepted values are: `dockerfiles`, `gitignores`, `gitlab_ci_ymls`, `licenses`, `issues`, `merge_requests` | Example response (licenses): @@ -99,7 +99,7 @@ GET /projects/:id/templates/:type/:name | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `id` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer / string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `type` | string | yes| The type of the template. One of: `dockerfiles`, `gitignores`, `gitlab_ci_ymls`, `licenses`, `issues`, or `merge_requests`. | | `name` | string | yes | The key of the template, as obtained from the collection endpoint | | `source_template_project_id` | integer | no | The project ID where a given template is being stored. This is useful when multiple templates from different projects have the same name. If multiple templates have the same name, the match from `closest ancestor` is returned if `source_template_project_id` is not specified | diff --git a/doc/api/project_vulnerabilities.md b/doc/api/project_vulnerabilities.md index 969ebe1f9c6..2035d17aa3f 100644 --- a/doc/api/project_vulnerabilities.md +++ b/doc/api/project_vulnerabilities.md @@ -14,7 +14,7 @@ This API is in an alpha stage and considered unstable. The response payload may be subject to change or breakage across GitLab releases. -Every API call to vulnerabilities must be [authenticated](README.md#authentication). +Every API call to vulnerabilities must be [authenticated](index.md#authentication). Vulnerability permissions inherit permissions from their project. If a project is private, and a user isn't a member of the project to which the vulnerability @@ -24,7 +24,7 @@ belongs, requests to that project returns a `404 Not Found` status code. API results are paginated, and `GET` requests return 20 results at a time by default. -Read more on [pagination](README.md#pagination). +Read more on [pagination](index.md#pagination). ## List project vulnerabilities @@ -40,7 +40,7 @@ GET /projects/:id/vulnerabilities | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/vulnerabilities" @@ -117,7 +117,7 @@ POST /projects/:id/vulnerabilities?finding_id=<your_finding_id> | Attribute | Type | Required | Description | | ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) which the authenticated user is a member of | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) which the authenticated user is a member of | | `finding_id` | integer or string | yes | The ID of a Vulnerability Finding to create the new Vulnerability from | The other attributes of a newly created Vulnerability are populated from diff --git a/doc/api/projects.md b/doc/api/projects.md index e5cb2c8e1eb..72de8ab6844 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -4,7 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Projects API +# Projects API **(FREE)** + +Interact with [projects](../user/project/index.md) using the REST API. ## Project visibility level @@ -58,7 +60,7 @@ GET /projects | `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | -| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. | +| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | | `topic` | string | **{dotted-circle}** No | Comma-separated topic names. Limit results to projects that match all of given topics. See `topics` attribute. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | | `wiki_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2). | @@ -67,7 +69,7 @@ GET /projects | `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | | `with_programming_language` | string | **{dotted-circle}** No | Limit by projects which use the given programming language. | -This endpoint supports [keyset pagination](README.md#keyset-based-pagination) +This endpoint supports [keyset pagination](index.md#keyset-based-pagination) for selected `order_by` options. When `simple=true` or the user is unauthenticated this returns something like: @@ -345,9 +347,9 @@ GET /projects?custom_attributes[key]=value&custom_attributes[other_key]=other_va ### Pagination limits -In GitLab 13.0 and later, [offset-based pagination](README.md#offset-based-pagination) +In GitLab 13.0 and later, [offset-based pagination](index.md#offset-based-pagination) is [limited to 50,000 records](https://gitlab.com/gitlab-org/gitlab/-/issues/34565). -[Keyset pagination](README.md#keyset-based-pagination) is required to retrieve +[Keyset pagination](index.md#keyset-based-pagination) is required to retrieve projects beyond this limit. Keyset pagination supports only `order_by=id`. Other sorting options aren't available. @@ -357,7 +359,7 @@ Keyset pagination supports only `order_by=id`. Other sorting options aren't avai Get a list of visible projects owned by the given user. When accessed without authentication, only public projects are returned. -This endpoint supports [keyset pagination](README.md#keyset-based-pagination) +This endpoint supports [keyset pagination](index.md#keyset-based-pagination) for selected `order_by` options. ```plaintext @@ -377,7 +379,7 @@ GET /users/:user_id/projects | `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | -| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. | +| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | | `user_id` | string | **{check-circle}** Yes | The ID or username of the user. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | @@ -610,7 +612,7 @@ GET /users/:user_id/starred_projects | `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned.. | | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | -| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. | +| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | | `user_id` | string | **{check-circle}** Yes | The ID or username of the user. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | @@ -827,9 +829,9 @@ GET /projects/:id | Attribute | Type | Required | Description | |--------------------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `license` | boolean | **{dotted-circle}** No | Include project license data. | -| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. | +| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | ```json @@ -1080,7 +1082,7 @@ GET /projects/:id/users | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific users. | | `skip_users` | integer array | **{dotted-circle}** No | Filter out users with the specified IDs. | @@ -1115,7 +1117,7 @@ GET /projects/:id/groups | Attribute | Type | Required | Description | |-----------------------------|-------------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific groups. | | `skip_groups` | array of integers | **{dotted-circle}** No | Skip the group IDs passed. | | `with_shared` | boolean | **{dotted-circle}** No | Include projects shared with this group. Default is `false`. | @@ -1326,7 +1328,7 @@ PUT /projects/:id | `build_timeout` | integer | **{dotted-circle}** No | The maximum amount of time, in seconds, that a job can run. | | `builds_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `ci_config_path` | string | **{dotted-circle}** No | The path to CI configuration file. | -| `ci_default_git_depth` | integer | **{dotted-circle}** No | Default number of revisions for [shallow cloning](../ci/pipelines/settings.md#git-shallow-clone). | +| `ci_default_git_depth` | integer | **{dotted-circle}** No | Default number of revisions for [shallow cloning](../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone). | | `ci_forward_deployment_enabled` | boolean | **{dotted-circle}** No | When a new deployment job starts, [skip older deployment jobs](../ci/pipelines/settings.md#skip-outdated-deployment-jobs) that are still pending | | `container_expiration_policy_attributes` | hash | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). | | `container_registry_enabled` | boolean | **{dotted-circle}** No | Enable container registry for this project. | @@ -1335,7 +1337,7 @@ PUT /projects/:id | `emails_disabled` | boolean | **{dotted-circle}** No | Disable email notifications. | | `external_authorization_classification_label` **(PREMIUM)** | string | **{dotted-circle}** No | The classification label for the project. | | `forking_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `import_url` | string | **{dotted-circle}** No | URL to import repository from. | | `issues_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `issues_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable issues for this project. Use `issues_access_level` instead. | @@ -1394,7 +1396,7 @@ POST /projects/:id/fork | Attribute | Type | Required | Description | |------------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `name` | string | **{dotted-circle}** No | The name assigned to the resultant project after forking. | | `namespace_id` | integer | **{dotted-circle}** No | The ID of the namespace that the project is forked to. | | `namespace_path` | string | **{dotted-circle}** No | The path of the namespace that the project is forked to. | @@ -1417,7 +1419,7 @@ GET /projects/:id/forks | Attribute | Type | Required | Description | |-------------------------------|----------------|------------------------|-------------| | `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | | `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [access level](members.md#valid-access-levels). | | `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | @@ -1426,7 +1428,7 @@ GET /projects/:id/forks | `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | -| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. | +| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | | `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | @@ -1523,7 +1525,7 @@ POST /projects/:id/star | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/star" @@ -1621,7 +1623,7 @@ POST /projects/:id/unstar | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unstar" @@ -1719,7 +1721,7 @@ GET /projects/:id/starrers | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific users. | ```shell @@ -1765,7 +1767,7 @@ GET /projects/:id/languages | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/languages" @@ -1794,7 +1796,7 @@ POST /projects/:id/archive | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/archive" @@ -1913,7 +1915,7 @@ POST /projects/:id/unarchive | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unarchive" @@ -2044,7 +2046,7 @@ DELETE /projects/:id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ## Restore project marked for deletion **(PREMIUM)** @@ -2058,7 +2060,7 @@ POST /projects/:id/restore | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ## Upload a file @@ -2073,7 +2075,7 @@ POST /projects/:id/uploads | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `file` | string | **{check-circle}** Yes | The file to be uploaded. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | To upload a file from your file system, use the `--form` argument. This causes cURL to post data using the header `Content-Type: multipart/form-data`. The @@ -2147,7 +2149,7 @@ PUT /projects/:id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `avatar` | string | **{check-circle}** Yes | The file to be uploaded. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | To upload an avatar from your file system, use the `--form` argument. This causes cURL to post data using the header `Content-Type: multipart/form-data`. The @@ -2182,7 +2184,7 @@ POST /projects/:id/share | `expires_at` | string | **{dotted-circle}** No | Share expiration date in ISO 8601 format: 2016-09-26 | | `group_access` | integer | **{check-circle}** Yes | The [access level](members.md#valid-access-levels) to grant the group. | | `group_id` | integer | **{check-circle}** Yes | The ID of the group to share with. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ## Delete a shared project link within a group @@ -2195,7 +2197,7 @@ DELETE /projects/:id/share/:group_id | Attribute | Type | Required | Description | |------------|----------------|------------------------|-------------| | `group_id` | integer | **{check-circle}** Yes | The ID of the group. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17" @@ -2216,7 +2218,7 @@ GET /projects/:id/hooks | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ### Get project hook @@ -2229,7 +2231,7 @@ GET /projects/:id/hooks/:hook_id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|---------------------------| | `hook_id` | integer | **{check-circle}** Yes | The ID of a project hook. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ```json { @@ -2268,7 +2270,7 @@ POST /projects/:id/hooks | `confidential_note_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential note events. | | `deployment_events` | boolean | **{dotted-circle}** No | Trigger hook on deployment events. | | `enable_ssl_verification` | boolean | **{dotted-circle}** No | Do SSL verification when triggering the hook. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `issues_events` | boolean | **{dotted-circle}** No | Trigger hook on issues events. | | `job_events` | boolean | **{dotted-circle}** No | Trigger hook on job events. | | `merge_requests_events` | boolean | **{dotted-circle}** No | Trigger hook on merge requests events. | @@ -2296,7 +2298,7 @@ PUT /projects/:id/hooks/:hook_id | `deployment_events` | boolean | **{dotted-circle}** No | Trigger hook on deployment events. | | `enable_ssl_verification` | boolean | **{dotted-circle}** No | Do SSL verification when triggering the hook. | | `hook_id` | integer | **{check-circle}** Yes | The ID of the project hook. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `issues_events` | boolean | **{dotted-circle}** No | Trigger hook on issues events. | | `job_events` | boolean | **{dotted-circle}** No | Trigger hook on job events. | | `merge_requests_events` | boolean | **{dotted-circle}** No | Trigger hook on merge requests events. | @@ -2322,7 +2324,7 @@ DELETE /projects/:id/hooks/:hook_id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `hook_id` | integer | **{check-circle}** Yes | The ID of the project hook. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | Note the JSON response differs if the hook is available or not. If the project hook is available before it's returned in the JSON response or an empty response @@ -2342,7 +2344,7 @@ POST /projects/:id/fork/:forked_from_id | Attribute | Type | Required | Description | |------------------|----------------|------------------------|-------------| | `forked_from_id` | ID | **{check-circle}** Yes | The ID of the project that was forked from. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ### Delete an existing forked from relationship @@ -2352,7 +2354,7 @@ DELETE /projects/:id/fork | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ## Search for projects by name @@ -2382,7 +2384,7 @@ POST /projects/:id/housekeeping | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ## Push Rules **(PREMIUM)** @@ -2397,7 +2399,7 @@ GET /projects/:id/push_rule | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | ```json { @@ -2449,7 +2451,7 @@ POST /projects/:id/push_rule | `commit_message_regex` | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | **{dotted-circle}** No | Deny deleting a tag. | | `file_name_regex` | string | **{dotted-circle}** No | All committed filenames must **not** match this, for example `(jar|exe)$`. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding), | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding), | | `max_file_size` | integer | **{dotted-circle}** No | Maximum file size (MB). | | `member_check` | boolean | **{dotted-circle}** No | Restrict commits by author (email) to existing GitLab users. | | `prevent_secrets` | boolean | **{dotted-circle}** No | GitLab rejects any files that are likely to contain secrets. | @@ -2472,7 +2474,7 @@ PUT /projects/:id/push_rule | `commit_message_regex` | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | **{dotted-circle}** No | Deny deleting a tag. | | `file_name_regex` | string | **{dotted-circle}** No | All committed filenames must **not** match this, for example `(jar|exe)$`. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `max_file_size` | integer | **{dotted-circle}** No | Maximum file size (MB). | | `member_check` | boolean | **{dotted-circle}** No | Restrict commits by author (email) to existing GitLab users. | | `prevent_secrets` | boolean | **{dotted-circle}** No | GitLab rejects any files that are likely to contain secrets. | @@ -2491,7 +2493,7 @@ DELETE /projects/:id/push_rule | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ## Transfer a project to a new namespace @@ -2503,7 +2505,7 @@ PUT /projects/:id/transfer | Attribute | Type | Required | Description | |-------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `namespace` | integer or string | **{check-circle}** Yes | The ID or path of the namespace to transfer to project to. | Example request: @@ -2653,7 +2655,7 @@ POST /projects/:id/mirror/pull | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/mirror/pull" @@ -2682,7 +2684,7 @@ GET /projects/:id/snapshot | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `wiki` | boolean | **{dotted-circle}** No | Whether to download the wiki, rather than project, repository. | ## Get the path to repository storage @@ -2697,7 +2699,7 @@ GET /projects/:id/storage | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | ```json [ diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 2fe821a7758..a75090c90d5 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -30,7 +30,7 @@ GET /projects/:id/protected_branches | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `search` | string | no | Name or part of the name of protected branches to be searched for | ```shell @@ -124,7 +124,7 @@ GET /projects/:id/protected_branches/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch or wildcard | ```shell @@ -199,7 +199,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.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`, Maintainer role) | | `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, Maintainer role) | @@ -280,7 +280,7 @@ Example response: ### Example with user / group level access **(PREMIUM)** Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the -form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md#restricting-push-and-merge-access-to-certain-users) and were [added to the API](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3516) in GitLab 10.3 EE. +form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md). ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&allowed_to_push%5B%5D%5Buser_id%5D=1" @@ -399,7 +399,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch | ## Require code owner approvals for a single branch @@ -416,6 +416,6 @@ curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitl | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch | | `code_owner_approval_required` | boolean | no | **(PREMIUM)** Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). (defaults: false)| diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index 52fcdad1ad6..9a64e676ad9 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -30,7 +30,7 @@ GET /projects/:id/protected_environments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_environments/" @@ -64,7 +64,7 @@ GET /projects/:id/protected_environments/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the protected environment | ```shell @@ -104,7 +104,7 @@ curl --header 'Content-Type: application/json' --request POST \ | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `name` | string | yes | The name of the environment. | | `deploy_access_levels` | array | yes | Array of access levels allowed to deploy, with each described by a hash. | @@ -143,5 +143,5 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `name` | string | yes | The name of the protected environment. | diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md index e04f418258d..7a46a2dbf12 100644 --- a/doc/api/protected_tags.md +++ b/doc/api/protected_tags.md @@ -30,7 +30,7 @@ GET /projects/:id/protected_tags | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_tags" @@ -64,7 +64,7 @@ GET /projects/:id/protected_tags/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the tag or wildcard | ```shell @@ -100,7 +100,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the tag or wildcard | | `create_access_level` | string | no | Access levels allowed to create (defaults: `40`, Maintainer role) | @@ -132,5 +132,5 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the tag | diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index 0cbf613c598..cb688b81336 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -12,6 +12,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Release Evidences were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.5. > - `description_html` became an opt-in field [with GitLab 13.12 for performance reasons](https://gitlab.com/gitlab-org/gitlab/-/issues/299447). Please pass the `include_html_description` query string parameter if you need it. +> - [The permission model for create, update and delete actions was fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/327505) in GitLab 14.1. + See [Release permissions](../../user/project/releases/index.md#release-permissions) for more information. ## List Releases @@ -23,7 +25,7 @@ GET /projects/:id/releases | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | | `order_by` | string | no | The field to use as order. Either `released_at` (default) or `created_at`. | | `sort` | string | no | The direction of the order. Either `desc` (default) for descending order or `asc` for ascending order. | | `include_html_description` | boolean | no | If `true`, a response includes HTML rendered Markdown of the release description. | @@ -228,7 +230,7 @@ GET /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | | `include_html_description` | boolean | no | If `true`, a response includes HTML rendered Markdown of the release description. | @@ -359,7 +361,7 @@ POST /projects/:id/releases | Attribute | Type | Required | Description | | -------------------| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | | `name` | string | no | The release name. | | `tag_name` | string | yes | The tag where the release is created from. | | `description` | string | no | The description of the release. You can use [Markdown](../../user/markdown.md). | @@ -507,7 +509,7 @@ POST /projects/:id/releases/:tag_name/evidence | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | Example request: @@ -532,7 +534,7 @@ PUT /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | | `name` | string | no | The release name. | | `description` | string | no | The description of the release. You can use [Markdown](../../user/markdown.md). | @@ -639,7 +641,7 @@ DELETE /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | Example request: diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index f4a2df5558f..2f8dc363124 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -21,7 +21,7 @@ GET /projects/:id/releases/:tag_name/assets/links | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag associated with the Release. | Example request: @@ -61,7 +61,7 @@ GET /projects/:id/releases/:tag_name/assets/links/:link_id | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag associated with the Release. | | `link_id` | integer | yes | The ID of the link. | @@ -93,7 +93,7 @@ POST /projects/:id/releases/:tag_name/assets/links | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag associated with the Release. | | `name` | string | yes | The name of the link. Link names must be unique within the release. | | `url` | string | yes | The URL of the link. Link URLs must be unique within the release. | @@ -134,7 +134,7 @@ PUT /projects/:id/releases/:tag_name/assets/links/:link_id | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag associated with the Release. | | `link_id` | integer | yes | The ID of the link. | | `name` | string | no | The name of the link. | @@ -175,7 +175,7 @@ DELETE /projects/:id/releases/:tag_name/assets/links/:link_id | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag associated with the Release. | | `link_id` | integer | yes | The ID of the link. | diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md index 5e5b44fec8a..799763a7da3 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.md @@ -7,7 +7,7 @@ type: reference, api # Project remote mirrors API **(FREE)** -[Push mirrors](../user/project/repository/repository_mirroring.md#pushing-to-a-remote-repository) +[Push mirrors](../user/project/repository/repository_mirroring.md#push-to-a-remote-repository) defined on a project's repository settings are called "remote mirrors", and the state of these mirrors can be queried and modified via the remote mirror API outlined below. diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 1868f33373c..7e50a2c9f4c 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -22,11 +22,11 @@ Supported attributes: | Attribute | Type | Required | Description | | :---------- | :------------- | :------- | :---------- | -| `id` | integer/string | no | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | no | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `path` | string | yes | The path inside repository. Used to get content of subdirectories. | | `ref` | string | yes | The name of a repository branch or tag or if not given the default branch. | | `recursive` | boolean | yes | Boolean value used to get a recursive tree (false by default). | -| `per_page` | integer | yes | Number of results to show per page. If not specified, defaults to `20`. [Learn more on pagination](README.md#pagination). | +| `per_page` | integer | yes | Number of results to show per page. If not specified, defaults to `20`. [Learn more on pagination](index.md#pagination). | ```json [ @@ -96,7 +96,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :-------- | :------------- | :------- | :---------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `sha` | string | yes | The blob SHA. | ## Raw blob content @@ -112,7 +112,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :-------- | :------- | :------- | :---------- | -| `id` | datatype | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | datatype | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `sha` | datatype | yes | The blob SHA. | ## Get file archive @@ -137,7 +137,7 @@ Supported attributes: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:----------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `sha` | string | no | The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. | Example request: @@ -159,7 +159,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :--------- | :------------- | :------- | :---------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `from` | string | yes | The commit SHA or branch name. | | `to` | string | yes | The commit SHA or branch name. | | `from_project_id` | integer | no | The ID to compare from | @@ -220,7 +220,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :--------- | :------------- | :------- | :---------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user. | | `order_by` | string | no | Return contributors ordered by `name`, `email`, or `commits` (orders by commit date) fields. Default is `commits`. | | `sort` | string | no | Return contributors sorted in `asc` or `desc` order. Default is `asc`. | @@ -252,7 +252,7 @@ GET /projects/:id/repository/merge_base | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `refs` | array | yes | The refs to find the common ancestor of, multiple refs can be passed | Example request: @@ -313,7 +313,7 @@ Supported attributes: WARNING: GitLab treats trailers case-sensitively. If you set the `trailer` field to -`Example`, GitLab _won't_ include commits that use the trailer `example`, +`Example`, GitLab _won't_ include commits that use the trailer `example`, `eXaMpLE`, or anything else that isn't _exactly_ `Example`. If the `from` attribute is unspecified, GitLab uses the Git tag of the last diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md index 1d7ca903fee..06f9e514009 100644 --- a/doc/api/repository_submodules.md +++ b/doc/api/repository_submodules.md @@ -22,7 +22,7 @@ PUT /projects/:id/repository/submodules/:submodule | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `submodule` | string | yes | URL-encoded full path to the submodule. For example, `lib%2Fclass%2Erb` | | `branch` | string | yes | Name of the branch to commit into | | `commit_sha` | string | yes | Full commit SHA to update the submodule to | diff --git a/doc/api/resource_access_tokens.md b/doc/api/resource_access_tokens.md index 3b443dbb8f8..3532cfda47b 100644 --- a/doc/api/resource_access_tokens.md +++ b/doc/api/resource_access_tokens.md @@ -20,7 +20,7 @@ GET projects/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens" @@ -38,7 +38,8 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a "id" : 42, "active" : true, "created_at" : "2021-01-20T22:11:48.151Z", - "revoked" : false + "revoked" : false, + "access_level": 40 } ] ``` @@ -55,15 +56,16 @@ POST projects/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `name` | String | yes | The name of the project access token | | `scopes` | `Array[String]` | yes | [List of scopes](../user/project/settings/project_access_tokens.md#limiting-scopes-of-a-project-access-token) | +| `access_level` | Integer | no | A valid access level. Default value is 40 (Maintainer). Other allowed values are 10 (Guest), 20 (Reporter), and 30 (Developer). | | `expires_at` | Date | no | The token expires at midnight UTC on that date | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ --header "Content-Type:application/json" \ ---data '{ "name":"test_token", "scopes":["api", "read_repository"], "expires_at":"2021-01-31" }' \ +--data '{ "name":"test_token", "scopes":["api", "read_repository"], "expires_at":"2021-01-31", "access_level": 30 }' \ "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens" ``` @@ -80,7 +82,8 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ "user_id" : 166, "id" : 58, "expires_at" : "2021-01-31", - "token" : "D4y...Wzr" + "token" : "D4y...Wzr", + "access_level": 30 } ``` @@ -96,7 +99,7 @@ DELETE projects/:id/access_tokens/:token_id | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `token_id` | integer or string | yes | The ID of the project access token | ```shell diff --git a/doc/api/resource_iteration_events.md b/doc/api/resource_iteration_events.md index 91c7a1b07ea..f4463a4746d 100644 --- a/doc/api/resource_iteration_events.md +++ b/doc/api/resource_iteration_events.md @@ -26,7 +26,7 @@ GET /projects/:id/issues/:issue_iid/resource_iteration_events | Attribute | Type | Required | Description | | ----------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | Example request: @@ -108,7 +108,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | | `issue_iid` | integer | yes | The IID of an issue | | `resource_iteration_event_id` | integer | yes | The ID of an iteration event | diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index 5fc7a0a52bd..c5292059c0f 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.md @@ -21,7 +21,7 @@ GET /projects/:id/issues/:issue_iid/resource_label_events | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | ```json @@ -87,7 +87,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `resource_label_event_id` | integer | yes | The ID of a label event | @@ -107,7 +107,7 @@ GET /groups/:id/epics/:epic_id/resource_label_events | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | ```json @@ -173,7 +173,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `resource_label_event_id` | integer | yes | The ID of a label event | @@ -193,7 +193,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/resource_label_events | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | ```json @@ -259,7 +259,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `resource_label_event_id` | integer | yes | The ID of a label event | diff --git a/doc/api/resource_milestone_events.md b/doc/api/resource_milestone_events.md index df51584a4ed..75ecd986e4c 100644 --- a/doc/api/resource_milestone_events.md +++ b/doc/api/resource_milestone_events.md @@ -4,12 +4,12 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Resource milestone events API +# Resource milestone events API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31720) in GitLab 13.1. -Resource milestone events keep track of what happens to GitLab [issues](../user/project/issues/) and -[merge requests](../user/project/merge_requests/). +Resource [milestone](../user/project/milestones/index.md) events keep track of what happens to +GitLab [issues](../user/project/issues/) and [merge requests](../user/project/merge_requests/). Use them to track which milestone was added or removed, who did it, and when it happened. @@ -25,7 +25,7 @@ GET /projects/:id/issues/:issue_iid/resource_milestone_events | Attribute | Type | Required | Description | | ----------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | Example request: @@ -109,7 +109,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | | `issue_iid` | integer | yes | The IID of an issue | | `resource_milestone_event_id` | integer | yes | The ID of a milestone event | @@ -131,7 +131,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/resource_milestone_events | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | | `merge_request_iid` | integer | yes | The IID of a merge request | Example request: @@ -215,7 +215,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `resource_milestone_event_id` | integer | yes | The ID of a milestone event | diff --git a/doc/api/resource_state_events.md b/doc/api/resource_state_events.md index e81b7ddd272..950d82a92a4 100644 --- a/doc/api/resource_state_events.md +++ b/doc/api/resource_state_events.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Resource state events API +# Resource state events API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35210/) in GitLab 13.2. @@ -25,7 +25,7 @@ GET /projects/:id/issues/:issue_iid/resource_state_events | Attribute | Type | Required | Description | | ----------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | Example request: @@ -83,7 +83,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | | `issue_iid` | integer | yes | The IID of an issue | | `resource_state_event_id` | integer | yes | The ID of a state event | @@ -125,7 +125,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/resource_state_events | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | | `merge_request_iid` | integer | yes | The IID of a merge request | Example request: @@ -183,7 +183,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `resource_state_event_id` | integer | yes | The ID of a state event | diff --git a/doc/api/resource_weight_events.md b/doc/api/resource_weight_events.md index 44c20c5bca8..8f11f0c984b 100644 --- a/doc/api/resource_weight_events.md +++ b/doc/api/resource_weight_events.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Resource weight events API +# Resource weight events API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32542) in GitLab 13.2. @@ -24,7 +24,7 @@ GET /projects/:id/issues/:issue_iid/resource_weight_events | Attribute | Type | Required | Description | | ----------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | Example request: @@ -80,7 +80,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | | `issue_iid` | integer | yes | The IID of an issue | | `resource_weight_event_id` | integer | yes | The ID of a weight event | diff --git a/doc/api/runners.md b/doc/api/runners.md index 951e72edcb5..9e48331cdea 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -14,7 +14,7 @@ There are two tokens to take into account when connecting a runner with GitLab. | Token | Description | | ----- | ----------- | -| Registration token | Token used to [register the runner](https://docs.gitlab.com/runner/register/). It can be [obtained through GitLab](../ci/runners/README.md). | +| Registration token | Token used to [register the runner](https://docs.gitlab.com/runner/register/). It can be [obtained through GitLab](../ci/runners/index.md). | | Authentication token | Token used to authenticate the runner with the GitLab instance. It is obtained either automatically when [registering a runner](https://docs.gitlab.com/runner/register/), or manually when [registering the runner via the Runner API](#register-a-new-runner). | Here's an example of how the two tokens are used in runner registration: @@ -164,7 +164,7 @@ Example response: Get details of a runner. -The [Maintainer role or higher](../user/permissions.md) is required to get runner details at the +At least the [Maintainer role](../user/permissions.md) is required to get runner details at the project and group level. Instance-level runner details via this endpoint are available to all signed in users. @@ -410,7 +410,7 @@ GET /projects/:id/runners?tag_list=tag1,tag2 | Attribute | Type | Required | Description | |------------|----------------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided | | `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | | `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | @@ -459,7 +459,7 @@ POST /projects/:id/runners | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `runner_id` | integer | yes | The ID of a runner | ```shell @@ -495,7 +495,7 @@ DELETE /projects/:id/runners/:runner_id | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `runner_id` | integer | yes | The ID of a runner | ```shell diff --git a/doc/api/search.md b/doc/api/search.md index 9714bc17f62..d3a2f9c41b6 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -444,7 +444,7 @@ GET /groups/:id/search | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `scope` | string | yes | The scope to search in | | `search` | string | yes | The search query | | `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | @@ -836,7 +836,7 @@ GET /projects/:id/search | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `scope` | string | yes | The scope to search in | | `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. | diff --git a/doc/api/services.md b/doc/api/services.md index 0a26a88de70..3652dd99fcd 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -258,7 +258,8 @@ GET /projects/:id/services/buildkite ## Campfire -Simple web-based real-time group chat +Send notifications about push events to Campfire chat rooms. +Note that [new users can no longer sign up for Campfire](https://basecamp.com/retired/campfire). ### Create/Edit Campfire service @@ -270,12 +271,12 @@ PUT /projects/:id/services/campfire Parameters: -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `token` | string | true | Campfire token | -| `subdomain` | string | false | Campfire subdomain | -| `room` | string | false | Campfire room | -| `push_events` | boolean | false | Enable notifications for push events | +| Parameter | Type | Required | Description | +|---------------|---------|----------|---------------------------------------------------------------------------------------------| +| `token` | string | true | Campfire API token. To find it, log into Campfire and select **My info**. | +| `subdomain` | string | false | Campfire subdomain. Text between `https://` and `.campfirenow.com` when you're logged in. | +| `room` | string | false | Campfire room. The last part of the URL when you're in a room. | +| `push_events` | boolean | false | Enable notifications for push events. | ### Delete Campfire service @@ -955,13 +956,15 @@ Get Pipeline-Emails service settings for a project. GET /projects/:id/services/pipelines-email ``` -## PivotalTracker +## Pivotal Tracker -Project Management Software (Source Commits Endpoint) +Add commit messages as comments to Pivotal Tracker stories. + +See also the [Pivotal Tracker service documentation](../user/project/integrations/pivotal_tracker.md). -### Create/Edit PivotalTracker service +### Create/Edit Pivotal Tracker service -Set PivotalTracker service for a project. +Set Pivotal Tracker service for a project. ```plaintext PUT /projects/:id/services/pivotaltracker @@ -971,21 +974,21 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `token` | string | true | The PivotalTracker token | +| `token` | string | true | The Pivotal Tracker token | | `restrict_to_branch` | boolean | false | Comma-separated list of branches to automatically inspect. Leave blank to include all branches. | | `push_events` | boolean | false | Enable notifications for push events | -### Delete PivotalTracker service +### Delete Pivotal Tracker service -Delete PivotalTracker service for a project. +Delete Pivotal Tracker service for a project. ```plaintext DELETE /projects/:id/services/pivotaltracker ``` -### Get PivotalTracker service settings +### Get Pivotal Tracker service settings -Get PivotalTracker service settings for a project. +Get Pivotal Tracker service settings for a project. ```plaintext GET /projects/:id/services/pivotaltracker diff --git a/doc/api/settings.md b/doc/api/settings.md index 8225713fc00..d49dca96dfd 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -258,7 +258,7 @@ listed in the descriptions of the relevant settings. | `disabled_oauth_sign_in_sources` | array of strings | no | Disabled OAuth sign-in sources. | | `dns_rebinding_protection_enabled` | boolean | no | Enforce DNS rebinding attack protection. | | `domain_denylist_enabled` | boolean | no | (**If enabled, requires:** `domain_denylist`) Allows blocking sign-ups from emails from specific domains. | -| `domain_denylist` | array of strings | no | Users with e-mail addresses that match these domain(s) **cannot** sign up. Wildcards allowed. Use separate lines for multiple entries. Ex: `domain.com`, `*.domain.com`. | +| `domain_denylist` | array of strings | no | Users with email addresses that match these domain(s) **cannot** sign up. Wildcards allowed. Use separate lines for multiple entries. Ex: `domain.com`, `*.domain.com`. | | `domain_allowlist` | array of strings | no | Force people to use only corporate emails for sign-up. Default is `null`, meaning there is no restriction. | | `dsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded DSA key. Default is `0` (no restriction). `-1` disables DSA keys. | | `ecdsa_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ECDSA key. Default is `0` (no restriction). `-1` disables ECDSA keys. | @@ -328,6 +328,8 @@ listed in the descriptions of the relevant settings. | `issues_create_limit` | integer | no | Max number of issue creation requests per minute per user. Disabled by default.| | `keep_latest_artifact` | boolean | no | Prevent the deletion of the artifacts from the most recent successful jobs, regardless of the expiry time. Enabled by default. | | `local_markdown_version` | integer | no | Increase this value when any cached Markdown should be invalidated. | +| `mailgun_signing_key` | string | no | The Mailgun HTTP webhook signing key for receiving events from webhook | +| `mailgun_events_enabled` | boolean | no | Enable Mailgun event receiver. | | `maintenance_mode_message` | string | no | **(PREMIUM)** Message displayed when instance is in maintenance mode. | | `maintenance_mode` | boolean | no | **(PREMIUM)** When instance is in maintenance mode, non-administrative users can sign in with read-only access and make read-only API requests. | | `max_artifacts_size` | integer | no | Maximum artifacts size in MB. | @@ -413,7 +415,7 @@ listed in the descriptions of the relevant settings. | `unique_ips_limit_time_window` | integer | required by: `unique_ips_limit_enabled` | How many seconds an IP is counted towards the limit. | | `usage_ping_enabled` | boolean | no | Every week GitLab reports license usage back to GitLab, Inc. | | `user_default_external` | boolean | no | Newly registered users are external by default. | -| `user_default_internal_regex` | string | no | Specify an e-mail address regex pattern to identify default internal users. | +| `user_default_internal_regex` | string | no | Specify an email address regex pattern to identify default internal users. | | `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider. | | `user_show_add_ssh_key_message` | boolean | no | When set to `false` disable the `You won't be able to pull or push project code via SSH` warning shown to users with no uploaded SSH key. | | `version_check_enabled` | boolean | no | Let GitLab inform you when an update is available. | diff --git a/doc/api/snippet_repository_storage_moves.md b/doc/api/snippet_repository_storage_moves.md index 3454073cc8c..9951e073c39 100644 --- a/doc/api/snippet_repository_storage_moves.md +++ b/doc/api/snippet_repository_storage_moves.md @@ -16,19 +16,19 @@ example. As snippet repository storage moves are processed, they transition through different states. Values of `state` are: -- `initial` -- `scheduled` -- `started` -- `finished` -- `failed` -- `replicated` -- `cleanup failed` +- `initial`: The record has been created but the background job has not yet been scheduled. +- `scheduled`: The background job has been scheduled. +- `started`: The snippet repository is being copied to the destination storage. +- `replicated`: The snippet has been moved. +- `failed`: The snippet repository failed to copy or the checksum did not match. +- `finished`: The snippet has been moved and the repository on the source storage has been deleted. +- `cleanup failed`: The snippet has been moved but the repository on the source storage could not be deleted. To ensure data integrity, snippets are put in a temporary read-only state for the duration of the move. During this time, users receive a `The repository is temporarily read-only. Please try again later.` message if they try to push new commits. -This API requires you to [authenticate yourself](README.md#authentication) as an administrator. +This API requires you to [authenticate yourself](index.md#authentication) as an administrator. For other repository types see: @@ -42,7 +42,7 @@ GET /snippet_repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](README.md#pagination). +are [paginated](index.md#pagination). Example request: @@ -84,7 +84,7 @@ GET /snippets/:snippet_id/repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](README.md#pagination). +are [paginated](index.md#pagination). Supported attributes: diff --git a/doc/api/status_checks.md b/doc/api/status_checks.md index f4e384a2efb..25ccd5d767a 100644 --- a/doc/api/status_checks.md +++ b/doc/api/status_checks.md @@ -7,14 +7,8 @@ type: reference, api # External Status Checks API **(ULTIMATE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0. -> - It's [deployed behind a feature flag](../user/feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-status-checks). **(ULTIMATE SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0, disabled behind the `:ff_external_status_checks` feature flag. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320783) in GitLab 14.1. ## List status checks for a merge request @@ -58,22 +52,16 @@ POST /projects/:id/merge_requests/:merge_request_iid/status_check_responses **Parameters:** -| Attribute | Type | Required | Description | -| ------------------------ | ------- | -------- | -------------------------------------- | -| `id` | integer | yes | ID of a project | -| `merge_request_iid` | integer | yes | IID of a merge request | -| `sha` | string | yes | SHA at `HEAD` of the source branch | +| Attribute | Type | Required | Description | +| -------------------------- | ------- | -------- | ------------------------------------- | +| `id` | integer | yes | ID of a project | +| `merge_request_iid` | integer | yes | IID of a merge request | +| `sha` | string | yes | SHA at `HEAD` of the source branch | +| `external_status_check_id` | integer | yes | ID of an external status check | NOTE: `sha` must be the SHA at the `HEAD` of the merge request's source branch. -## Enable or disable status checks **(ULTIMATE SELF)** - -Status checks are under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) -can enable it. - ## Get project external status checks **(ULTIMATE)** You can request information about a project's external status checks using the following endpoint: @@ -86,7 +74,7 @@ GET /projects/:id/external_status_checks | Attribute | Type | Required | Description | |---------------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer | yes | ID of a project | ```json [ @@ -109,7 +97,7 @@ GET /projects/:id/external_status_checks ] ``` -### Create external status check **(ULTIMATE)** +## Create external status check **(ULTIMATE)** You can create a new external status check for a project using the following endpoint: @@ -117,14 +105,18 @@ You can create a new external status check for a project using the following end POST /projects/:id/external_status_checks ``` -| Attribute | Type | Required | Description | -|------------------------|----------------|----------|----------------------------------------------------| -| `id` | integer | yes | The ID of a project | -| `name` | string | yes | Display name of status check | -| `external_url` | string | yes | URL of status check resource | -| `protected_branch_ids` | `array<Integer>` | no | The ids of protected branches to scope the rule by | +WARNING: +External status checks send information about all applicable merge requests to the +defined external service. This includes confidential merge requests. + +| Attribute | Type | Required | Description | +|------------------------|------------------|----------|------------------------------------------------| +| `id` | integer | yes | ID of a project | +| `name` | string | yes | Display name of status check | +| `external_url` | string | yes | URL of status check resource | +| `protected_branch_ids` | `array<Integer>` | no | IDs of protected branches to scope the rule by | -### Delete external status check **(ULTIMATE)** +## Delete external status check **(ULTIMATE)** You can delete an external status check for a project using the following endpoint: @@ -132,12 +124,12 @@ You can delete an external status check for a project using the following endpoi DELETE /projects/:id/external_status_checks/:check_id ``` -| Attribute | Type | Required | Description | -|------------------------|----------------|----------|----------------------------------------------------| -| `rule_id` | integer | yes | The ID of an status check | -| `id` | integer | yes | The ID of a project | +| Attribute | Type | Required | Description | +|------------------------|----------------|----------|-----------------------| +| `rule_id` | integer | yes | ID of an status check | +| `id` | integer | yes | ID of a project | -### Update external status check **(ULTIMATE)** +## Update external status check **(ULTIMATE)** You can update an existing external status check for a project using the following endpoint: @@ -145,57 +137,14 @@ You can update an existing external status check for a project using the followi PUT /projects/:id/external_status_checks/:check_id ``` -| Attribute | Type | Required | Description | -|------------------------|----------------|----------|----------------------------------------------------| -| `id` | integer | yes | The ID of a project | -| `rule_id` | integer | yes | The ID of an external status check | -| `name` | string | no | Display name of status check | -| `external_url` | string | no | URL of external status check resource | -| `protected_branch_ids` | `array<Integer>` | no | The ids of protected branches to scope the rule by | - -### Enable or disable External Project-level MR status checks **(ULTIMATE SELF)** - -Enable or disable External Project-level MR status checks is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../user/feature_flags.md) -can enable it. - -To enable it: - -```ruby -# For the instance -Feature.enable(:ff_compliance_approval_gates) -# For a single project -Feature.enable(:ff_compliance_approval_gates, Project.find(<project id>)) -``` - -To disable it: - -```ruby -# For the instance -Feature.disable(:ff_compliance_approval_gates) -# For a single project -Feature.disable(:ff_compliance_approval_gates, Project.find(<project id>)) -``` - -To enable it: - -```ruby -# For the instance -Feature.enable(:ff_compliance_approval_gates) -# For a single project -Feature.enable(:ff_compliance_approval_gates, Project.find(<project id>)) -``` - -To disable it: - -```ruby -# For the instance -Feature.disable(:ff_compliance_approval_gates) -# For a single project -Feature.disable(:ff_compliance_approval_gates, Project.find(<project id>) -``` +| Attribute | Type | Required | Description | +|------------------------|------------------|----------|------------------------------------------------| +| `id` | integer | yes | ID of a project | +| `rule_id` | integer | yes | ID of an external status check | +| `name` | string | no | Display name of status check | +| `external_url` | string | no | URL of external status check resource | +| `protected_branch_ids` | `array<Integer>` | no | IDs of protected branches to scope the rule by | ## Related links -- [External status checks](../user/project/merge_requests/status_checks.md) +- [External status checks](../user/project/merge_requests/status_checks.md). diff --git a/doc/api/tags.md b/doc/api/tags.md index 53a981256aa..bbde6c1491b 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -21,7 +21,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user| | `order_by` | string | no | Return tags ordered by `name` or `updated` fields. Default is `updated` | | `sort` | string | no | Return tags sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Return list of tags matching the search criteria. You can use `^term` and `term$` to find tags that begin and end with `term` respectively. | @@ -72,7 +72,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `tag_name` | string | yes | The name of the tag | ```shell @@ -119,7 +119,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `tag_name` | string | yes | The name of a tag | | `ref` | string | yes | Create tag using commit SHA, another tag name, or branch name | | `message` | string | no | Creates annotated tag | @@ -176,5 +176,5 @@ Parameters: | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- | -| `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](index.md#namespaced-path-encoding) owned by the authenticated user | | `tag_name` | string | yes | The name of a tag | diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index 388556d354f..82abe598cf6 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.md @@ -9,7 +9,7 @@ type: reference In GitLab, there is an API endpoint available to work with GitLab CI/CD YMLs. For more information on CI/CD pipeline configuration in GitLab, see the -[configuration reference documentation](../../ci/yaml/README.md). +[configuration reference documentation](../../ci/yaml/index.md). ## List GitLab CI YAML templates diff --git a/doc/api/todos.md b/doc/api/todos.md index 69c0f760a29..737bfb11da9 100644 --- a/doc/api/todos.md +++ b/doc/api/todos.md @@ -4,13 +4,13 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# To dos API +# GitLab To-Do List API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3188) in GitLab 8.10. +Interact with [to-do items](../user/todos.md) using the REST API. -## Get a list of to dos +## Get a list of to-do items -Returns a list of [to-do items](../user/todos.md). When no filter is applied, it +Returns a list of to-do items. When no filter is applied, it returns all pending to-do items for the current user. Different filters allow the user to refine the request. @@ -26,7 +26,7 @@ Parameters: | `author_id` | integer | no | The ID of an author | | `project_id` | integer | no | The ID of a project | | `group_id` | integer | no | The ID of a group | -| `state` | string | no | The state of the to do. Can be either `pending` or `done` | +| `state` | string | no | The state of the to-do item. Can be either `pending` or `done` | | `type` | string | no | The type of to-do item. Can be either `Issue`, `MergeRequest`, `DesignManagement::Design` or `AlertManagement::Alert` | ```shell @@ -190,8 +190,8 @@ Example Response: ## Mark a to-do item as done -Marks a single pending to do given by its ID for the current user as done. The -to do marked as done is returned in the response. +Marks a single pending to-do item given by its ID for the current user as done. The +to-do item marked as done is returned in the response. ```plaintext POST /todos/:id/mark_as_done @@ -287,9 +287,9 @@ Example Response: } ``` -## Mark all to dos as done +## Mark all to-do items as done -Marks all pending to dos for the current user as done. It returns the HTTP status code `204` with an empty response. +Marks all pending to-do items for the current user as done. It returns the HTTP status code `204` with an empty response. ```plaintext POST /todos/mark_as_done diff --git a/doc/api/usage_data.md b/doc/api/usage_data.md index 024caa96565..7a7f36ce43a 100644 --- a/doc/api/usage_data.md +++ b/doc/api/usage_data.md @@ -5,9 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, api --- -# Usage Data API **(FREE SELF)** +# Service Data API **(FREE SELF)** -The Usage Data API is associated with [Usage Ping](../development/usage_ping/index.md). +The Service Data API is associated with [Service Ping](../development/service_ping/index.md). ## Export metric definitions as a single YAML file @@ -48,14 +48,14 @@ Example response: ... ``` -## Export Usage Ping SQL queries +## Export Service Ping SQL queries This action is available only for the GitLab instance [Administrator](../user/permissions.md) users. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57016) in GitLab 13.11. > - [Deployed behind a feature flag](../user/feature_flags.md), disabled by default. -Return all of the raw SQL queries used to compute Usage Ping. +Return all of the raw SQL queries used to compute Service Ping. ```plaintext GET /usage_data/queries @@ -116,7 +116,7 @@ Example response: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57050) in GitLab 13.11. > - [Deployed behind a feature flag](../user/feature_flags.md), disabled by default. -Return all non-SQL metrics data used in the usage ping. +Return all non-SQL metrics data used in the Service ping. Example request: diff --git a/doc/api/users.md b/doc/api/users.md index 0e7b197b106..0d922487cf9 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -1352,7 +1352,7 @@ Parameters: - `id` (required) - ID of specified user - `email` (required) - email address -- `skip_confirmation` (optional) - Skip confirmation and assume e-mail is verified - true or false (default) +- `skip_confirmation` (optional) - Skip confirmation and assume email is verified - true or false (default) ## Delete email for current user diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index c6d883371a3..69e1ea56c2c 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -9,10 +9,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: The GitLab API v3 was removed in [GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819). -For information about the current version of the GitLab API, read the [API documentation](README.md). +For information about the current version of the GitLab API, read the [API documentation](index.md). ## Related links -- [GitLab v3 API documentation](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/8-16-stable/doc/api/README.md) +- [GitLab v3 API documentation](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/8-16-stable/doc/api/index.md) - [Migration guide](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/11-0-stable/doc/api/v3_to_v4.md) from v3 to v4 diff --git a/doc/api/visual_review_discussions.md b/doc/api/visual_review_discussions.md index c3414a4e9ec..8457f63fd38 100644 --- a/doc/api/visual_review_discussions.md +++ b/doc/api/visual_review_discussions.md @@ -26,7 +26,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `body` | string | yes | The content of the thread | | `position` | hash | no | Position when creating a diff note | diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index 5ec769df08c..b18a837de26 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -21,7 +21,7 @@ across GitLab releases. Please use the [GraphQL API](graphql/reference/index.md#queryvulnerabilities) instead. -Every API call to vulnerabilities must be [authenticated](README.md#authentication). +Every API call to vulnerabilities must be [authenticated](index.md#authentication). Vulnerability permissions inherit permissions from their project. If a project is private, and a user isn't a member of the project to which the vulnerability diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index 6d01d7e7d96..4240d363ff0 100644 --- a/doc/api/vulnerability_exports.md +++ b/doc/api/vulnerability_exports.md @@ -13,7 +13,7 @@ This API is in an alpha stage and considered unstable. The response payload may be subject to change or breakage across GitLab releases. -Every API call to vulnerability exports must be [authenticated](README.md#authentication). +Every API call to vulnerability exports must be [authenticated](index.md#authentication). ## Create a project-level vulnerability export @@ -34,7 +34,7 @@ POST /security/projects/:id/vulnerability_exports | Attribute | Type | Required | Description | | ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the project which the authenticated user is a member of | +| `id` | integer or string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project which the authenticated user is a member of | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/projects/1/vulnerability_exports" @@ -80,7 +80,7 @@ POST /security/groups/:id/vulnerability_exports | Attribute | Type | Required | Description | | ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the group which the authenticated user is a member of | +| `id` | integer or string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the group which the authenticated user is a member of | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/groups/1/vulnerability_exports" diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md index b4791ee8365..c7f045a67a0 100644 --- a/doc/api/vulnerability_findings.md +++ b/doc/api/vulnerability_findings.md @@ -14,7 +14,7 @@ for serving [Vulnerability objects](https://gitlab.com/gitlab-org/gitlab/-/issue To fix any broken integrations with the former Vulnerabilities API, change the `vulnerabilities` URL part to be `vulnerability_findings`. -Every API call to vulnerability findings must be [authenticated](README.md#authentication). +Every API call to vulnerability findings must be [authenticated](index.md#authentication). Vulnerability findings are project-bound entities. If a user is not a member of a project and the project is private, a request on @@ -34,7 +34,7 @@ across GitLab releases. By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](README.md#pagination). +Read more on [pagination](index.md#pagination). ## List project vulnerability findings @@ -57,7 +57,7 @@ Beginning with GitLab 12.9, the `undefined` severity and confidence level is no | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) which the authenticated user is a member of. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) which the authenticated user is a member of. | | `report_type` | string array | no | Returns vulnerability findings belonging to specified report type. Valid values: `sast`, `dast`, `dependency_scanning`, or `container_scanning`. Defaults to all. | | `scope` | string | no | Returns vulnerability findings for the given scope: `all` or `dismissed`. Defaults to `dismissed`. | | `severity` | string array | no | Returns vulnerability findings belonging to specified severity level: `info`, `unknown`, `low`, `medium`, `high`, or `critical`. Defaults to all. | diff --git a/doc/api/wikis.md b/doc/api/wikis.md index d6cc6f938b8..8f71097aa0f 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -22,7 +22,7 @@ GET /projects/:id/wikis | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `with_content` | boolean | no | Include pages' content | ```shell @@ -63,7 +63,7 @@ GET /projects/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `slug` | string | yes | URLencoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | ```shell @@ -91,7 +91,7 @@ POST /projects/:id/wikis | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `content` | string | yes | The content of the wiki page | | `title` | string | yes | The title of the wiki page | | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | @@ -122,7 +122,7 @@ PUT /projects/:id/wikis/:slug | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `content` | string | yes if `title` is not provided | The content of the wiki page | | `title` | string | yes if `content` is not provided | The title of the wiki page | | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | @@ -154,7 +154,7 @@ DELETE /projects/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | ```shell @@ -174,7 +174,7 @@ POST /projects/:id/wikis/attachments | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `file` | string | yes | The attachment to be uploaded | | `branch` | string | no | The name of the branch. Defaults to the wiki repository default branch | |
