diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-02-27 12:09:01 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-02-27 12:09:01 +0300 |
| commit | c72e5ebe9938d315ec598197873e71a80168d40a (patch) | |
| tree | 439bf5c40aaf774e5a301825af517cb52726f450 /doc | |
| parent | ffc43b862df32a590eae874bcbb11109b46dc8be (diff) | |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
68 files changed, 540 insertions, 494 deletions
diff --git a/doc/api/appearance.md b/doc/api/appearance.md index 354a69cb604..f9ca6aed01a 100644 --- a/doc/api/appearance.md +++ b/doc/api/appearance.md @@ -9,7 +9,7 @@ Appearance API allows you to maintain GitLab's appearance as if using the GitLab List the current appearance configuration of the GitLab instance. -``` +```plaintext GET /application/appearance ``` @@ -39,7 +39,7 @@ Example response: Use an API call to modify GitLab instance appearance configuration. -``` +```plaintext PUT /application/appearance ``` diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md index 5af2bdc1d29..cba7da4ac1b 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.md @@ -8,7 +8,7 @@ To retrieve audit events using the API, you must [authenticate yourself](README. ### Retrieve all instance audit events -``` +```plaintext GET /audit_events ``` @@ -87,7 +87,7 @@ Example response: ### Retrieve single instance audit event -``` +```plaintext GET /audit_events/:id ``` @@ -126,7 +126,7 @@ To retrieve group audit events using the API, you must [authenticate yourself](R ### Retrieve all group audit events -``` +```plaintext GET /groups/:id/audit_events ``` @@ -188,7 +188,7 @@ Example response: Only available to group owners and administrators. -``` +```plaintext GET /groups/:id/audit_events/:audit_event_id ``` diff --git a/doc/api/boards.md b/doc/api/boards.md index 54b92a7511c..b99f249cab1 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -9,7 +9,7 @@ request on that project will result to a `404` status code. Lists Issue Boards in the given project. -``` +```plaintext GET /projects/:id/boards ``` @@ -83,7 +83,7 @@ Example response: Get a single board. -``` +```plaintext GET /projects/:id/boards/:board_id ``` @@ -157,7 +157,7 @@ Example response: Creates a board. -``` +```plaintext POST /projects/:id/boards ``` @@ -233,7 +233,7 @@ Example response: Updates a board. -``` +```plaintext PUT /projects/:id/boards/:board_id ``` @@ -312,7 +312,7 @@ Example response: Deletes a board. -``` +```plaintext DELETE /projects/:id/boards/:board_id ``` @@ -330,7 +330,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitl Get a list of the board's lists. Does not include `open` and `closed` lists -``` +```plaintext GET /projects/:id/boards/:board_id/lists ``` @@ -387,7 +387,7 @@ Example response: Get a single board list. -``` +```plaintext GET /projects/:id/boards/:board_id/lists/:list_id ``` @@ -421,7 +421,7 @@ Example response: Creates a new Issue Board list. -``` +```plaintext POST /projects/:id/boards/:board_id/lists ``` @@ -463,7 +463,7 @@ Example response: Updates an existing Issue Board list. This call is used to change list position. -``` +```plaintext PUT /projects/:id/boards/:board_id/lists/:list_id ``` @@ -498,7 +498,7 @@ Example response: Only for admins and project owners. Deletes the board list in question. -``` +```plaintext DELETE /projects/:id/boards/:board_id/lists/:list_id ``` diff --git a/doc/api/commits.md b/doc/api/commits.md index ee635a009bf..ca82eb4c442 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -4,7 +4,7 @@ Get a list of repository commits in a project. -``` +```plaintext GET /projects/:id/repository/commits ``` @@ -67,7 +67,7 @@ Example response: Create a commit by posting a JSON payload -``` +```plaintext POST /projects/:id/repository/commits ``` @@ -190,7 +190,7 @@ curl --request POST \ Get a specific commit identified by the commit hash or name of a branch or tag. -``` +```plaintext GET /projects/:id/repository/commits/:sha ``` @@ -246,7 +246,7 @@ Example response: Get all references (from branches or tags) a commit is pushed to. The pagination parameters `page` and `per_page` can be used to restrict the list of references. -``` +```plaintext GET /projects/:id/repository/commits/:sha/refs ``` @@ -280,7 +280,7 @@ Example response: Cherry picks a commit to a given branch. -``` +```plaintext POST /projects/:id/repository/commits/:sha/cherry_pick ``` @@ -339,7 +339,7 @@ conflict. Reverts a commit in a given branch. -``` +```plaintext POST /projects/:id/repository/commits/:sha/revert ``` @@ -391,7 +391,7 @@ changeset was empty, likely due to the change having already been reverted. Get the diff of a commit in a project. -``` +```plaintext GET /projects/:id/repository/commits/:sha/diff ``` @@ -427,7 +427,7 @@ Example response: Get the comments of a commit in a project. -``` +```plaintext GET /projects/:id/repository/commits/:sha/comments ``` @@ -478,7 +478,7 @@ cases below is valid: In any of the above cases, the response of `line`, `line_type` and `path` is set to `null`. -``` +```plaintext POST /projects/:id/repository/commits/:sha/comments ``` @@ -524,7 +524,7 @@ Since GitLab 8.1, this is the new commit status API. List the statuses of a commit in a project. The pagination parameters `page` and `per_page` can be used to restrict the list of references. -``` +```plaintext GET /projects/:id/repository/commits/:sha/statuses ``` @@ -598,7 +598,7 @@ Example response: Adds or updates a build status of a commit. -``` +```plaintext POST /projects/:id/statuses/:sha ``` @@ -651,7 +651,7 @@ Example response: Get a list of Merge Requests related to the specified commit. -``` +```plaintext GET /projects/:id/repository/commits/:sha/merge_requests ``` @@ -720,7 +720,7 @@ Example response: Get the [GPG signature from a commit](../user/project/repository/gpg_signed_commits/index.md), if it is signed. For unsigned commits, it results in a 404 response. -``` +```plaintext GET /projects/:id/repository/commits/:sha/signature ``` diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index f9c6ec4e572..f09ba3fc4ce 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -10,7 +10,7 @@ This is the API docs of the [GitLab Container Registry](../user/packages/contain Get a list of registry repositories in a project. -``` +```plaintext GET /projects/:id/registry/repositories ``` @@ -50,7 +50,7 @@ Example response: Get a list of registry repositories in a group. -``` +```plaintext GET /groups/:id/registry/repositories ``` @@ -116,7 +116,7 @@ Delete a repository in registry. This operation is executed asynchronously and might take some time to get executed. -``` +```plaintext DELETE /projects/:id/registry/repositories/:repository_id ``` @@ -135,7 +135,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git Get a list of tags for given registry repository. -``` +```plaintext GET /projects/:id/registry/repositories/:repository_id/tags ``` @@ -169,7 +169,7 @@ Example response: Get details of a registry repository tag. -``` +```plaintext GET /projects/:id/registry/repositories/:repository_id/tags/:tag_name ``` @@ -202,7 +202,7 @@ Example response: Delete a registry repository tag. -``` +```plaintext DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name ``` @@ -223,7 +223,7 @@ This action does not delete blobs. In order to delete them and recycle disk spac Delete registry repository tags in bulk based on given criteria. -``` +```plaintext DELETE /projects/:id/registry/repositories/:repository_id/tags ``` diff --git a/doc/api/custom_attributes.md b/doc/api/custom_attributes.md index 983b2381ae0..20b364993ae 100644 --- a/doc/api/custom_attributes.md +++ b/doc/api/custom_attributes.md @@ -9,7 +9,7 @@ which will be referred to as "resource" in this documentation. Get all custom attributes on a resource. -``` +```plaintext GET /users/:id/custom_attributes GET /groups/:id/custom_attributes GET /projects/:id/custom_attributes @@ -42,7 +42,7 @@ Example response: Get a single custom attribute on a resource. -``` +```plaintext GET /users/:id/custom_attributes/:key GET /groups/:id/custom_attributes/:key GET /projects/:id/custom_attributes/:key @@ -71,7 +71,7 @@ Example response: Set a custom attribute on a resource. The attribute will be updated if it already exists, or newly created otherwise. -``` +```plaintext PUT /users/:id/custom_attributes/:key PUT /groups/:id/custom_attributes/:key PUT /projects/:id/custom_attributes/:key @@ -100,7 +100,7 @@ Example response: Delete a custom attribute on a resource. -``` +```plaintext DELETE /users/:id/custom_attributes/:key DELETE /groups/:id/custom_attributes/:key DELETE /projects/:id/custom_attributes/:key diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md index 561645d7697..bb7e5ae238d 100644 --- a/doc/api/dependencies.md +++ b/doc/api/dependencies.md @@ -16,7 +16,7 @@ Get a list of project dependencies. This API partially mirroring This list can be generated only for [languages and package managers](../user/application_security/dependency_scanning/index.md#supported-languages-and-package-managers) supported by Gemnasium. -``` +```plaintext GET /projects/:id/dependencies GET /projects/:id/dependencies?package_manager=maven GET /projects/:id/dependencies?package_manager=yarn,bundler diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index 492777fb785..f6d00988c56 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -4,7 +4,7 @@ Get a list of all deploy keys across all projects of the GitLab instance. This endpoint requires admin access. -``` +```plaintext GET /deploy_keys ``` @@ -35,7 +35,7 @@ Example response: Get a list of a project's deploy keys. -``` +```plaintext GET /projects/:id/deploy_keys ``` @@ -72,7 +72,7 @@ Example response: Get a single key. -``` +```plaintext GET /projects/:id/deploy_keys/:key_id ``` @@ -106,7 +106,7 @@ Creates a new deploy key for a project. If the deploy key already exists in another project, it will be joined to current project only if original one is accessible by the same user. -``` +```plaintext POST /projects/:id/deploy_keys ``` @@ -137,7 +137,7 @@ Example response: Updates a deploy key for a project. -``` +```plaintext PUT /projects/:id/deploy_keys/:key_id ``` @@ -167,7 +167,7 @@ Example response: Removes a deploy key from the project. If the deploy key is used only for this project, it will be deleted from the system. -``` +```plaintext DELETE /projects/:id/deploy_keys/:key_id ``` diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 02c7e178aaf..f34c8026ac4 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -4,7 +4,7 @@ Get a list of deployments in a project. -``` +```plaintext GET /projects/:id/deployments ``` @@ -177,7 +177,7 @@ Example of response ## Get a specific deployment -``` +```plaintext GET /projects/:id/deployments/:deployment_id ``` @@ -265,7 +265,7 @@ Example of response ## Create a deployment -``` +```plaintext POST /projects/:id/deployments ``` @@ -319,7 +319,7 @@ Example of a response: ## Updating a deployment -``` +```plaintext PUT /projects/:id/deployments/:deployment_id ``` @@ -366,7 +366,7 @@ Example of a response: This API retrieves the list of merge requests shipped with a given deployment: -``` +```plaintext GET /projects/:id/deployments/:deployment_id/merge_requests ``` diff --git a/doc/api/discussions.md b/doc/api/discussions.md index 22d615eba28..936fcae0b72 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -22,7 +22,7 @@ Read more on [pagination](README.md#pagination). Gets a list of all discussion items for a single issue. -``` +```plaintext GET /projects/:id/issues/:issue_iid/discussions ``` @@ -118,7 +118,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Returns a single discussion item for a specific project issue -``` +```plaintext GET /projects/:id/issues/:issue_iid/discussions/:discussion_id ``` @@ -138,7 +138,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Creates a new thread to a single project issue. This is similar to creating a note but other comments (replies) can be added to it later. -``` +```plaintext POST /projects/:id/issues/:issue_iid/discussions ``` @@ -162,7 +162,7 @@ Adds a new note to the thread. This can also [create a thread from a single comm **WARNING** Notes can be added to other items than comments (system notes, etc.) making them threads. -``` +```plaintext POST /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes ``` @@ -185,7 +185,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Modify existing thread note of an issue. -``` +```plaintext PUT /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes/:note_id ``` @@ -207,7 +207,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab. Deletes an existing thread note of an issue. -``` +```plaintext DELETE /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes/:note_id ``` @@ -230,7 +230,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitl Gets a list of all discussion items for a single snippet. -``` +```plaintext GET /projects/:id/snippets/:snippet_id/discussions ``` @@ -326,7 +326,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Returns a single discussion item for a specific project snippet -``` +```plaintext GET /projects/:id/snippets/:snippet_id/discussions/:discussion_id ``` @@ -347,7 +347,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Creates a new thread to a single project snippet. This is similar to creating a note but other comments (replies) can be added to it later. -``` +```plaintext POST /projects/:id/snippets/:snippet_id/discussions ``` @@ -368,7 +368,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Adds a new note to the thread. -``` +```plaintext POST /projects/:id/snippets/:snippet_id/discussions/:discussion_id/notes ``` @@ -391,7 +391,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Modify existing thread note of a snippet. -``` +```plaintext PUT /projects/:id/snippets/:snippet_id/discussions/:discussion_id/notes/:note_id ``` @@ -413,7 +413,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab. Deletes an existing thread note of a snippet. -``` +```plaintext DELETE /projects/:id/snippets/:snippet_id/discussions/:discussion_id/notes/:note_id ``` @@ -436,7 +436,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitl Gets a list of all discussion items for a single epic. -``` +```plaintext GET /groups/:id/epics/:epic_id/discussions ``` @@ -533,7 +533,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Returns a single discussion item for a specific group epic -``` +```plaintext GET /groups/:id/epics/:epic_id/discussions/:discussion_id ``` @@ -554,7 +554,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Creates a new thread to a single group epic. This is similar to creating a note but but other comments (replies) can be added to it later. -``` +```plaintext POST /groups/:id/epics/:epic_id/discussions ``` @@ -576,7 +576,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab 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). -``` +```plaintext POST /groups/:id/epics/:epic_id/discussions/:discussion_id/notes ``` @@ -599,7 +599,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Modify existing thread note of an epic. -``` +```plaintext PUT /groups/:id/epics/:epic_id/discussions/:discussion_id/notes/:note_id ``` @@ -621,7 +621,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab. Deletes an existing thread note of an epic. -``` +```plaintext DELETE /groups/:id/epics/:epic_id/discussions/:discussion_id/notes/:note_id ``` @@ -644,7 +644,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitl Gets a list of all discussion items for a single merge request. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/discussions ``` @@ -793,7 +793,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Returns a single discussion item for a specific project merge request -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id ``` @@ -814,7 +814,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Creates a new thread to a single project merge request. This is similar to creating a note but other comments (replies) can be added to it later. -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/discussions ``` @@ -848,7 +848,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Resolve/unresolve whole thread of a merge request. -``` +```plaintext PUT /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id ``` @@ -870,7 +870,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab. 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). -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id/notes ``` @@ -893,7 +893,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Modify or resolve an existing thread note of a merge request. -``` +```plaintext PUT /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id/notes/:note_id ``` @@ -922,7 +922,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab. Deletes an existing thread note of a merge request. -``` +```plaintext DELETE /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id/notes/:note_id ``` @@ -945,7 +945,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitl Gets a list of all discussion items for a single commit. -``` +```plaintext GET /projects/:id/commits/:commit_id/discussions ``` @@ -1086,7 +1086,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Returns a single discussion item for a specific project commit -``` +```plaintext GET /projects/:id/commits/:commit_id/discussions/:discussion_id ``` @@ -1107,7 +1107,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Creates a new thread to a single project commit. This is similar to creating a note but other comments (replies) can be added to it later. -``` +```plaintext POST /projects/:id/commits/:commit_id/discussions ``` @@ -1141,7 +1141,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Adds a new note to the thread. -``` +```plaintext POST /projects/:id/commits/:commit_id/discussions/:discussion_id/notes ``` @@ -1164,7 +1164,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Modify or resolve an existing thread note of a commit. -``` +```plaintext PUT /projects/:id/commits/:commit_id/discussions/:discussion_id/notes/:note_id ``` @@ -1192,7 +1192,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab. Deletes an existing thread note of a commit. -``` +```plaintext DELETE /projects/:id/commits/:commit_id/discussions/:discussion_id/notes/:note_id ``` diff --git a/doc/api/environments.md b/doc/api/environments.md index 6817b904618..ffaff5f4f1e 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -4,7 +4,7 @@ Get all environments for a given project. -``` +```plaintext GET /projects/:id/environments ``` @@ -34,7 +34,7 @@ Example response: ## Get a specific environment -``` +```plaintext GET /projects/:id/environments/:environment_id ``` @@ -145,7 +145,7 @@ Creates a new environment with the given name and external_url. It returns `201` if the environment was successfully created, `400` for wrong parameters. -``` +```plaintext POST /projects/:id/environments ``` @@ -177,7 +177,7 @@ Updates an existing environment's name and/or external_url. It returns `200` if the environment was successfully updated. In case of an error, a status code `400` is returned. -``` +```plaintext PUT /projects/:id/environments/:environments_id ``` @@ -208,7 +208,7 @@ Example response: It returns `204` if the environment was successfully deleted, and `404` if the environment does not exist. -``` +```plaintext DELETE /projects/:id/environments/:environment_id ``` @@ -225,7 +225,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git It returns `200` if the environment was successfully stopped, and `404` if the environment does not exist. -``` +```plaintext POST /projects/:id/environments/:environment_id/stop ``` diff --git a/doc/api/epic_issues.md b/doc/api/epic_issues.md index cea6da43add..e23639ce8b0 100644 --- a/doc/api/epic_issues.md +++ b/doc/api/epic_issues.md @@ -10,7 +10,7 @@ Epics are available only in Ultimate. If epics feature is not available a `403` Gets all issues that are assigned to an epic and the authenticated user has access to. -``` +```plaintext GET /groups/:id/epics/:epic_iid/issues ``` @@ -106,7 +106,7 @@ Example response: Creates an epic - issue association. If the issue in question belongs to another epic it is unassigned from that epic. -``` +```plaintext POST /groups/:id/epics/:epic_iid/issues/:issue_id ``` @@ -212,7 +212,7 @@ Example response: Removes an epic - issue association. -``` +```plaintext DELETE /groups/:id/epics/:epic_iid/issues/:epic_issue_id ``` @@ -318,7 +318,7 @@ Example response: Updates an epic - issue association. -``` +```plaintext PUT /groups/:id/epics/:epic_iid/issues/:epic_issue_id ``` diff --git a/doc/api/epics.md b/doc/api/epics.md index b8eb1ab9f9a..54dc3754de0 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -41,7 +41,7 @@ NOTE: **Note** Gets all epics of the requested group and its subgroups. -``` +```plaintext GET /groups/:id/epics GET /groups/:id/epics?author_id=5 GET /groups/:id/epics?labels=bug,reproduced @@ -160,7 +160,7 @@ Example response: Gets a single epic -``` +```plaintext GET /groups/:id/epics/:epic_iid ``` @@ -228,7 +228,7 @@ Starting with GitLab [11.3][ee-6448], `start_date` and `end_date` should no long directly, as they now represent composite values. You can configure it via the `*_is_fixed` and `*_fixed` fields instead. -``` +```plaintext POST /groups/:id/epics ``` @@ -302,7 +302,7 @@ Starting with GitLab [11.3][ee-6448], `start_date` and `end_date` should no long directly, as they now represent composite values. You can configure it via the `*_is_fixed` and `*_fixed` fields instead. -``` +```plaintext PUT /groups/:id/epics/:epic_iid ``` @@ -372,7 +372,7 @@ Example response: Deletes an epic -``` +```plaintext DELETE /groups/:id/epics/:epic_iid ``` @@ -391,7 +391,7 @@ Manually creates a todo for the current user on an epic. If there already exists a todo for the user on that epic, status code `304` is returned. -``` +```plaintext POST /groups/:id/epics/:epic_iid/todo ``` diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index e20b74d764b..f44266aa552 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -8,7 +8,7 @@ The project settings API allows you to retrieve the Error Tracking settings for ### Get Error Tracking settings -``` +```plaintext GET /projects/:id/error_tracking/settings ``` @@ -35,7 +35,7 @@ Example response: The API allows you to enable or disable the Error Tracking settings for a project. Only for project maintainers. -``` +```plaintext PATCH /projects/:id/error_tracking/settings ``` diff --git a/doc/api/events.md b/doc/api/events.md index f3963bcf970..431e96b2804 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -38,7 +38,7 @@ Note that these options are downcased. Dates for the `before` and `after` parameters should be supplied in the following format: -``` +```plaintext YYYY-MM-DD ``` @@ -54,7 +54,7 @@ GitLab removes events older than 2 years from the events table for performance r Get a list of events for the authenticated user. Scope `read_user` or `api` is required. -``` +```plaintext GET /events ``` @@ -128,7 +128,7 @@ Example response: Get the contribution events for the specified user, sorted from newest to oldest. Scope `read_user` or `api` is required. -``` +```plaintext GET /users/:id/events ``` @@ -259,7 +259,7 @@ Example response: Get a list of visible events for a particular project. -``` +```plaintext GET /projects/:project_id/events ``` diff --git a/doc/api/feature_flag_specs.md b/doc/api/feature_flag_specs.md index e41bbea0e66..442d2c2c2d7 100644 --- a/doc/api/feature_flag_specs.md +++ b/doc/api/feature_flag_specs.md @@ -16,7 +16,7 @@ For instance, there are two specs, `staging` and `production`, for a feature fla When you pass `production` as a parameter to this endpoint, the system returns the `production` feature flag spec only. -``` +```plaintext GET /projects/:id/feature_flag_scopes ``` @@ -84,7 +84,7 @@ Example response: Get all specs of a feature flag. -``` +```plaintext GET /projects/:id/feature_flags/:name/scopes ``` @@ -147,7 +147,7 @@ Example response: Creates a new feature flag spec. -``` +```plaintext POST /projects/:id/feature_flags/:name/scopes ``` @@ -194,7 +194,7 @@ Example response: Gets a single feature flag spec. -``` +```plaintext GET /projects/:id/feature_flags/:name/scopes/:environment_scope ``` @@ -230,7 +230,7 @@ Example response: Updates an existing feature flag spec. -``` +```plaintext PUT /projects/:id/feature_flags/:name/scopes/:environment_scope ``` @@ -276,7 +276,7 @@ Example response: Deletes a feature flag spec. -``` +```plaintext DELETE /projects/:id/feature_flags/:name/scopes/:environment_scope ``` diff --git a/doc/api/features.md b/doc/api/features.md index d3c585f67c9..a43f2daa93f 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -9,7 +9,7 @@ values. Get a list of all persisted features, with its gate values. -``` +```plaintext GET /features ``` @@ -50,7 +50,7 @@ Set a feature's gate value. If a feature with the given name doesn't exist yet it will be created. The value can be a boolean, or an integer to indicate percentage of time. -``` +```plaintext POST /features/:name ``` @@ -93,6 +93,6 @@ Example response: Removes a feature gate. Response is equal when the gate exists, or doesn't. -``` +```plaintext DELETE /features/:name ``` diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index 83a00cf3f10..baaa2e2f09f 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -7,7 +7,7 @@ as an admin. Creates a new Geo node. -``` +```plaintext POST /geo_nodes ``` @@ -68,7 +68,7 @@ Example response: ## Retrieve configuration about all Geo nodes -``` +```plaintext GET /geo_nodes ``` @@ -135,7 +135,7 @@ Example response: ## Retrieve configuration about a specific Geo node -``` +```plaintext GET /geo_nodes/:id ``` @@ -178,7 +178,7 @@ Updates settings of an existing Geo node. _This can only be run against a primary Geo node._ -``` +```plaintext PUT /geo_nodes/:id ``` @@ -237,7 +237,7 @@ Removes the Geo node. NOTE: **Note:** Only a Geo primary node will accept this request. -``` +```plaintext DELETE /geo_nodes/:id ``` @@ -251,7 +251,7 @@ To repair the OAuth authentication of a Geo node. _This can only be run against a primary Geo node._ -``` +```plaintext POST /geo_nodes/:id/repair ``` @@ -282,7 +282,7 @@ Example response: ## Retrieve status about all Geo nodes -``` +```plaintext GET /geo_nodes/status ``` @@ -441,7 +441,7 @@ In GitLab 12.0, deprecated fields `wikis_count` and `repositories_count` were re ## Retrieve status about a specific Geo node -``` +```plaintext GET /geo_nodes/:id/status ``` @@ -512,7 +512,7 @@ In GitLab 12.0, deprecated fields `wikis_count` and `repositories_count` were re This only works on a secondary node. -``` +```plaintext GET /geo_nodes/current/failures ``` diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index 4fa2fa2b577..0d1a333e318 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -19,7 +19,7 @@ from the first group's project by creation date. If the group hasn't got any pro Gets a list of a group's badges. -``` +```plaintext GET /groups/:id/badges ``` @@ -52,7 +52,7 @@ Example response: Gets a badge of a group. -``` +```plaintext GET /groups/:id/badges/:badge_id ``` @@ -82,7 +82,7 @@ Example response: Adds a badge to a group. -``` +```plaintext POST /groups/:id/badges ``` @@ -113,7 +113,7 @@ Example response: Updates a badge of a group. -``` +```plaintext PUT /groups/:id/badges/:badge_id ``` @@ -145,7 +145,7 @@ Example response: Removes a badge from a group. -``` +```plaintext DELETE /groups/:id/badges/:badge_id ``` @@ -162,7 +162,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitl Returns how the `link_url` and `image_url` final URLs would be after resolving the placeholder interpolation. -``` +```plaintext GET /groups/:id/badges/render ``` diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index 186e00022cf..adfcd6e65cb 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -9,7 +9,7 @@ request will result in `404` status code. Lists Issue Boards in the given group. -``` +```plaintext GET /groups/:id/boards ``` @@ -126,7 +126,7 @@ Example response: Gets a single group issue board. -``` +```plaintext GET /groups/:id/boards/:board_id ``` @@ -240,7 +240,7 @@ Example response: Creates a Group Issue Board. -``` +```plaintext POST /groups/:id/boards ``` @@ -306,7 +306,7 @@ Example response: Updates a Group Issue Board. -``` +```plaintext PUT /groups/:id/boards/:board_id ``` @@ -372,7 +372,7 @@ Example response: Deletes a Group Issue Board. -``` +```plaintext DELETE /groups/:id/boards/:board_id ``` @@ -390,7 +390,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitl Get a list of the board's lists. Does not include `open` and `closed` lists -``` +```plaintext GET /groups/:id/boards/:board_id/lists ``` @@ -441,7 +441,7 @@ Example response: Get a single board list. -``` +```plaintext GET /groups/:id/boards/:board_id/lists/:list_id ``` @@ -473,7 +473,7 @@ Example response: Creates a new Issue Board list. -``` +```plaintext POST /groups/:id/boards/:board_id/lists ``` @@ -514,7 +514,7 @@ Example response: Updates an existing Issue Board list. This call is used to change list position. -``` +```plaintext PUT /groups/:id/boards/:board_id/lists/:list_id ``` @@ -547,7 +547,7 @@ Example response: Only for admins and group owners. Deletes the board list in question. -``` +```plaintext DELETE /groups/:id/boards/:board_id/lists/:list_id ``` diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index b94b4773a1d..afe1561b129 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -10,7 +10,7 @@ User will need at least maintainer access for the group to use these endpoints. Returns a list of group clusters. -``` +```plaintext GET /groups/:id/clusters ``` @@ -77,7 +77,7 @@ Example response: Gets a single group cluster. -``` +```plaintext GET /groups/:id/clusters/:cluster_id ``` @@ -144,7 +144,7 @@ Example response: Adds an existing Kubernetes cluster to the group. -``` +```plaintext POST /groups/:id/clusters/user ``` @@ -213,7 +213,7 @@ Example response: Updates an existing group cluster. -``` +```plaintext PUT /groups/:id/clusters/:cluster_id ``` @@ -287,14 +287,13 @@ Example response: "web_url":"https://gitlab.example.com/group-with-clusters-api" } } - ``` ## Delete group cluster Deletes an existing group cluster. -``` +```plaintext DELETE /groups/:id/clusters/:cluster_id ``` diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index 09bc9810615..039f81a18d0 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -19,7 +19,7 @@ Group exports include the following: Start a new group export. -```text +```plaintext POST /groups/:id/export ``` diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index c9c084c6d11..37ab2fe48f1 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -11,7 +11,7 @@ The `description_html` - was added to response JSON in [GitLab 12.7](https://git Get all labels for a given group. -``` +```plaintext GET /groups/:id/labels ``` @@ -60,7 +60,7 @@ Example response: Get a single label for a given group. -``` +```plaintext GET /groups/:id/labels/:label_id ``` @@ -95,7 +95,7 @@ Example response: Create a new group label for a given group. -``` +```plaintext POST /groups/:id/labels ``` @@ -131,7 +131,7 @@ Example response: Updates an existing group label. At least one parameter is required, to update the group label. -``` +```plaintext PUT /groups/:id/labels/:label_id ``` @@ -170,7 +170,7 @@ NOTE: **Note:** An older endpoint `PUT /groups/:id/labels` with `name` in the pa Deletes a group label with a given name. -``` +```plaintext DELETE /groups/:id/labels/:label_id ``` @@ -190,7 +190,7 @@ NOTE: **Note:** An older endpoint `DELETE /groups/:id/labels` with `name` in the Subscribes the authenticated user to a group label to receive notifications. If the user is already subscribed to the label, the status code `304` is returned. -``` +```plaintext POST /groups/:id/labels/:label_id/subscribe ``` @@ -226,7 +226,7 @@ Unsubscribes the authenticated user from a group label to not receive notifications from it. If the user is not subscribed to the label, the status code `304` is returned. -``` +```plaintext POST /groups/:id/labels/:label_id/unsubscribe ``` diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index 5eaf44ef6c1..95a68283f1d 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.md @@ -6,7 +6,7 @@ Get list of a group's variables. -``` +```plaintext GET /groups/:id/variables ``` @@ -14,7 +14,7 @@ GET /groups/:id/variables |-----------|---------|----------|---------------------| | `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 | -``` +```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables" ``` @@ -41,7 +41,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a Get the details of a group's specific variable. -``` +```plaintext GET /groups/:id/variables/:key ``` @@ -50,7 +50,7 @@ GET /groups/:id/variables/:key | `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 | | `key` | string | yes | The `key` of a variable | -``` +```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables/TEST_VARIABLE_1" ``` @@ -68,7 +68,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a Create a new variable. -``` +```plaintext POST /groups/:id/variables ``` @@ -81,7 +81,7 @@ POST /groups/:id/variables | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | -``` +```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables" --form "key=NEW_VARIABLE" --form "value=new value" ``` @@ -99,7 +99,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla Update a group's variable. -``` +```plaintext PUT /groups/:id/variables/:key ``` @@ -112,7 +112,7 @@ PUT /groups/:id/variables/:key | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | -``` +```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables/NEW_VARIABLE" --form "value=updated value" ``` @@ -130,7 +130,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab Remove a group's variable. -``` +```plaintext DELETE /groups/:id/variables/:key ``` @@ -139,7 +139,7 @@ DELETE /groups/:id/variables/:key | `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 | | `key` | string | yes | The `key` of a variable | -``` +```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables/VARIABLE_1" ``` diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index c86ddab5793..7e2a6987208 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -6,7 +6,7 @@ Returns a list of group milestones. -``` +```plaintext GET /groups/:id/milestones GET /groups/:id/milestones?iids[]=42 GET /groups/:id/milestones?iids[]=42&iids[]=43 @@ -53,7 +53,7 @@ Example Response: Gets a single group milestone. -``` +```plaintext GET /groups/:id/milestones/:milestone_id ``` @@ -66,7 +66,7 @@ Parameters: Creates a new group milestone. -``` +```plaintext POST /groups/:id/milestones ``` @@ -82,7 +82,7 @@ Parameters: Updates an existing group milestone. -``` +```plaintext PUT /groups/:id/milestones/:milestone_id ``` @@ -100,7 +100,7 @@ Parameters: Only for users with Developer access to the group. -``` +```plaintext DELETE /groups/:id/milestones/:milestone_id ``` @@ -113,7 +113,7 @@ Parameters: Gets all issues assigned to a single group milestone. -``` +```plaintext GET /groups/:id/milestones/:milestone_id/issues ``` @@ -126,7 +126,7 @@ Parameters: Gets all merge requests assigned to a single group milestone. -``` +```plaintext GET /groups/:id/milestones/:milestone_id/merge_requests ``` @@ -143,7 +143,7 @@ Parameters: Get all burndown chart events for a single milestone. -``` +```plaintext GET /groups/:id/milestones/:milestone_id/burndown_events ``` diff --git a/doc/api/groups.md b/doc/api/groups.md index 4c287386c59..3a488ca6546 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -21,7 +21,7 @@ Parameters: | `owned` | boolean | no | Limit to groups explicitly owned by the current user | | `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md) | -``` +```plaintext GET /groups ``` @@ -55,7 +55,7 @@ GET /groups When adding the parameter `statistics=true` and the authenticated user is an admin, additional group statistics are returned. -``` +```plaintext GET /groups?statistics=true ``` @@ -99,7 +99,7 @@ You can search for groups by name or path, see below. You can filter by [custom attributes](custom_attributes.md) with: -``` +```plaintext GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_value ``` @@ -127,7 +127,7 @@ Parameters: | `owned` | boolean | no | Limit to groups explicitly owned by the current user | | `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md) | -``` +```plaintext GET /groups/:id/subgroups ``` @@ -165,7 +165,7 @@ Get a list of projects in this group. When accessed without authentication, only By default, this request returns 20 results at a time because the API results [are paginated](README.md#pagination). -``` +```plaintext GET /groups/:id/projects ``` @@ -239,7 +239,7 @@ Example response: Get all details of a group. This endpoint can be accessed without authentication if the group is publicly accessible. In case the user that requests is admin of the group, it will return the `runners_token` for the group too. -``` +```plaintext GET /groups/:id ``` @@ -470,7 +470,7 @@ Feature.disable(:limit_projects_in_groups_api) Creates a new project group. Available only for users who can create groups. -``` +```plaintext POST /groups ``` @@ -500,7 +500,7 @@ Parameters: Transfer a project to the Group namespace. Available only to instance administrators, although an [alternative API endpoint](projects.md#transfer-a-project-to-a-new-namespace) is available which does not require instance administrator access. Transferring projects may fail when tagged packages exist in the project's repository. -``` +```plaintext POST /groups/:id/projects/:project_id ``` @@ -519,7 +519,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Updates the project group. Only available to group owners and administrators. -``` +```plaintext PUT /groups/:id ``` @@ -548,7 +548,6 @@ PUT /groups/:id ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5?name=Experimental" - ``` This endpoint returns: @@ -639,7 +638,7 @@ This endpoint either: - Removes group, and queues a background job to delete all projects in the group as well. - Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, marks a group for deletion. The deletion will happen 7 days later by default, but this can be changed in the [instance settings](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-adjourned-period-premium-only). -``` +```plaintext DELETE /groups/:id ``` @@ -671,7 +670,7 @@ Parameters: Get all groups that match your string in their name or path. -``` +```plaintext GET /groups?search=foobar ``` @@ -695,7 +694,7 @@ These are different from [System Hooks](system_hooks.md) that are system wide an Get a list of group hooks -``` +```plaintext GET /groups/:id/hooks ``` @@ -712,7 +711,7 @@ Get a specific hook for a group. | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of a group hook | -``` +```plaintext GET /groups/:id/hooks/:hook_id ``` @@ -739,7 +738,7 @@ GET /groups/:id/hooks/:hook_id Adds a hook to a specified group. -``` +```plaintext POST /groups/:id/hooks ``` @@ -763,7 +762,7 @@ POST /groups/:id/hooks Edits a hook for a specified group. -``` +```plaintext PUT /groups/:id/hooks/:hook_id ``` @@ -789,7 +788,7 @@ PUT /groups/:id/hooks/:hook_id Removes a hook from a group. This is an idempotent method and can be called multiple times. Either the hook is available or not. -``` +```plaintext DELETE /groups/:id/hooks/:hook_id ``` @@ -806,7 +805,7 @@ Group audit events can be accessed via the [Group Audit Events API](audit_events Syncs the group with its linked LDAP group. Only available to group owners and administrators. -``` +```plaintext POST /groups/:id/ldap_sync ``` @@ -826,7 +825,7 @@ List, add, and delete LDAP group links. Lists LDAP group links. -``` +```plaintext GET /groups/:id/ldap_group_links ``` @@ -838,7 +837,7 @@ Parameters: Adds an LDAP group link. -``` +```plaintext POST /groups/:id/ldap_group_links ``` @@ -853,7 +852,7 @@ Parameters: Deletes an LDAP group link. -``` +```plaintext DELETE /groups/:id/ldap_group_links/:cn ``` @@ -864,7 +863,7 @@ Parameters: Deletes a LDAP group link for a specific LDAP provider -``` +```plaintext DELETE /groups/:id/ldap_group_links/:provider/:cn ``` @@ -880,13 +879,13 @@ By default, groups only get 20 namespaces at a time because the API results are To get more (up to 100), pass the following as an argument to the API call: -``` +```plaintext /groups?per_page=100 ``` And to switch pages add: -``` +```plaintext /groups?per_page=100&page=2 ``` diff --git a/doc/api/import.md b/doc/api/import.md index 0f8a9bc71d1..8db8dc7eea4 100644 --- a/doc/api/import.md +++ b/doc/api/import.md @@ -4,7 +4,7 @@ Import your projects from GitHub to GitLab via the API. -``` +```plaintext POST /import/github ``` diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index 2a64c2370fc..b6502bf099c 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.md @@ -5,7 +5,7 @@ Get a list of related issues of a given issue, sorted by the relationship creation datetime (ascending). Issues will be filtered according to the user authorizations. -``` +```plaintext GET /projects/:id/issues/:issue_iid/links ``` @@ -57,7 +57,7 @@ Parameters: Creates a two-way relation between two issues. User must be allowed to update both issues in order to succeed. -``` +```plaintext POST /projects/:id/issues/:issue_iid/links ``` @@ -145,7 +145,7 @@ Example response: Deletes an issue link, thus removes the two-way relationship. -``` +```plaintext DELETE /projects/:id/issues/:issue_iid/links/:issue_link_id ``` diff --git a/doc/api/issues.md b/doc/api/issues.md index e2c8c046d3d..612971d8f5e 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -26,7 +26,7 @@ Get all issues the authenticated user has access to. By default it returns only issues created by the current user. To get all issues, use parameter `scope=all`. -``` +```plaintext GET /issues GET /issues?state=opened GET /issues?state=closed @@ -181,7 +181,7 @@ the `weight` parameter: Get a list of a group's issues. -``` +```plaintext GET /groups/:id/issues GET /groups/:id/issues?state=opened GET /groups/:id/issues?state=closed @@ -336,7 +336,7 @@ the `weight` parameter: Get a list of a project's issues. -``` +```plaintext GET /projects/:id/issues GET /projects/:id/issues?state=opened GET /projects/:id/issues?state=closed @@ -497,7 +497,7 @@ the `weight` parameter: Get a single project issue. -``` +```plaintext GET /projects/:id/issues/:issue_iid ``` @@ -637,7 +637,7 @@ Please use `iid` of the `epic` attribute instead. Creates a new project issue. -``` +```plaintext POST /projects/:id/issues ``` @@ -745,7 +745,7 @@ the `weight` parameter: Updates an existing project issue. This call is also used to mark an issue as closed. -``` +```plaintext PUT /projects/:id/issues/:issue_iid ``` @@ -864,7 +864,7 @@ The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value Only for admins and project owners. Deletes the issue in question. -``` +```plaintext DELETE /projects/:id/issues/:issue_iid ``` @@ -886,7 +886,7 @@ issue, error `400` together with an explaining error message is returned. If a given label and/or milestone with the same name also exists in the target project, it will then be assigned to the issue that is being moved. -``` +```plaintext POST /projects/:id/issues/:issue_iid/move ``` @@ -993,7 +993,7 @@ Subscribes the authenticated user to an issue to receive notifications. If the user is already subscribed to the issue, the status code `304` is returned. -``` +```plaintext POST /projects/:id/issues/:issue_iid/subscribe ``` @@ -1099,7 +1099,7 @@ Unsubscribes the authenticated user from the issue to not receive notifications from it. If the user is not subscribed to the issue, the status code `304` is returned. -``` +```plaintext POST /projects/:id/issues/:issue_iid/unsubscribe ``` @@ -1170,7 +1170,7 @@ Manually creates a todo for the current user on an issue. If there already exists a todo for the user on that issue, status code `304` is returned. -``` +```plaintext POST /projects/:id/issues/:issue_iid/todo ``` @@ -1284,7 +1284,7 @@ Example response: Sets an estimated time of work for this issue. -``` +```plaintext POST /projects/:id/issues/:issue_iid/time_estimate ``` @@ -1313,7 +1313,7 @@ Example response: Resets the estimated time for this issue to 0 seconds. -``` +```plaintext POST /projects/:id/issues/:issue_iid/reset_time_estimate ``` @@ -1341,7 +1341,7 @@ Example response: Adds spent time for this issue -``` +```plaintext POST /projects/:id/issues/:issue_iid/add_spent_time ``` @@ -1370,7 +1370,7 @@ Example response: Resets the total spent time for this issue to 0 seconds. -``` +```plaintext POST /projects/:id/issues/:issue_iid/reset_spent_time ``` @@ -1396,7 +1396,7 @@ Example response: ## Get time tracking stats -``` +```plaintext GET /projects/:id/issues/:issue_iid/time_stats ``` @@ -1424,7 +1424,7 @@ Example response: Get all the merge requests that are related to the issue. -``` +```plaintext GET /projects/:id/issues/:issue_id/related_merge_requests ``` @@ -1580,7 +1580,7 @@ Example response: Get all the merge requests that will close issue when merged. -``` +```plaintext GET /projects/:id/issues/:issue_iid/closed_by ``` @@ -1653,7 +1653,7 @@ Example response: ## Participants on issues -``` +```plaintext GET /projects/:id/issues/:issue_iid/participants ``` @@ -1697,7 +1697,7 @@ Comments are done via the [notes](notes.md) resource. Available only for admins. -``` +```plaintext GET /projects/:id/issues/:issue_iid/user_agent_detail ``` diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md index 2c391166088..b24e385c3de 100644 --- a/doc/api/issues_statistics.md +++ b/doc/api/issues_statistics.md @@ -11,7 +11,7 @@ Gets issues count statistics on all issues the authenticated user has access to. returns only issues created by the current user. To get all issues, use parameter `scope=all`. -``` +```plaintext GET /issues_statistics GET /issues_statistics?labels=foo GET /issues_statistics?labels=foo,bar @@ -67,7 +67,7 @@ Example response: Gets issues count statistics for given group. -``` +```plaintext GET /groups/:id/issues_statistics GET /groups/:id/issues_statistics?labels=foo GET /groups/:id/issues_statistics?labels=foo,bar diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 00920f94610..6cd2d0a04f5 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -4,7 +4,7 @@ Get a list of jobs in a project. Jobs are sorted in descending order of their IDs. -``` +```plaintext GET /projects/:id/jobs ``` @@ -138,7 +138,7 @@ Example of response Get a list of jobs for a pipeline. -``` +```plaintext GET /projects/:id/pipelines/:pipeline_id/jobs ``` @@ -273,7 +273,7 @@ Example of response Get a single job of a project -``` +```plaintext GET /projects/:id/jobs/:job_id ``` @@ -351,7 +351,7 @@ Example of response Get the job's artifacts zipped archive of a project. -``` +```plaintext GET /projects/:id/jobs/:job_id/artifacts ``` @@ -414,7 +414,7 @@ the given reference name and job, provided the job finished successfully. This is the same as [getting the job's artifacts](#get-job-artifacts), but by defining the job's name instead of its ID. -``` +```plaintext GET /projects/:id/jobs/artifacts/:ref_name/download?job=name ``` @@ -476,7 +476,7 @@ Download a single artifact file from a job with a specified ID from within the job's artifacts zipped archive. The file is extracted from the archive and streamed to the client. -``` +```plaintext GET /projects/:id/jobs/:job_id/artifacts/*artifact_path ``` @@ -510,7 +510,7 @@ Download a single artifact file for a specific job of the latest successful pipeline for the given reference name from within the job's artifacts archive. The file is extracted from the archive and streamed to the client. -``` +```plaintext GET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_path?job=name ``` @@ -541,7 +541,7 @@ Possible response status codes: Get a log (trace) of a specific job of a project: -``` +```plaintext GET /projects/:id/jobs/:job_id/trace ``` @@ -565,7 +565,7 @@ Possible response status codes: Cancel a single job of a project -``` +```plaintext POST /projects/:id/jobs/:job_id/cancel ``` @@ -614,7 +614,7 @@ Example of response Retry a single job of a project -``` +```plaintext POST /projects/:id/jobs/:job_id/retry ``` @@ -663,7 +663,7 @@ Example of response Erase a single job of a project (remove job artifacts and a job log) -``` +```plaintext POST /projects/:id/jobs/:job_id/erase ``` @@ -717,7 +717,7 @@ Example of response Prevents artifacts from being deleted when expiration is set. -``` +```plaintext POST /projects/:id/jobs/:job_id/artifacts/keep ``` @@ -773,7 +773,7 @@ Example response: Delete artifacts of a job. -``` +```plaintext DELETE /projects/:id/jobs/:job_id/artifacts ``` @@ -797,7 +797,7 @@ If the artifacts were deleted successfully, a response with status `204 No Conte Triggers a manual action to start a job. -``` +```plaintext POST /projects/:id/jobs/:job_id/play ``` diff --git a/doc/api/labels.md b/doc/api/labels.md index 4ee7484d301..54af6c093b9 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -7,7 +7,7 @@ The `description_html` - was added to response JSON in [GitLab 12.7](https://git Get all labels for a given project. -``` +```plaintext GET /projects/:id/labels ``` @@ -102,7 +102,7 @@ Example response: Get a single label for a given project. -``` +```plaintext GET /projects/:id/labels/:label_id ``` @@ -139,7 +139,7 @@ Example response: Creates a new label for the given repository with the given name and color. -``` +```plaintext POST /projects/:id/labels ``` @@ -178,7 +178,7 @@ Example response: Deletes a label with a given name. -``` +```plaintext DELETE /projects/:id/labels/:label_id ``` @@ -198,7 +198,7 @@ NOTE: **Note:** An older endpoint `DELETE /projects/:id/labels` with `name` in t Updates an existing label with new name or new color. At least one parameter is required, to update the label. -``` +```plaintext PUT /projects/:id/labels/:label_id ``` @@ -242,7 +242,7 @@ NOTE: **Note:** An older endpoint `PUT /projects/:id/labels` with `name` or `lab Promotes a project label to a group label. -``` +```plaintext PUT /projects/:id/labels/:label_id/promote ``` @@ -279,7 +279,7 @@ Subscribes the authenticated user to a label to receive notifications. If the user is already subscribed to the label, the status code `304` is returned. -``` +```plaintext POST /projects/:id/labels/:label_id/subscribe ``` @@ -317,7 +317,7 @@ Unsubscribes the authenticated user from a label to not receive notifications from it. If the user is not subscribed to the label, the status code `304` is returned. -``` +```plaintext POST /projects/:id/labels/:label_id/unsubscribe ``` diff --git a/doc/api/license.md b/doc/api/license.md index 2be26e1bddf..71e95fc3202 100644 --- a/doc/api/license.md +++ b/doc/api/license.md @@ -5,7 +5,7 @@ as an admin. ## Retrieve information about the current license -``` +```plaintext GET /license ``` @@ -34,7 +34,7 @@ GET /license ## Retrieve information about all licenses -``` +```plaintext GET /licenses ``` @@ -93,7 +93,7 @@ Returns: ## Add a new license -``` +```plaintext POST /license ``` @@ -137,7 +137,7 @@ Returns: ## Delete a license -``` +```plaintext DELETE /license/:id ``` diff --git a/doc/api/lint.md b/doc/api/lint.md index c495bfaa7cb..4ecce92df26 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -4,7 +4,7 @@ Checks if your `.gitlab-ci.yml` file is valid. -``` +```plaintext POST /ci/lint ``` diff --git a/doc/api/managed_licenses.md b/doc/api/managed_licenses.md index 34b1e5dc6dc..66125d23a82 100644 --- a/doc/api/managed_licenses.md +++ b/doc/api/managed_licenses.md @@ -4,7 +4,7 @@ Get all managed licenses for a given project. -``` +```plaintext GET /projects/:id/managed_licenses ``` @@ -37,7 +37,7 @@ Example response: Shows an existing managed license. -``` +```plaintext GET /projects/:id/managed_licenses/:managed_license_id ``` @@ -64,7 +64,7 @@ Example response: Creates a new managed license for the given project with the given name and approval status. -``` +```plaintext POST /projects/:id/managed_licenses ``` @@ -92,7 +92,7 @@ Example response: Deletes a managed license with a given id. -``` +```plaintext DELETE /projects/:id/managed_licenses/:managed_license_id ``` @@ -111,7 +111,7 @@ When successful, it replies with an HTTP 204 response. Updates an existing managed license with a new approval status. -``` +```plaintext PATCH /projects/:id/managed_licenses/:managed_license_id ``` diff --git a/doc/api/markdown.md b/doc/api/markdown.md index b9207b7ba15..bacd9d805bf 100644 --- a/doc/api/markdown.md +++ b/doc/api/markdown.md @@ -6,7 +6,7 @@ Available only in APIv4. ## Render an arbitrary Markdown document -``` +```plaintext POST /api/v4/markdown ``` diff --git a/doc/api/members.md b/doc/api/members.md index e32f72e14e7..47f2d694006 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -17,7 +17,7 @@ The access levels are defined in the `Gitlab::Access` module. Currently, these l Gets a list of group or project members viewable by the authenticated user. Returns only direct members and not inherited members through ancestors groups. -``` +```plaintext GET /groups/:id/members GET /projects/:id/members ``` @@ -72,7 +72,7 @@ Gets a list of group or project members viewable by the authenticated user, incl When a user is a member of the project/group and of one or more ancestor groups the user is returned only once with the project `access_level` (if exists) or the `access_level` for the user in the first group which they belong to in the project groups ancestors chain. -``` +```plaintext GET /groups/:id/members/all GET /projects/:id/members/all ``` @@ -136,7 +136,7 @@ Example response: Gets a member of a group or project. Returns only direct members and not inherited members through ancestor groups. -``` +```plaintext GET /groups/:id/members/:user_id GET /projects/:id/members/:user_id ``` @@ -173,7 +173,7 @@ Example response: Gets a member of a group or project, including members inherited through ancestor groups. See the corresponding [endpoint to list all inherited members](#list-all-members-of-a-group-or-project-including-inherited-members) for details. -``` +```plaintext GET /groups/:id/members/all/:user_id GET /projects/:id/members/all/:user_id ``` @@ -208,7 +208,7 @@ Example response: Adds a member to a group or project. -``` +```plaintext POST /groups/:id/members POST /projects/:id/members ``` @@ -245,7 +245,7 @@ Example response: Updates a member of a group or project. -``` +```plaintext PUT /groups/:id/members/:user_id PUT /projects/:id/members/:user_id ``` @@ -282,7 +282,7 @@ Example response: Removes a user from a group or project. -``` +```plaintext DELETE /groups/:id/members/:user_id DELETE /projects/:id/members/:user_id ``` diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index a96b9aadc41..004c10fa70a 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -11,7 +11,7 @@ Configuration for approvals on all Merge Requests (MR) in the project. Must be a You can request information about a project's approval configuration using the following endpoint: -``` +```plaintext GET /projects/:id/approvals ``` @@ -39,7 +39,7 @@ GET /projects/:id/approvals If you are allowed to, you can change approval configuration using the following endpoint: -``` +```plaintext POST /projects/:id/approvals ``` @@ -73,7 +73,7 @@ POST /projects/:id/approvals You can request information about a project's approval rules using the following endpoint: -``` +```plaintext GET /projects/:id/approval_rules ``` @@ -172,7 +172,7 @@ GET /projects/:id/approval_rules You can create project approval rules using the following endpoint: -``` +```plaintext POST /projects/:id/approval_rules ``` @@ -274,7 +274,7 @@ POST /projects/:id/approval_rules You can update project approval rules using the following endpoint: -``` +```plaintext PUT /projects/:id/approval_rules/:approval_rule_id ``` @@ -379,7 +379,7 @@ PUT /projects/:id/approval_rules/:approval_rule_id You can delete project approval rules using the following endpoint: -``` +```plaintext DELETE /projects/:id/approval_rules/:approval_rule_id ``` @@ -398,7 +398,7 @@ DELETE /projects/:id/approval_rules/:approval_rule_id If you are allowed to, you can change approvers and approver groups using the following endpoint: -``` +```plaintext PUT /projects/:id/approvers ``` @@ -464,7 +464,7 @@ Configuration for approvals on a specific Merge Request. Must be authenticated f You can request information about a merge request's approval status using the following endpoint: -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/approvals ``` @@ -510,7 +510,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/approvals If you are allowed to, you can change `approvals_required` using the following endpoint: -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/approvals ``` @@ -547,7 +547,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals If you are allowed to, you can change approvers and approver groups using the following endpoint: -``` +```plaintext PUT /projects/:id/merge_requests/:merge_request_iid/approvers ``` @@ -617,7 +617,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/approvers You can request information about a merge request's approval state by using the following endpoint: -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/approval_state ``` @@ -688,7 +688,7 @@ This includes additional information about the users who have already approved You can request information about a merge request's approval rules using the following endpoint: -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/approval_rules ``` @@ -764,7 +764,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/approval_rules You can create merge request approval rules using the following endpoint: -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/approval_rules ``` @@ -847,7 +847,7 @@ will be used. You can update merge request approval rules using the following endpoint: -``` +```plaintext PUT /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id ``` @@ -931,7 +931,7 @@ These are system generated rules. You can delete merge request approval rules using the following endpoint: -``` +```plaintext DELETE /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id ``` @@ -953,7 +953,7 @@ These are system generated rules. If you are allowed to, you can approve a merge request using the following endpoint: -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/approve ``` @@ -1016,7 +1016,7 @@ does not match, the response code will be `409`. If you did approve a merge request, you can unapprove it using the following endpoint: -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/unapprove ``` diff --git a/doc/api/merge_request_context_commits.md b/doc/api/merge_request_context_commits.md index a4659204127..58847dc20ae 100644 --- a/doc/api/merge_request_context_commits.md +++ b/doc/api/merge_request_context_commits.md @@ -4,7 +4,7 @@ Get a list of merge request context commits. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/context_commits ``` @@ -36,7 +36,7 @@ Parameters: Create a list of merge request context commits. -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/context_commits ``` @@ -45,7 +45,7 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The internal ID of the merge request -``` +```plaintext POST /projects/:id/merge_requests/ ``` @@ -75,7 +75,7 @@ POST /projects/:id/merge_requests/ Delete a list of merge request context commits. -``` +```plaintext DELETE /projects/:id/merge_requests/:merge_request_iid/context_commits ``` diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 54d140461e1..a0f9a120480 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -23,7 +23,7 @@ given state (`opened`, `closed`, `locked`, or `merged`) or all of them (`all`). The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests. -``` +```plaintext GET /merge_requests GET /merge_requests?state=opened GET /merge_requests?state=all @@ -190,7 +190,7 @@ Get all merge requests for this project. The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, `locked`, or `merged`) or all of them (`all`). The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests. -``` +```plaintext GET /projects/:id/merge_requests GET /projects/:id/merge_requests?state=opened GET /projects/:id/merge_requests?state=all @@ -361,7 +361,7 @@ Get all merge requests for this group and its subgroups. The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, `locked`, or `merged`) or all of them (`all`). The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests. -``` +```plaintext GET /groups/:id/merge_requests GET /groups/:id/merge_requests?state=opened GET /groups/:id/merge_requests?state=all @@ -524,7 +524,7 @@ integer. This is because when an MR has too many changes to display and store, it will be capped at 1,000. In that case, the API will return the string `"1000+"` for the changes count. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid ``` @@ -683,7 +683,7 @@ the `approvals_before_merge` parameter: Get a list of merge request participants. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/participants ``` @@ -717,7 +717,7 @@ Parameters: Get a list of merge request commits. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/commits ``` @@ -753,7 +753,7 @@ Parameters: Shows information about the merge request including its files and changes. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/changes ``` @@ -864,7 +864,7 @@ Parameters: Get a list of merge request pipelines. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/pipelines ``` @@ -896,7 +896,7 @@ The new pipeline can be: - 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#enabling-pipelines-for-merged-results). -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/pipelines ``` @@ -948,7 +948,7 @@ Parameters: Creates a new merge request. -``` +```plaintext POST /projects/:id/merge_requests ``` @@ -1105,7 +1105,7 @@ the `approvals_before_merge` parameter: Updates an existing merge request. You can change the target branch, title, or even close the MR. -``` +```plaintext PUT /projects/:id/merge_requests/:merge_request_iid ``` @@ -1264,7 +1264,7 @@ the `approvals_before_merge` parameter: Only for admins and project owners. Deletes the merge request in question. -``` +```plaintext DELETE /projects/:id/merge_requests/:merge_request_iid ``` @@ -1289,7 +1289,7 @@ If the `sha` parameter is passed and does not match the HEAD of the source - you If you don't have permissions to accept this merge request - you'll get a `401` -``` +```plaintext PUT /projects/:id/merge_requests/:merge_request_iid/merge ``` @@ -1450,7 +1450,7 @@ If the merge request has conflicts, is empty or already merged, you'll get a `40 It returns the HEAD commit of `refs/merge-requests/:iid/merge` in the response body in case of `200`. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/merge_ref ``` @@ -1473,7 +1473,7 @@ If the merge request is already merged or closed - you get `405` and error messa In case the merge request is not set to be merged when the pipeline succeeds, you'll also get a `406` error. -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_succeeds ``` @@ -1621,7 +1621,7 @@ Automatically rebase the `source_branch` of the merge request against its If you don't have permissions to push to the merge request's source branch - you'll get a `403 Forbidden` response. -``` +```plaintext PUT /projects/:id/merge_requests/:merge_request_iid/rebase ``` @@ -1684,7 +1684,7 @@ Comments are done via the [notes](notes.md) resource. Get all the issues that would be closed by merging the provided merge request. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/closes_issues ``` @@ -1760,7 +1760,7 @@ Example response when an external issue tracker (e.g. Jira) is used: Subscribes the authenticated user to a merge request to receive notification. If the user is already subscribed to the merge request, the status code `304` is returned. -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/subscribe ``` @@ -1911,7 +1911,7 @@ Unsubscribes the authenticated user from a merge request to not receive notifications from that merge request. If the user is not subscribed to the merge request, the status code `304` is returned. -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/unsubscribe ``` @@ -2062,7 +2062,7 @@ Manually creates a todo for the current user on a merge request. If there already exists a todo for the user on that merge request, status code `304` is returned. -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/todo ``` @@ -2179,7 +2179,7 @@ Example response: Get a list of merge request diff versions. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/versions ``` @@ -2220,7 +2220,7 @@ Example response: Get a single merge request diff version. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/versions/:version_id ``` @@ -2288,7 +2288,7 @@ Example response: Sets an estimated time of work for this merge request. -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/time_estimate ``` @@ -2317,7 +2317,7 @@ Example response: Resets the estimated time for this merge request to 0 seconds. -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/reset_time_estimate ``` @@ -2345,7 +2345,7 @@ Example response: Adds spent time for this merge request -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/add_spent_time ``` @@ -2374,7 +2374,7 @@ Example response: Resets the total spent time for this merge request to 0 seconds. -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/reset_spent_time ``` @@ -2400,7 +2400,7 @@ Example response: ## Get time tracking stats -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/time_stats ``` diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 43faf04a709..5727a4b637f 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -4,7 +4,7 @@ Returns a list of project milestones. -``` +```plaintext GET /projects/:id/milestones GET /projects/:id/milestones?iids[]=42 GET /projects/:id/milestones?iids[]=42&iids[]=43 @@ -51,7 +51,7 @@ Example Response: Gets a single project milestone. -``` +```plaintext GET /projects/:id/milestones/:milestone_id ``` @@ -64,7 +64,7 @@ Parameters: Creates a new project milestone. -``` +```plaintext POST /projects/:id/milestones ``` @@ -80,7 +80,7 @@ Parameters: Updates an existing project milestone. -``` +```plaintext PUT /projects/:id/milestones/:milestone_id ``` @@ -98,7 +98,7 @@ Parameters: Only for users with Developer access to the project. -``` +```plaintext DELETE /projects/:id/milestones/:milestone_id ``` @@ -111,7 +111,7 @@ Parameters: Gets all issues assigned to a single project milestone. -``` +```plaintext GET /projects/:id/milestones/:milestone_id/issues ``` @@ -124,7 +124,7 @@ Parameters: Gets all merge requests assigned to a single project milestone. -``` +```plaintext GET /projects/:id/milestones/:milestone_id/merge_requests ``` @@ -139,7 +139,7 @@ Parameters: Only for users with Developer access to the group. -``` +```plaintext POST /projects/:id/milestones/:milestone_id/promote ``` @@ -154,7 +154,7 @@ Parameters: Gets all burndown chart events for a single milestone. -``` +```plaintext GET /projects/:id/milestones/:milestone_id/burndown_events ``` diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 872385b8b5e..50b5f3f19cd 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -12,7 +12,7 @@ For users and groups supported API calls see the [users](users.md) and Get a list of the namespaces of the authenticated user. If the user is an administrator, a list of all namespaces in the GitLab instance is shown. -``` +```plaintext GET /namespaces ``` @@ -74,7 +74,7 @@ NOTE: **Note:** Only group maintainers/owners are presented with `members_count_ Get all namespaces that match a string in their name or path. -``` +```plaintext GET /namespaces?search=foobar ``` @@ -108,7 +108,7 @@ Example response: Get a namespace by ID. -``` +```plaintext GET /namespaces/:id ``` diff --git a/doc/api/notes.md b/doc/api/notes.md index 302b89e5359..f7d7163b7a8 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -22,7 +22,7 @@ Read more on [pagination](README.md#pagination). Gets a list of all notes for a single issue. -``` +```plaintext GET /projects/:id/issues/:issue_iid/notes GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at ``` @@ -87,7 +87,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Returns a single note for a specific project issue -``` +```plaintext GET /projects/:id/issues/:issue_iid/notes/:note_id ``` @@ -105,7 +105,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Creates a new note to a single project issue. -``` +```plaintext POST /projects/:id/issues/:issue_iid/notes ``` @@ -124,7 +124,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Modify existing note of an issue. -``` +```plaintext PUT /projects/:id/issues/:issue_iid/notes/:note_id ``` @@ -143,7 +143,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab. Deletes an existing note of an issue. -``` +```plaintext DELETE /projects/:id/issues/:issue_iid/notes/:note_id ``` @@ -165,7 +165,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitl Gets a list of all notes for a single snippet. Snippet notes are comments users can post to a snippet. -``` +```plaintext GET /projects/:id/snippets/:snippet_id/notes GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at ``` @@ -185,7 +185,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Returns a single note for a given snippet. -``` +```plaintext GET /projects/:id/snippets/:snippet_id/notes/:note_id ``` @@ -223,7 +223,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Creates a new note for a single snippet. Snippet notes are comments users can post to a snippet. If you create a note where the body only contains an Award Emoji, you'll receive this object back. -``` +```plaintext POST /projects/:id/snippets/:snippet_id/notes ``` @@ -242,7 +242,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Modify existing note of a snippet. -``` +```plaintext PUT /projects/:id/snippets/:snippet_id/notes/:note_id ``` @@ -261,7 +261,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab. Deletes an existing note of a snippet. -``` +```plaintext DELETE /projects/:id/snippets/:snippet_id/notes/:note_id ``` @@ -283,7 +283,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitl Gets a list of all notes for a single merge request. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/notes GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=updated_at ``` @@ -303,7 +303,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Returns a single note for a given merge request. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id ``` @@ -346,7 +346,7 @@ Creates a new note for a single merge request. If you create a note where the body only contains an Award Emoji, you'll receive this object back. -``` +```plaintext POST /projects/:id/merge_requests/:merge_request_iid/notes ``` @@ -361,7 +361,7 @@ Parameters: Modify existing note of a merge request. -``` +```plaintext PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id ``` @@ -380,7 +380,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab. Deletes an existing note of a merge request. -``` +```plaintext DELETE /projects/:id/merge_requests/:merge_request_iid/notes/:note_id ``` @@ -402,7 +402,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitl Gets a list of all notes for a single epic. Epic notes are comments users can post to an epic. -``` +```plaintext GET /groups/:id/epics/:epic_id/notes GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at ``` @@ -422,7 +422,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Returns a single note for a given epic. -``` +```plaintext GET /groups/:id/epics/:epic_id/notes/:note_id ``` @@ -462,7 +462,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Creates a new note for a single epic. Epic notes are comments users can post to an epic. If you create a note where the body only contains an Award Emoji, you'll receive this object back. -``` +```plaintext POST /groups/:id/epics/:epic_id/notes ``` @@ -482,7 +482,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Modify existing note of an epic. -``` +```plaintext PUT /groups/:id/epics/:epic_id/notes/:note_id ``` @@ -503,7 +503,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab. Deletes an existing note of an epic. -``` +```plaintext DELETE /groups/:id/epics/:epic_id/notes/:note_id ``` diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 71223669d5c..38a5e350bee 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -6,7 +6,7 @@ The notification levels are defined in the `NotificationSetting.level` model enumeration. Currently, these levels are recognized: -``` +```plaintext disabled participating watch @@ -37,7 +37,7 @@ If the `custom` level is used, specific email events can be controlled. Availabl Get current notification settings and email address. -``` +```plaintext GET /notification_settings ``` @@ -58,7 +58,7 @@ Example response: Update current notification settings and email address. -``` +```plaintext PUT /notification_settings ``` @@ -99,7 +99,7 @@ Example response: Get current group or project notification settings. -``` +```plaintext GET /groups/:id/notification_settings GET /projects/:id/notification_settings ``` @@ -125,7 +125,7 @@ Example response: Update current group/project notification settings. -``` +```plaintext PUT /groups/:id/notification_settings PUT /projects/:id/notification_settings ``` diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index c556f1e8108..a4a7d39383c 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -2,7 +2,7 @@ **CRUD for repository files** -**Create, read, update and delete repository files using this API** +**Create, read, update, and delete repository files using this API** The different scopes available using [personal access tokens](../user/profile/personal_access_tokens.md) are depicted in the following table. @@ -242,7 +242,7 @@ If the commit fails for any reason we return a 400 error with a non-specific error message. Possible causes for a failed commit include: - the `file_path` contained `/../` (attempted directory traversal); -- the new file contents were identical to the current file contents, i.e. the +- the new file contents were identical to the current file contents. That is, the user tried to make an empty commit; - the branch was updated by a Git push while the file edit was in progress. diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index 6532e2d4231..c33d41550c2 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.md @@ -1,6 +1,6 @@ # Resource label events API -Resource label events keep track about who, when, and which label was added or removed to an issuable. +Resource label events keep track about who, when, and which label was added to, or removed from, an issuable. ## Issues diff --git a/doc/api/services.md b/doc/api/services.md index 2f70cb21964..570442b09fd 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -567,7 +567,7 @@ Set Hangouts Chat service for a project. PUT /projects/:id/services/hangouts-chat ``` ->**Note:** Specific event parameters (e.g. `push_events` flag) were [introduced in v10.4][11435] +>**Note:** Specific event parameters (for example, `push_events` flag) were [introduced in v10.4][11435] Parameters: @@ -833,7 +833,7 @@ DELETE /projects/:id/services/mattermost-slash-commands ## Packagist -Update your project on Packagist, the main Composer repository, when commits or tags are pushed to GitLab. +Update your project on Packagist (the main Composer repository) when commits or tags are pushed to GitLab. ### Create/Edit Packagist service @@ -1068,7 +1068,7 @@ Set Slack service for a project. PUT /projects/:id/services/slack ``` ->**Note:** Specific event parameters (e.g. `push_events` flag and `push_channel`) were [introduced in v10.4][11435] +>**Note:** Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4][11435] Parameters: @@ -1177,7 +1177,7 @@ Set Mattermost service for a project. PUT /projects/:id/services/mattermost ``` ->**Note:** Specific event parameters (e.g. `push_events` flag and `push_channel`) were [introduced in v10.4][11435] +>**Note:** Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4][11435] Parameters: diff --git a/doc/api/settings.md b/doc/api/settings.md index cae51579afb..5ec05f39224 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -201,7 +201,7 @@ are listed in the descriptions of the relevant settings. | `commit_email_hostname` | string | no | Custom hostname (for private commit emails). | | `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes. | | `default_artifacts_expire_in` | string | no | Set the default expiration time for each job's artifacts. | -| `default_branch_protection` | integer | no | Determine if developers can push to master. Can take: `0` _(not protected, both developers and maintainers can push new commits, force push, or delete the branch)_, `1` _(partially protected, developers and maintainers can push new commits, but cannot force push or delete the branch)_ or `2` _(fully protected, developers cannot push new commits, but maintainers can; no-one can force push or delete the branch)_ as a parameter. Default is `2`. | +| `default_branch_protection` | integer | no | Determine if developers can push to master. Can take: `0` _(not protected, both developers and maintainers can push new commits, force push, or delete the branch)_, `1` _(partially protected, developers and maintainers can push new commits, but cannot force push, or delete, the branch)_ or `2` _(fully protected, developers cannot push new commits, but maintainers can; no-one can force push or delete the branch)_ as a parameter. Default is `2`. | | `default_ci_config_path` | string | no | Default CI configuration path for new projects (`.gitlab-ci.yml` if not set). | | `default_group_visibility` | string | no | What visibility level new groups receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `default_project_creation` | integer | no | Default project creation protection. Can take: `0` _(No one)_, `1` _(Maintainers)_ or `2` _(Developers + Maintainers)_| @@ -230,7 +230,7 @@ are listed in the descriptions of the relevant settings. | `elasticsearch_namespace_ids` | array of integers | no | **(PREMIUM)** The namespaces to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | | `elasticsearch_project_ids` | array of integers | no | **(PREMIUM)** The projects to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | | `elasticsearch_search` | boolean | no | **(PREMIUM)** Enable Elasticsearch search | -| `elasticsearch_url` | string | no | **(PREMIUM)** The url to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (e.g., `http://localhost:9200, http://localhost:9201"`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). | +| `elasticsearch_url` | string | no | **(PREMIUM)** The url to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (for example, `http://localhost:9200, http://localhost:9201"`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (for example, `http://<username>:<password>@<elastic_host>:9200/`). | | `email_additional_text` | string | no | **(PREMIUM)** Additional text added to the bottom of every email for legal/auditing/compliance reasons | | `email_author_in_body` | boolean | no | Some email servers do not support overriding the email sender name. Enable this option to include the name of the author of the issue, merge request or comment in the email body instead. | | `enabled_git_access_protocol` | string | no | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `nil` to allow both protocols. | @@ -323,23 +323,23 @@ are listed in the descriptions of the relevant settings. | `slack_app_id` | string | required by: `slack_app_enabled` | **(PREMIUM)** The app id of the Slack-app. | | `slack_app_secret` | string | required by: `slack_app_enabled` | **(PREMIUM)** The app secret of the Slack-app. | | `slack_app_verification_token` | string | required by: `slack_app_enabled` | **(PREMIUM)** The verification token of the Slack-app. | -| `snowplow_collector_hostname` | string | required by: `snowplow_enabled` | The Snowplow collector hostname. (e.g. `snowplow.trx.gitlab.net`) | -| `snowplow_cookie_domain` | string | no | The Snowplow cookie domain. (e.g. `.gitlab.com`) | +| `snowplow_collector_hostname` | string | required by: `snowplow_enabled` | The Snowplow collector hostname. (for example, `snowplow.trx.gitlab.net`) | +| `snowplow_cookie_domain` | string | no | The Snowplow cookie domain. (for example, `.gitlab.com`) | | `snowplow_enabled` | boolean | no | Enable snowplow tracking. | -| `snowplow_app_id` | string | no | The Snowplow site name / application id. (e.g. `gitlab`) | +| `snowplow_app_id` | string | no | The Snowplow site name / application id. (for example, `gitlab`) | | `snowplow_iglu_registry_url` | string | no | The Snowplow base Iglu Schema Registry URL to use for custom context and self describing events'| | `sourcegraph_enabled` | boolean | no | Enables Sourcegraph integration. Default is `false`. **If enabled, requires** `sourcegraph_url`. | | `sourcegraph_url` | string | required by: `sourcegraph_enabled` | The Sourcegraph instance URL for integration. | | `sourcegraph_public_only` | boolean | no | Blocks Sourcegraph from being loaded on private and internal projects. Default is `true`. | | `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to `0` for unlimited time. | | `terms` | text | required by: `enforce_terms` | (**Required by:** `enforce_terms`) Markdown content for the ToS. | -| `throttle_authenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (e.g. from crawlers or abusive bots). | +| `throttle_authenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | | `throttle_authenticated_api_period_in_seconds` | integer | required by: `throttle_authenticated_api_enabled` | Rate limit period in seconds. | | `throttle_authenticated_api_requests_per_period` | integer | required by: `throttle_authenticated_api_enabled` | Max requests per period per user. | -| `throttle_authenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_web_period_in_seconds` and `throttle_authenticated_web_requests_per_period`) Enable authenticated web request rate limit. Helps reduce request volume (e.g. from crawlers or abusive bots). | +| `throttle_authenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_web_period_in_seconds` and `throttle_authenticated_web_requests_per_period`) Enable authenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | | `throttle_authenticated_web_period_in_seconds` | integer | required by: `throttle_authenticated_web_enabled` | Rate limit period in seconds. | | `throttle_authenticated_web_requests_per_period` | integer | required by: `throttle_authenticated_web_enabled` | Max requests per period per user. | -| `throttle_unauthenticated_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_period_in_seconds` and `throttle_unauthenticated_requests_per_period`) Enable unauthenticated request rate limit. Helps reduce request volume (e.g. from crawlers or abusive bots). | +| `throttle_unauthenticated_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_period_in_seconds` and `throttle_unauthenticated_requests_per_period`) Enable unauthenticated request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | | `throttle_unauthenticated_period_in_seconds` | integer | required by: `throttle_unauthenticated_enabled` | Rate limit period in seconds. | | `throttle_unauthenticated_requests_per_period` | integer | required by: `throttle_unauthenticated_enabled` | Max requests per period per IP. | | `time_tracking_limit_to_hours` | boolean | no | Limit display of time tracking units to hours. Default is `false`. | diff --git a/doc/api/users.md b/doc/api/users.md index ecd3c306d81..2c1d68be964 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -435,8 +435,8 @@ Parameters: On password update, user will be forced to change it upon next login. Note, at the moment this method does only return a `404` error, -even in cases where a `409` (Conflict) would be more appropriate, -e.g. when renaming the email address to some existing one. +even in cases where a `409` (Conflict) would be more appropriate. +For example, when renaming the email address to some existing one. ## Delete authentication identity from user @@ -1389,7 +1389,7 @@ The activities that update the timestamp are: - Git HTTP/SSH activities (such as clone, push) - User logging in into GitLab -- User visiting pages related to Dashboards, Projects, Issues and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/54947) in GitLab 11.8) +- User visiting pages related to Dashboards, Projects, Issues, and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/54947) in GitLab 11.8) - User using the API By default, it shows the activity for all users in the last 6 months, but this can be @@ -1403,7 +1403,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `from` | string | no | Date string in the format YEAR-MONTH-DAY, e.g. `2016-03-11`. Defaults to 6 months ago. | +| `from` | string | no | Date string in the format YEAR-MONTH-DAY. For example, `2016-03-11`. Defaults to 6 months ago. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/activities diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 08419685388..777174eb280 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -12,7 +12,7 @@ run applications in independent "containers" that are run within a single Linux instance. [Docker Hub][hub] has a rich database of pre-built images that can be used to test and build your applications. -Docker, when used with GitLab CI, runs each job in a separate and isolated +When used with GitLab CI, Docker runs each job in a separate and isolated container using the predefined image that is set up in [`.gitlab-ci.yml`](../yaml/README.md). @@ -588,7 +588,7 @@ There are two ways to determine the value of `DOCKER_AUTH_CONFIG`: # Example output to copy bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= ``` - + Create the Docker JSON configuration content as follows: ```json diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 65dc65f23f5..166ed9b4571 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -118,7 +118,7 @@ NOTE: **Note:** The `environment` keyword defines where the app is deployed. The environment `name` and `url` is exposed in various places within GitLab. Each time a job that has an environment specified -succeeds, a deployment is recorded, along with the Git SHA and environment name. +succeeds, a deployment is recorded, along with the Git SHA, and environment name. CAUTION: **Caution**: Some characters are not allowed in environment names. Use only letters, diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md index f780a13998c..4ca817908ed 100644 --- a/doc/ci/examples/deployment/composer-npm-deploy.md +++ b/doc/ci/examples/deployment/composer-npm-deploy.md @@ -44,7 +44,7 @@ All these operations will put all files into a `build` folder, which is ready to ## How to transfer files to a live server -You have multiple options: rsync, scp, sftp and so on. For now, we will use scp. +You have multiple options: rsync, scp, sftp, and so on. For now, we will use scp. To make this work, you need to add a GitLab CI/CD Variable (accessible on `gitlab.example/your-project-name/variables`). That variable will be called `STAGING_PRIVATE_KEY` and it's the **private** SSH key of your server. diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index bf7aec7107f..4284038b283 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -22,7 +22,7 @@ and you know how to use GitLab. Laravel is a high quality web framework written in PHP. It has a great community with a [fantastic documentation](https://laravel.com/docs). -Aside from the usual routing, controllers, requests, responses, views, and (blade) templates, out of the box Laravel provides plenty of additional services such as cache, events, localization, authentication and many others. +Aside from the usual routing, controllers, requests, responses, views, and (blade) templates, out of the box Laravel provides plenty of additional services such as cache, events, localization, authentication, and many others. We will use [Envoy](https://laravel.com/docs/master/envoy) as an SSH task runner based on PHP. It uses a clean, minimal [Blade syntax](https://laravel.com/docs/master/blade) to set up tasks that can run on remote servers, such as, cloning your project from the repository, installing the Composer dependencies, and running [Artisan commands](https://laravel.com/docs/master/artisan). @@ -82,7 +82,7 @@ git push -u origin master ## Configure the production server Before we begin setting up Envoy and GitLab CI/CD, let's quickly make sure the production server is ready for deployment. -We have installed LEMP stack which stands for Linux, NGINX, MySQL and PHP on our Ubuntu 16.04. +We have installed LEMP stack which stands for Linux, NGINX, MySQL, and PHP on our Ubuntu 16.04. ### Create a new user @@ -194,7 +194,7 @@ To start, we create an `Envoy.blade.php` in the root of our app with a simple ta @endtask ``` -As you may expect, we have an array within `@servers` directive at the top of the file, which contains a key named `web` with a value of the server's address (e.g. `deployer@192.168.1.1`). +As you may expect, we have an array within `@servers` directive at the top of the file, which contains a key named `web` with a value of the server's address (for example, `deployer@192.168.1.1`). Then within our `@task` directive we define the bash commands that should be run on the server when the task is executed. On the local machine use the `run` command to run Envoy tasks. diff --git a/doc/ci/img/collapsible_log_v12_6.png b/doc/ci/img/collapsible_log_v12_6.png Binary files differindex 294421c645d..24b2c83f7c1 100644 --- a/doc/ci/img/collapsible_log_v12_6.png +++ b/doc/ci/img/collapsible_log_v12_6.png diff --git a/doc/ci/img/pipelines_duration_chart.png b/doc/ci/img/pipelines_duration_chart.png Binary files differnew file mode 100644 index 00000000000..0be7539ba0a --- /dev/null +++ b/doc/ci/img/pipelines_duration_chart.png diff --git a/doc/ci/img/pipelines_success_chart.png b/doc/ci/img/pipelines_success_chart.png Binary files differnew file mode 100644 index 00000000000..10602b75eeb --- /dev/null +++ b/doc/ci/img/pipelines_success_chart.png diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index ec8de8d6f6c..6ac3fa2c92d 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/index.md @@ -104,7 +104,7 @@ and that your repository is clean. [`GIT_CLEAN_FLAGS`](../yaml/README.md#git-clean-flags) is disabled when set to `none`. On very big repositories, this might be desired because `git clean` is disk I/O intensive. Controlling that with `GIT_CLEAN_FLAGS: -ffdx --e .build/`, for example, allows you to control and disable removal of some +-e .build/` (for example) allows you to control and disable removal of some directories within the worktree between subsequent runs, which can speed-up the incremental builds. This has the biggest effect if you re-use existing machines and have an existing worktree that you can re-use for builds. diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index e03d767079f..448525efbde 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -89,7 +89,7 @@ Read the [documentation on Merge Trains](pipelines_for_merged_results/merge_trai The behavior of the `only: [merge_requests]` parameter is such that _only_ jobs with that parameter are run in the context of a merge request; no other jobs will be run. -However, you may want to reverse this behavior, having all of your jobs to run _except_ +However, you can invert this behavior and have all of your jobs run _except_ for one or two. Consider the following pipeline, with jobs `A`, `B`, and `C`. Imagine you want: diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md index e5a77c1f0d6..bab93392587 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md @@ -111,7 +111,7 @@ To check and set these feature flag values, please ask an administrator to: Since pipelines for merged results are a run on a merge ref of a merge request (`refs/merge-requests/<iid>/merge`), the Git reference could be overwritten at an -unexpected timing, for example, when a source or target branch is advanced. +unexpected timing. For example, when a source or target branch is advanced. In this case, the pipeline fails because of `fatal: reference is not a tree:` error, which indicates that the checkout-SHA is not found in the merge ref. diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md index 744713b0678..e5949473d01 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md @@ -21,7 +21,7 @@ just as it works in the current state. However, instead of queuing and waiting, each item takes the completed state of the previous (pending) merge ref, adds its own changes, and starts the pipeline immediately in parallel under the assumption that everything is going to pass. -In this way, if all the pipelines in the train merge successfully, no pipeline time is wasted either queuing or retrying. +This means that if all the pipelines in the train merge successfully, no pipeline time is wasted either queuing or retrying. If the button is subsequently pressed in a different MR, instead of creating a new pipeline for the target branch, it creates a new pipeline targeting the merge result of the previous MR plus the target branch. Pipelines invalidated through failures are immediately canceled and requeued. @@ -83,7 +83,7 @@ button while the latest pipeline is running. ## Immediately merge a merge request with a merge train -In case, you have a high-priority merge request (e.g. critical patch) to be merged urgently, +In the case where you have a high-priority merge request (for example, a critical patch) to be merged urgently, you can use **Merge Immediately** option for bypassing the merge train. This is the fastest option to get the change merged into the target branch. diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index d9aa52eb233..bf59d06f582 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -38,7 +38,7 @@ Let's assume you deploy your web app from different projects in GitLab: - One for the paid version add-ons, which also pass through builds and tests - One for the documentation, which also builds, tests, and deploys with an SSG -With Multi-Project Pipelines, you can visualize the entire pipeline, including all stages of builds and tests for the three projects. +With Multi-Project Pipelines you can visualize the entire pipeline, including all build and test stages for the three projects. ## Triggering multi-project pipelines through API diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index 896097ccd3a..be6da22e074 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -107,50 +107,6 @@ For example:  -### How pipeline duration is calculated - -Total running time for a given pipeline excludes retries and pending -(queued) time. - -Each job is represented as a `Period`, which consists of: - -- `Period#first` (when the job started). -- `Period#last` (when the job finished). - -A simple example is: - -- A (1, 3) -- B (2, 4) -- C (6, 7) - -In the example: - -- A begins at 1 and ends at 3. -- B begins at 2 and ends at 4. -- C begins at 6 and ends at 7. - -Visually, it can be viewed as: - -```text -0 1 2 3 4 5 6 7 - AAAAAAA - BBBBBBB - CCCC -``` - -The union of A, B, and C is (1, 4) and (6, 7). Therefore, the total running time is: - -```text -(4 - 1) + (7 - 6) => 4 -``` - -### How pipeline quotas are used - -Each user has a personal pipeline quota that tracks the usage of shared runners in all personal projects. -Each group has a [usage quota](../subscriptions/index.md#ci-pipeline-minutes) that tracks the usage of shared runners for all projects created within the group. - -When a pipeline is triggered, regardless of who triggered it, the pipeline quota for the project owner's [namespace](../user/group/index.md#namespaces) is used. In this case, the namespace can be the user or group that owns the project. - ### Expanding and collapsing job log sections > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/14664) in GitLab @@ -203,6 +159,65 @@ this line should be hidden when collapsed section_end:1560896353:my_first_section\r\e[0K ``` +### Pipeline success and duration charts + +> - Introduced in GitLab 3.1.1 as Commit Stats, and later renamed to Pipeline Charts. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/issues/38318) to CI / CD Analytics in GitLab 12.8. + +GitLab tracks the history of your pipeline successes and failures, as well as how long each pipeline ran. To view this information, go to **Analytics > CI / CD Analytics**. + +View successful pipelines: + + + +View pipeline duration history: + + + +## Pipeline quotas + +Each user has a personal pipeline quota that tracks the usage of shared runners in all personal projects. +Each group has a [usage quota](../subscriptions/index.md#ci-pipeline-minutes) that tracks the usage of shared runners for all projects created within the group. + +When a pipeline is triggered, regardless of who triggered it, the pipeline quota for the project owner's [namespace](../user/group/index.md#namespaces) is used. In this case, the namespace can be the user or group that owns the project. + +### How pipeline duration is calculated + +Total running time for a given pipeline excludes retries and pending +(queued) time. + +Each job is represented as a `Period`, which consists of: + +- `Period#first` (when the job started). +- `Period#last` (when the job finished). + +A simple example is: + +- A (1, 3) +- B (2, 4) +- C (6, 7) + +In the example: + +- A begins at 1 and ends at 3. +- B begins at 2 and ends at 4. +- C begins at 6 and ends at 7. + +Visually, it can be viewed as: + +```text +0 1 2 3 4 5 6 7 + AAAAAAA + BBBBBBB + CCCC +``` + +The union of A, B, and C is (1, 4) and (6, 7). Therefore, the total running time is: + +```text +(4 - 1) + (7 - 6) => 4 +``` + ## Configuring pipelines Pipelines, and their component jobs and stages, are defined in the [`.gitlab-ci.yml`](yaml/README.md) file for each project. diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 6416e6ec745..91b4000b74a 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -195,11 +195,11 @@ We have following jobs in queue: With the fair usage algorithm jobs are assigned in following order: -1. Job 1 is chosen first, because it has the lowest job number from projects with no running jobs (i.e. all projects) +1. Job 1 is chosen first, because it has the lowest job number from projects with no running jobs (that is, all projects) 1. Job 4 is next, because 4 is now the lowest job number from projects with no running jobs (Project 1 has a job running) 1. Job 6 is next, because 6 is now the lowest job number from projects with no running jobs (Projects 1 and 2 have jobs running) 1. Job 2 is next, because, of projects with the lowest number of jobs running (each has 1), it is the lowest job number -1. Job 5 is next, because Project 1 now has 2 jobs running, and between Projects 2 and 3, Job 5 is the lowest remaining job number +1. Job 5 is next, because Project 1 now has 2 jobs running and Job 5 is the lowest remaining job number between Projects 2 and 3. 1. Lastly we choose Job 3... because it's the only job left --- @@ -217,7 +217,7 @@ We have following jobs in queue: With the fair usage algorithm jobs are assigned in following order: -1. Job 1 is chosen first, because it has the lowest job number from projects with no running jobs (i.e. all projects) +1. Job 1 is chosen first, because it has the lowest job number from projects with no running jobs (that is, all projects) 1. We finish job 1 1. Job 2 is next, because, having finished Job 1, all projects have 0 jobs running again, and 2 is the lowest available job number 1. Job 4 is next, because with Project 1 running a job, 4 is the lowest number from projects running no jobs (Projects 2 and 3) @@ -307,7 +307,7 @@ Example 2: For each Runner you can specify a _maximum job timeout_. Such timeout, if smaller than [project defined timeout], will take the precedence. This feature can be used to prevent Shared Runner from being appropriated -by a project by setting a ridiculous big timeout (e.g. one week). +by a project by setting a ridiculous big timeout (for example, one week). When not configured, Runner will not override project timeout. diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index aa03add0ac2..7e187d58e21 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -167,7 +167,7 @@ build_docs: - tags ``` -Now, whenever a new tag is pushed on project A, the job will run and the +This means that whenever a new tag is pushed on project A, the job will run and the `build_docs` job will be executed, triggering a rebuild of project B. The `stage: deploy` ensures that this job will run only after all jobs with `stage: test` complete successfully. diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index b9afa6dea14..8931ee43a8a 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -2905,7 +2905,7 @@ your configuration file is on. In other words, when using a `include:local`, mak sure that both `.gitlab-ci.yml` and the local file are on the same branch. All [nested includes](#nested-includes) will be executed in the scope of the same project, -so it is possible to use local, project, remote or template includes. +so it is possible to use local, project, remote, or template includes. NOTE: **Note:** Including local files through Git submodules paths is not supported. diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index e8aa33b31a7..96b256dc022 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -76,6 +76,28 @@ a new presenter specifically for GraphQL. The presenter is initialized using the object resolved by a field, and the context. +### Nullable fields + +GraphQL allows fields to be be "nullable" or "non-nullable". The former means +that `null` may be returned instead of a value of the specified type. **In +general**, you should prefer using nullable fields to non-nullable ones, for +the following reasons: + +- It's common for data to switch from required to not-required, and back again +- Even when there is no prospect of a field becoming optional, it may not be **available** at query time + - For instance, the `content` of a blob may need to be looked up from Gitaly + - If the `content` is nullable, we can return a **partial** response, instead of failing the whole query +- Changing from a non-nullable field to a nullable field is difficult with a versionless schema + +Non-nullable fields should only be used when a field is required, very unlikely +to become optional in the future, and very easy to calculate. An example would +be `id` fields. + +Further reading: + +- [GraphQL Best Practices Guide](https://graphql.org/learn/best-practices/#nullability) +- [Using nullability in GraphQL](https://blog.apollographql.com/using-nullability-in-graphql-2254f84c4ed7) + ### Exposing Global IDs When exposing an `ID` field on a type, we will by default try to diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 41ebcc7f2d0..d5394e30d6a 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -89,7 +89,7 @@ that it does so in the most appropriate way, that it satisfies all requirements, and that there are no remaining bugs, logical problems, uncovered edge cases, or known vulnerabilities. The best way to do this, and to avoid unnecessary back-and-forth with reviewers, is to perform a self-review of your own merge -request, following the [Code Review](#reviewing-code) guidelines. +request, following the [Code Review](#reviewing-a-merge-request) guidelines. To reach the required level of confidence in their solution, an author is expected to involve other people in the investigation and implementation processes as @@ -129,7 +129,7 @@ This ### The responsibility of the reviewer -[Review the merge request](#reviewing-code) thoroughly. When you are confident +[Review the merge request](#reviewing-a-merge-request) thoroughly. When you are confident that it meets all requirements, you should: - Click the Approve button. @@ -211,7 +211,7 @@ Instead these should be sent to the [Release Manager](https://about.gitlab.com/c mentioning them; this will ensure they see it if their notification level is set to "mentioned" and other people will understand they don't have to respond. -### Having your code reviewed +### Having your merge request reviewed Please keep in mind that code review is a process that can take multiple iterations, and reviewers may spot things later that they may not have seen the @@ -244,52 +244,17 @@ first time. If you want to have your merge request reviewed, you can assign it to any reviewer. The list of reviewers can be found on [Engineering projects](https://about.gitlab.com/handbook/engineering/projects/) page. -You can also use `ready for review` label. That means that your merge request is ready to be reviewed and any reviewer can pick it. It is recommended to use that label only if there isn't time pressure and make sure the merge request is assigned to a reviewer. +You can also use `workflow::ready for review` label. That means that your merge request is ready to be reviewed and any reviewer can pick it. It is recommended to use that label only if there isn't time pressure and make sure the merge request is assigned to a reviewer. When your merge request was reviewed and can be passed to a maintainer you can either pick a specific maintainer or use a label `ready for merge`. It is responsibility of the author of a merge request that the merge request is reviewed. If it stays in `ready for review` state too long it is recommended to assign it to a specific reviewer. -### List of merge requests ready for review +#### List of merge requests ready for review -Developers who have capacity can regularly check the list of [merge requests to review](https://gitlab.com/groups/gitlab-org/-/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&label_name%5B%5D=ready%20for%20review) and assign any merge request they want to review. +Developers who have capacity can regularly check the list of [merge requests to review](https://gitlab.com/groups/gitlab-org/-/merge_requests?state=opened&label_name%5B%5D=workflow%3A%3Aready%20for%20review) and assign any merge request they want to review. -### Review turnaround time - -Since [unblocking others is always a top priority](https://about.gitlab.com/handbook/values/#global-optimization), -reviewers are expected to review assigned merge requests in a timely manner, -even when this may negatively impact their other tasks and priorities. - -Doing so allows everyone involved in the merge request to iterate faster as the -context is fresh in memory, and improves contributors' experience significantly. - -#### Review-response SLO - -To ensure swift feedback to ready-to-review code, we maintain a `Review-response` Service-level Objective (SLO). The SLO is defined as: - -> - review-response SLO = (time when first review response is provided) - (time MR is assigned to reviewer) < 2 business days - -If you don't think you'll be able to review a merge request within the `Review-response` SLO -time frame, let the author know as soon as possible and try to help them find -another reviewer or maintainer who will be able to, so that they can be unblocked -and get on with their work quickly. - -If you think you are at capacity and are unable to accept any more reviews until -some have been completed, communicate this through your GitLab status by setting -the `:red_circle:` emoji and mentioning that you are at capacity in the status -text. This will guide contributors to pick a different reviewer, helping us to -meet the SLO. - -Of course, if you are out of office and have -[communicated](https://about.gitlab.com/handbook/paid-time-off/#communicating-your-time-off) -this through your GitLab.com Status, authors are expected to realize this and -find a different reviewer themselves. - -When a merge request author has been blocked for longer than -the `Review-response` SLO, they are free to remind the reviewer through Slack or assign -another reviewer. - -### Reviewing code +### Reviewing a merge request Understand why the change is necessary (fixes a bug, improves the user experience, refactors the existing code). Then: @@ -310,26 +275,47 @@ experience, refactors the existing code). Then: "LGTM :thumbsup:", or "Just a couple things to address." - Assign the merge request to the author if changes are required following your review. -- Set the milestone before merging a merge request. -- Ensure the target branch is not too far behind master. If -[master is red](https://about.gitlab.com/handbook/engineering/workflow/#broken-master), -it should be no more than 100 commits behind. + +### Merging a merge request + +Before taking the decision to merge: + +- Set the milestone. - Consider warnings and errors from danger bot, code quality, and other reports. -Unless a strong case can be made for the violation, these should be resolved -before merge. -- Ensure a passing CI pipeline or if [master is broken](https://about.gitlab.com/handbook/engineering/workflow/#broken-master), post a comment mentioning the failure happens in master with a -link to the ~"master:broken" issue. -- Avoid accepting a merge request before the job succeeds. Of course, "Merge - When Pipeline Succeeds" (MWPS) is fine. -- If you set the MR to "Merge When Pipeline Succeeds", you should take over - subsequent revisions for anything that would be spotted after that. + Unless a strong case can be made for the violation, these should be resolved + before merge. A comment must to be posted if the MR is merged with any failed job. + +When ready to merge: + - Consider using the [Squash and - merge][squash-and-merge] feature when the merge request has a lot of commits. + merge](../user/project/merge_requests/squash_and_merge.md#squash-and-merge) + feature when the merge request has a lot of commits. When merging code a maintainer should only use the squash feature if the author has already set this option or if the merge request clearly contains a messy commit history that is intended to be squashed. +- **Start a new merge request pipeline with the `Run Pipeline` button in the merge + request's "Pipelines" tab, and enable "Merge When Pipeline Succeeds" (MWPS).** Note that: + - If the **latest [Pipeline for Merged Results](../ci/merge_request_pipelines/pipelines_for_merged_results/#pipelines-for-merged-results-premium)** finished less than 2 hours ago, you + might merge without starting a new pipeline as the merge request is close + enough to `master`. + - If the merge request is from a fork, check how far behind `master` the + source branch is. If it's more than 100 commits behind, ask the author to + rebase it before merging. + - If [master is broken](https://about.gitlab.com/handbook/engineering/workflow/#broken-master), + in addition to the two above rules, check that any failure also happens + in `master` and post a link to the ~"master:broken" issue before clicking the + red "Merge" button. +- When you set the MR to "Merge When Pipeline Succeeds", you should take over + subsequent revisions for anything that would be spotted after that. -[squash-and-merge]: ../user/project/merge_requests/squash_and_merge.md#squash-and-merge +NOTE: **Note:** +Thanks to "Pipeline for Merged Results", authors won't have to rebase their +branch as frequently anymore (only when there are conflicts) since the Merge +Results Pipeline will already incorporate the latest changes from `master`. +This results in faster review/merge cycles since maintainers don't have to ask +for a final rebase: instead, they only have to start a MR pipeline and set MWPS. +This step brings us very close to the actual Merge Trains feature by testing the +Merge Results against the latest `master` at the time of the pipeline creation. ### The right balance @@ -411,6 +397,41 @@ Enterprise Edition instance. This has some implications: 1. **Filesystem access** can be slow, so try to avoid [shared files](shared_files.md) when an alternative solution is available. +### Review turnaround time + +Since [unblocking others is always a top priority](https://about.gitlab.com/handbook/values/#global-optimization), +reviewers are expected to review assigned merge requests in a timely manner, +even when this may negatively impact their other tasks and priorities. + +Doing so allows everyone involved in the merge request to iterate faster as the +context is fresh in memory, and improves contributors' experience significantly. + +#### Review-response SLO + +To ensure swift feedback to ready-to-review code, we maintain a `Review-response` Service-level Objective (SLO). The SLO is defined as: + +> - review-response SLO = (time when first review response is provided) - (time MR is assigned to reviewer) < 2 business days + +If you don't think you'll be able to review a merge request within the `Review-response` SLO +time frame, let the author know as soon as possible and try to help them find +another reviewer or maintainer who will be able to, so that they can be unblocked +and get on with their work quickly. + +If you think you are at capacity and are unable to accept any more reviews until +some have been completed, communicate this through your GitLab status by setting +the `:red_circle:` emoji and mentioning that you are at capacity in the status +text. This will guide contributors to pick a different reviewer, helping us to +meet the SLO. + +Of course, if you are out of office and have +[communicated](https://about.gitlab.com/handbook/paid-time-off/#communicating-your-time-off) +this through your GitLab.com Status, authors are expected to realize this and +find a different reviewer themselves. + +When a merge request author has been blocked for longer than +the `Review-response` SLO, they are free to remind the reviewer through Slack or assign +another reviewer. + ## Examples How code reviews are conducted can surprise new contributors. Here are some examples of code reviews that should help to orient you as to what to expect. diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md index 24608cc1a5e..61df572a6d2 100644 --- a/doc/development/documentation/site_architecture/release_process.md +++ b/doc/development/documentation/site_architecture/release_process.md @@ -128,16 +128,6 @@ version and rotates the old one: - `online`: The 3 latest stable versions. - `offline`: All the previous versions offered as an offline archive. -1. **Add the new offline version in the 404 page redirect script:** - - Since we're deprecating the oldest version each month, we need to redirect - those URLs in order not to create [404 entries](https://gitlab.com/gitlab-org/gitlab-docs/issues/221). - There's a temporary hack for now: - - 1. Edit `content/404.html`, making sure all offline versions under - `content/_data/versions.yaml` are in the JavaScript snippet at the end of - the document. - 1. **Update the `:latest` and `:archives` Docker images:** The following two Dockerfiles need to be updated: |
