diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-02-28 06:09:04 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-02-28 06:09:04 +0300 |
commit | 597a43f359c3096d845e764b90439743962e5961 (patch) | |
tree | 2593024f91b2eb44e0764107490be4d0f1119ace /doc | |
parent | f54a50aa826d0eedcf2e56f51462613bc132f826 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/releases/index.md | 10 | ||||
-rw-r--r-- | doc/api/repositories.md | 26 | ||||
-rw-r--r-- | doc/api/repository_files.md | 14 | ||||
-rw-r--r-- | doc/api/repository_submodules.md | 2 | ||||
-rw-r--r-- | doc/api/resource_label_events.md | 12 | ||||
-rw-r--r-- | doc/api/runners.md | 48 | ||||
-rw-r--r-- | doc/api/scim.md | 2 | ||||
-rw-r--r-- | doc/api/search.md | 4 | ||||
-rw-r--r-- | doc/api/services.md | 200 | ||||
-rw-r--r-- | doc/ci/services/postgres.md | 13 | ||||
-rw-r--r-- | doc/development/database/add_foreign_key_to_existing_column.md | 136 | ||||
-rw-r--r-- | doc/development/migration_style_guide.md | 2 | ||||
-rw-r--r-- | doc/user/project/integrations/webhooks.md | 2 |
13 files changed, 305 insertions, 166 deletions
diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index e24dea3c278..88fdedfa1b8 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -9,7 +9,7 @@ Paginated list of Releases, sorted by `released_at`. -``` +```plaintext GET /projects/:id/releases ``` @@ -191,7 +191,7 @@ Example response: Get a Release for the given tag. -``` +```plaintext GET /projects/:id/releases/:tag_name ``` @@ -303,7 +303,7 @@ Example response: Create a Release. You need push access to the repository to create a Release. -``` +```plaintext POST /projects/:id/releases ``` @@ -430,7 +430,7 @@ Example response: Update a Release. -``` +```plaintext PUT /projects/:id/releases/:tag_name ``` @@ -533,7 +533,7 @@ Example response: Delete a Release. Deleting a Release will not delete the associated tag. -``` +```plaintext DELETE /projects/:id/releases/:tag_name ``` diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 3e34e1522e4..35762e3150f 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -7,7 +7,7 @@ be accessed without authentication if the repository is publicly accessible. This command provides essentially the same functionality as the `git ls-tree` command. For more information, see the section _Tree Objects_ in the [Git internals documentation](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects/#_tree_objects). -``` +```plaintext GET /projects/:id/repository/tree ``` @@ -79,7 +79,7 @@ Allows you to receive information about blob in repository like size and content. Note that blob content is Base64 encoded. This endpoint can be accessed without authentication if the repository is publicly accessible. -``` +```plaintext GET /projects/:id/repository/blobs/:sha ``` @@ -93,7 +93,7 @@ Parameters: Get the raw file contents for a blob by blob SHA. This endpoint can be accessed without authentication if the repository is publicly accessible. -``` +```plaintext GET /projects/:id/repository/blobs/:sha/raw ``` @@ -107,7 +107,7 @@ Parameters: Get an archive of the repository. This endpoint can be accessed without authentication if the repository is publicly accessible. -``` +```plaintext GET /projects/:id/repository/archive[.format] ``` @@ -130,7 +130,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.com/api/v4/pro This endpoint can be accessed without authentication if the repository is publicly accessible. Note that diffs could have an empty diff string if [diff limits](../development/diffs.md#diff-limits) are reached. -``` +```plaintext GET /projects/:id/repository/compare ``` @@ -141,7 +141,7 @@ Parameters: - `to` (required) - the commit SHA or branch name - `straight` (optional) - comparison method, `true` for direct comparison between `from` and `to` (`from`..`to`), `false` to compare using merge base (`from`...`to`)'. Default is `false`. -``` +```plaintext GET /projects/:id/repository/compare?from=master&to=feature ``` @@ -186,7 +186,7 @@ Response: Get repository contributors list. This endpoint can be accessed without authentication if the repository is publicly accessible. -``` +```plaintext GET /projects/:id/repository/contributors ``` @@ -198,16 +198,16 @@ Parameters: Response: -``` +```json [{ - "name": "Dmitriy Zaporozhets", - "email": "dmitriy.zaporozhets@gmail.com", + "name": "Example User", + "email": "example@example.com", "commits": 117, "additions": 2097, "deletions": 517 }, { - "name": "Jacob Vosmaer", - "email": "contact@jacobvosmaer.nl", + "name": "Sample User", + "email": "sample@example.com", "commits": 33, "additions": 338, "deletions": 244 @@ -218,7 +218,7 @@ Response: Get the common ancestor for 2 or more refs (commit SHAs, branch names or tags). -``` +```plaintext GET /projects/:id/repository/merge_base ``` diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index a4a7d39383c..f22d315da00 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -20,7 +20,7 @@ Allows you to receive information about file in repository like name, size, content. Note that file content is Base64 encoded. This endpoint can be accessed without authentication if the repository is publicly accessible. -``` +```plaintext GET /projects/:id/repository/files/:file_path ``` @@ -55,7 +55,7 @@ NOTE: **Note:** In addition to the `GET` method, you can also use `HEAD` to get just file metadata. -``` +```plaintext HEAD /projects/:id/repository/files/:file_path ``` @@ -84,7 +84,7 @@ X-Gitlab-Size: 1476 Allows you to receive blame information. Each blame range contains lines and corresponding commit info. -``` +```plaintext GET /projects/:id/repository/files/:file_path/blame ``` @@ -151,7 +151,7 @@ X-Gitlab-Size: 1476 ## Get raw file from repository -``` +```plaintext GET /projects/:id/repository/files/:file_path/raw ``` @@ -171,7 +171,7 @@ Like [Get file from repository](repository_files.md#get-file-from-repository) yo This allows you to create a single file. For creating multiple files with a single request see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions). -``` +```plaintext POST /projects/:id/repository/files/:file_path ``` @@ -206,7 +206,7 @@ Parameters: This allows you to update a single file. For updating multiple files with a single request see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions). -``` +```plaintext PUT /projects/:id/repository/files/:file_path ``` @@ -252,7 +252,7 @@ Currently GitLab Shell has a boolean return code, preventing GitLab from specify This allows you to delete a single file. For deleting multiple files with a single request, see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions). -``` +```plaintext DELETE /projects/:id/repository/files/:file_path ``` diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md index 59f6131fc96..2ae7afa35b2 100644 --- a/doc/api/repository_submodules.md +++ b/doc/api/repository_submodules.md @@ -9,7 +9,7 @@ submodule's reference to keep up to date other projects that use it. This endpoint allows you to update a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) reference in a specific branch. -``` +```plaintext PUT /projects/:id/repository/submodules/:submodule ``` diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index c33d41550c2..20f48674932 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.md @@ -8,7 +8,7 @@ Resource label events keep track about who, when, and which label was added to, Gets a list of all label events for a single issue. -``` +```plaintext GET /projects/:id/issues/:issue_iid/resource_label_events ``` @@ -72,7 +72,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Returns a single label event for a specific project issue -``` +```plaintext GET /projects/:id/issues/:issue_iid/resource_label_events/:resource_label_event_id ``` @@ -94,7 +94,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Gets a list of all label events for a single epic. -``` +```plaintext GET /groups/:id/epics/:epic_id/resource_label_events ``` @@ -158,7 +158,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Returns a single label event for a specific group epic -``` +```plaintext GET /groups/:id/epics/:epic_id/resource_label_events/:resource_label_event_id ``` @@ -180,7 +180,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Gets a list of all label events for a single merge request. -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/resource_label_events ``` @@ -244,7 +244,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Returns a single label event for a specific project merge request -``` +```plaintext GET /projects/:id/merge_requests/:merge_request_iid/resource_label_events/:resource_label_event_id ``` diff --git a/doc/api/runners.md b/doc/api/runners.md index 53ca97b9e41..551a7580e54 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -31,7 +31,7 @@ GitLab and Runner are then connected. Get a list of specific runners available to the user. -``` +```plaintext GET /runners GET /runners?scope=active GET /runners?type=project_type @@ -46,7 +46,7 @@ GET /runners?tag_list=tag1,tag2 | `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | | `tag_list` | string array | no | List of of the runner's tags | -``` +```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners" ``` @@ -82,7 +82,7 @@ Example response: Get a list of all runners in the GitLab instance (specific and shared). Access is restricted to users with `admin` privileges. -``` +```plaintext GET /runners/all GET /runners/all?scope=online GET /runners/all?type=project_type @@ -97,7 +97,7 @@ GET /runners/all?tag_list=tag1,tag2 | `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | | `tag_list` | string array | no | List of of the runner's tags | -``` +```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all" ``` @@ -152,7 +152,7 @@ Example response: Get details of a runner. -``` +```plaintext GET /runners/:id ``` @@ -160,7 +160,7 @@ GET /runners/:id |-----------|---------|----------|---------------------| | `id` | integer | yes | The ID of a runner | -``` +```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" ``` @@ -204,7 +204,7 @@ Example response: Update details of a runner. -``` +```plaintext PUT /runners/:id ``` @@ -219,7 +219,7 @@ PUT /runners/:id | `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | | `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job | -``` +```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" ``` @@ -265,7 +265,7 @@ Example response: Remove a runner. -``` +```plaintext DELETE /runners/:id ``` @@ -273,7 +273,7 @@ DELETE /runners/:id |-----------|---------|----------|---------------------| | `id` | integer | yes | The ID of a runner | -``` +```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" ``` @@ -283,7 +283,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git List jobs that are being processed or were processed by specified Runner. -``` +```plaintext GET /runners/:id/jobs ``` @@ -294,7 +294,7 @@ GET /runners/:id/jobs | `order_by`| string | no | Order jobs by `id`. | | `sort` | string | no | Sort jobs in `asc` or `desc` order (default: `desc`) | -``` +```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running" ``` @@ -373,7 +373,7 @@ Example response: List all runners (specific and shared) available in the project. Shared runners are listed if at least one shared runner is defined. -``` +```plaintext GET /projects/:id/runners GET /projects/:id/runners?scope=active GET /projects/:id/runners?type=project_type @@ -389,7 +389,7 @@ GET /projects/:id/runners?tag_list=tag1,tag2 | `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | | `tag_list` | string array | no | List of of the runner's tags | -``` +```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" ``` @@ -424,7 +424,7 @@ Example response: Enable an available specific runner in the project. -``` +```plaintext POST /projects/:id/runners ``` @@ -433,7 +433,7 @@ POST /projects/:id/runners | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `runner_id` | integer | yes | The ID of a runner | -``` +```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" --form "runner_id=9" ``` @@ -458,7 +458,7 @@ Disable a specific runner from the project. It works only if the project isn't the only project associated with the specified runner. If so, an error is returned. Use the [Remove a runner](#remove-a-runner) call instead. -``` +```plaintext DELETE /projects/:id/runners/:runner_id ``` @@ -467,7 +467,7 @@ DELETE /projects/:id/runners/:runner_id | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `runner_id` | integer | yes | The ID of a runner | -``` +```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9" ``` @@ -475,7 +475,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git Register a new Runner for the instance. -``` +```plaintext POST /runners ``` @@ -491,7 +491,7 @@ POST /runners | `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | | `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job | -``` +```shell curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=<registration_token>" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" ``` @@ -514,7 +514,7 @@ Example response: Deletes a registered Runner. -``` +```plaintext DELETE /runners ``` @@ -522,7 +522,7 @@ DELETE /runners |-------------|---------|----------|---------------------| | `token` | string | yes | Runner's [authentication token](#registration-and-authentication-tokens). | -``` +```shell curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=<authentication_token>" ``` @@ -536,7 +536,7 @@ Response: Validates authentication credentials for a registered Runner. -``` +```plaintext POST /runners/verify ``` @@ -544,7 +544,7 @@ POST /runners/verify |-------------|---------|----------|---------------------| | `token` | string | yes | Runner's [authentication token](#registration-and-authentication-tokens). | -``` +```shell curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=<authentication_token>" ``` diff --git a/doc/api/scim.md b/doc/api/scim.md index 11721517cbb..cdd635d0627 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -219,7 +219,7 @@ They match an expression as specified in [the RFC7644 filtering section](https:/ Example: -``` +```plaintext id eq a-b-c-d ``` diff --git a/doc/api/search.md b/doc/api/search.md index 8203fbecbb3..78f68ed20e3 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -8,7 +8,7 @@ Every API call to search must be authenticated. Search globally across the GitLab instance. -``` +```plaintext GET /search ``` @@ -410,7 +410,7 @@ Search within the specified group. If a user is not a member of a group and the group is private, a `GET` request on that group will result to a `404` status code. -``` +```plaintext GET /groups/:id/search ``` diff --git a/doc/api/services.md b/doc/api/services.md index 570442b09fd..0d749150909 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -8,7 +8,7 @@ Get a list of all active project services. -``` +```plaintext GET /projects/:id/services ``` @@ -69,7 +69,7 @@ Set Asana service for a project. > This service adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, `https://app.asana.com/0/123456/987654`) or task IDs starting with # (for example, `#987654`). Every task ID found will get the commit comment added to it. You can also close a task with a message containing: `fix #123456`. You can find your API Keys here: <https://asana.com/developers/documentation/getting-started/auth#api-key>. -``` +```plaintext PUT /projects/:id/services/asana ``` @@ -85,7 +85,7 @@ Parameters: Delete Asana service for a project. -``` +```plaintext DELETE /projects/:id/services/asana ``` @@ -93,7 +93,7 @@ DELETE /projects/:id/services/asana Get Asana service settings for a project. -``` +```plaintext GET /projects/:id/services/asana ``` @@ -105,7 +105,7 @@ Project Management Software (Source Commits Endpoint) Set Assembla service for a project. -``` +```plaintext PUT /projects/:id/services/assembla ``` @@ -121,7 +121,7 @@ Parameters: Delete Assembla service for a project. -``` +```plaintext DELETE /projects/:id/services/assembla ``` @@ -129,7 +129,7 @@ DELETE /projects/:id/services/assembla Get Assembla service settings for a project. -``` +```plaintext GET /projects/:id/services/assembla ``` @@ -143,7 +143,7 @@ Set Atlassian Bamboo CI service for a project. > You must set up automatic revision labeling and a repository trigger in Bamboo. -``` +```plaintext PUT /projects/:id/services/bamboo ``` @@ -161,7 +161,7 @@ Parameters: Delete Atlassian Bamboo CI service for a project. -``` +```plaintext DELETE /projects/:id/services/bamboo ``` @@ -169,7 +169,7 @@ DELETE /projects/:id/services/bamboo Get Atlassian Bamboo CI service settings for a project. -``` +```plaintext GET /projects/:id/services/bamboo ``` @@ -181,7 +181,7 @@ Bugzilla Issue Tracker Set Bugzilla service for a project. -``` +```plaintext PUT /projects/:id/services/bugzilla ``` @@ -200,7 +200,7 @@ Parameters: Delete Bugzilla service for a project. -``` +```plaintext DELETE /projects/:id/services/bugzilla ``` @@ -208,7 +208,7 @@ DELETE /projects/:id/services/bugzilla Get Bugzilla service settings for a project. -``` +```plaintext GET /projects/:id/services/bugzilla ``` @@ -220,7 +220,7 @@ Continuous integration and deployments Set Buildkite service for a project. -``` +```plaintext PUT /projects/:id/services/buildkite ``` @@ -237,7 +237,7 @@ Parameters: Delete Buildkite service for a project. -``` +```plaintext DELETE /projects/:id/services/buildkite ``` @@ -245,7 +245,7 @@ DELETE /projects/:id/services/buildkite Get Buildkite service settings for a project. -``` +```plaintext GET /projects/:id/services/buildkite ``` @@ -257,7 +257,7 @@ Simple web-based real-time group chat Set Campfire service for a project. -``` +```plaintext PUT /projects/:id/services/campfire ``` @@ -274,7 +274,7 @@ Parameters: Delete Campfire service for a project. -``` +```plaintext DELETE /projects/:id/services/campfire ``` @@ -282,7 +282,7 @@ DELETE /projects/:id/services/campfire Get Campfire service settings for a project. -``` +```plaintext GET /projects/:id/services/campfire ``` @@ -294,7 +294,7 @@ Unify Circuit RTC and collaboration tool. Set Unify Circuit service for a project. -``` +```plaintext PUT /projects/:id/services/unify-circuit ``` @@ -319,7 +319,7 @@ Parameters: Delete Unify Circuit service for a project. -``` +```plaintext DELETE /projects/:id/services/unify-circuit ``` @@ -327,7 +327,7 @@ DELETE /projects/:id/services/unify-circuit Get Unify Circuit service settings for a project. -``` +```plaintext GET /projects/:id/services/unify-circuit ``` @@ -339,7 +339,7 @@ Custom issue tracker Set Custom Issue Tracker service for a project. -``` +```plaintext PUT /projects/:id/services/custom-issue-tracker ``` @@ -358,7 +358,7 @@ Parameters: Delete Custom Issue Tracker service for a project. -``` +```plaintext DELETE /projects/:id/services/custom-issue-tracker ``` @@ -366,7 +366,7 @@ DELETE /projects/:id/services/custom-issue-tracker Get Custom Issue Tracker service settings for a project. -``` +```plaintext GET /projects/:id/services/custom-issue-tracker ``` @@ -378,7 +378,7 @@ Drone is a Continuous Integration platform built on Docker, written in Go Set Drone CI service for a project. -``` +```plaintext PUT /projects/:id/services/drone-ci ``` @@ -397,7 +397,7 @@ Parameters: Delete Drone CI service for a project. -``` +```plaintext DELETE /projects/:id/services/drone-ci ``` @@ -405,7 +405,7 @@ DELETE /projects/:id/services/drone-ci Get Drone CI service settings for a project. -``` +```plaintext GET /projects/:id/services/drone-ci ``` @@ -417,7 +417,7 @@ Email the commits and diff of each push to a list of recipients. Set Emails on push service for a project. -``` +```plaintext PUT /projects/:id/services/emails-on-push ``` @@ -436,7 +436,7 @@ Parameters: Delete Emails on push service for a project. -``` +```plaintext DELETE /projects/:id/services/emails-on-push ``` @@ -444,7 +444,7 @@ DELETE /projects/:id/services/emails-on-push Get Emails on push service settings for a project. -``` +```plaintext GET /projects/:id/services/emails-on-push ``` @@ -456,7 +456,7 @@ Replaces the link to the internal wiki with a link to an external wiki. Set External Wiki service for a project. -``` +```plaintext PUT /projects/:id/services/external-wiki ``` @@ -470,7 +470,7 @@ Parameters: Delete External Wiki service for a project. -``` +```plaintext DELETE /projects/:id/services/external-wiki ``` @@ -478,7 +478,7 @@ DELETE /projects/:id/services/external-wiki Get External Wiki service settings for a project. -``` +```plaintext GET /projects/:id/services/external-wiki ``` @@ -490,7 +490,7 @@ Flowdock is a collaboration web app for technical teams. Set Flowdock service for a project. -``` +```plaintext PUT /projects/:id/services/flowdock ``` @@ -505,7 +505,7 @@ Parameters: Delete Flowdock service for a project. -``` +```plaintext DELETE /projects/:id/services/flowdock ``` @@ -513,7 +513,7 @@ DELETE /projects/:id/services/flowdock Get Flowdock service settings for a project. -``` +```plaintext GET /projects/:id/services/flowdock ``` @@ -525,7 +525,7 @@ Code collaboration software. Set GitHub service for a project. -``` +```plaintext PUT /projects/:id/services/github ``` @@ -541,7 +541,7 @@ Parameters: Delete GitHub service for a project. -``` +```plaintext DELETE /projects/:id/services/github ``` @@ -549,7 +549,7 @@ DELETE /projects/:id/services/github Get GitHub service settings for a project. -``` +```plaintext GET /projects/:id/services/github ``` @@ -563,7 +563,7 @@ Google GSuite team collaboration tool. Set Hangouts Chat service for a project. -``` +```plaintext PUT /projects/:id/services/hangouts-chat ``` @@ -591,7 +591,7 @@ Parameters: Delete Hangouts Chat service for a project. -``` +```plaintext DELETE /projects/:id/services/hangouts-chat ``` @@ -599,7 +599,7 @@ DELETE /projects/:id/services/hangouts-chat Get Hangouts Chat service settings for a project. -``` +```plaintext GET /projects/:id/services/hangouts-chat ``` @@ -611,7 +611,7 @@ Private group chat and IM Set HipChat service for a project. -``` +```plaintext PUT /projects/:id/services/hipchat ``` @@ -638,7 +638,7 @@ Parameters: Delete HipChat service for a project. -``` +```plaintext DELETE /projects/:id/services/hipchat ``` @@ -646,7 +646,7 @@ DELETE /projects/:id/services/hipchat Get HipChat service settings for a project. -``` +```plaintext GET /projects/:id/services/hipchat ``` @@ -660,7 +660,7 @@ Set Irker (IRC gateway) service for a project. > NOTE: Irker does NOT have built-in authentication, which makes it vulnerable to spamming IRC channels if it is hosted outside of a firewall. Please make sure you run the daemon within a secured network to prevent abuse. For more details, read: <http://www.catb.org/~esr/irker/security.html>. -``` +```plaintext PUT /projects/:id/services/irker ``` @@ -679,7 +679,7 @@ Parameters: Delete Irker (IRC gateway) service for a project. -``` +```plaintext DELETE /projects/:id/services/irker ``` @@ -687,7 +687,7 @@ DELETE /projects/:id/services/irker Get Irker (IRC gateway) service settings for a project. -``` +```plaintext GET /projects/:id/services/irker ``` @@ -699,7 +699,7 @@ Jira issue tracker. Get Jira service settings for a project. -``` +```plaintext GET /projects/:id/services/jira ``` @@ -711,7 +711,7 @@ Set Jira service for a project. > `project_url` are replaced by `url`. If you are using an > older version, [follow this documentation](https://gitlab.com/gitlab-org/gitlab/blob/8-13-stable-ee/doc/api/services.md#jira). -``` +```plaintext PUT /projects/:id/services/jira ``` @@ -733,7 +733,7 @@ Parameters: Remove all previously Jira settings from a project. -``` +```plaintext DELETE /projects/:id/services/jira ``` @@ -745,7 +745,7 @@ Ability to receive slash commands from a Slack chat instance. Get Slack slash command service settings for a project. -``` +```plaintext GET /projects/:id/services/slack-slash-commands ``` @@ -778,7 +778,7 @@ Example response: Set Slack slash command for a project. -``` +```plaintext PUT /projects/:id/services/slack-slash-commands ``` @@ -792,7 +792,7 @@ Parameters: Delete Slack slash command service for a project. -``` +```plaintext DELETE /projects/:id/services/slack-slash-commands ``` @@ -804,7 +804,7 @@ Ability to receive slash commands from a Mattermost chat instance. Get Mattermost slash command service settings for a project. -``` +```plaintext GET /projects/:id/services/mattermost-slash-commands ``` @@ -812,7 +812,7 @@ GET /projects/:id/services/mattermost-slash-commands Set Mattermost slash command for a project. -``` +```plaintext PUT /projects/:id/services/mattermost-slash-commands ``` @@ -827,7 +827,7 @@ Parameters: Delete Mattermost slash command service for a project. -``` +```plaintext DELETE /projects/:id/services/mattermost-slash-commands ``` @@ -839,7 +839,7 @@ Update your project on Packagist (the main Composer repository) when commits or Set Packagist service for a project. -``` +```plaintext PUT /projects/:id/services/packagist ``` @@ -858,7 +858,7 @@ Parameters: Delete Packagist service for a project. -``` +```plaintext DELETE /projects/:id/services/packagist ``` @@ -866,7 +866,7 @@ DELETE /projects/:id/services/packagist Get Packagist service settings for a project. -``` +```plaintext GET /projects/:id/services/packagist ``` @@ -878,7 +878,7 @@ Get emails for GitLab CI pipelines. Set Pipeline-Emails service for a project. -``` +```plaintext PUT /projects/:id/services/pipelines-email ``` @@ -897,7 +897,7 @@ Parameters: Delete Pipeline-Emails service for a project. -``` +```plaintext DELETE /projects/:id/services/pipelines-email ``` @@ -905,7 +905,7 @@ DELETE /projects/:id/services/pipelines-email Get Pipeline-Emails service settings for a project. -``` +```plaintext GET /projects/:id/services/pipelines-email ``` @@ -917,7 +917,7 @@ Project Management Software (Source Commits Endpoint) Set PivotalTracker service for a project. -``` +```plaintext PUT /projects/:id/services/pivotaltracker ``` @@ -933,7 +933,7 @@ Parameters: Delete PivotalTracker service for a project. -``` +```plaintext DELETE /projects/:id/services/pivotaltracker ``` @@ -941,7 +941,7 @@ DELETE /projects/:id/services/pivotaltracker Get PivotalTracker service settings for a project. -``` +```plaintext GET /projects/:id/services/pivotaltracker ``` @@ -953,7 +953,7 @@ Prometheus is a powerful time-series monitoring service. Set Prometheus service for a project. -``` +```plaintext PUT /projects/:id/services/prometheus ``` @@ -967,7 +967,7 @@ Parameters: Delete Prometheus service for a project. -``` +```plaintext DELETE /projects/:id/services/prometheus ``` @@ -975,7 +975,7 @@ DELETE /projects/:id/services/prometheus Get Prometheus service settings for a project. -``` +```plaintext GET /projects/:id/services/prometheus ``` @@ -987,7 +987,7 @@ Pushover makes it easy to get real-time notifications on your Android device, iP Set Pushover service for a project. -``` +```plaintext PUT /projects/:id/services/pushover ``` @@ -1006,7 +1006,7 @@ Parameters: Delete Pushover service for a project. -``` +```plaintext DELETE /projects/:id/services/pushover ``` @@ -1014,7 +1014,7 @@ DELETE /projects/:id/services/pushover Get Pushover service settings for a project. -``` +```plaintext GET /projects/:id/services/pushover ``` @@ -1026,7 +1026,7 @@ Redmine issue tracker Set Redmine service for a project. -``` +```plaintext PUT /projects/:id/services/redmine ``` @@ -1044,7 +1044,7 @@ Parameters: Delete Redmine service for a project. -``` +```plaintext DELETE /projects/:id/services/redmine ``` @@ -1052,7 +1052,7 @@ DELETE /projects/:id/services/redmine Get Redmine service settings for a project. -``` +```plaintext GET /projects/:id/services/redmine ``` @@ -1064,7 +1064,7 @@ Receive event notifications in Slack Set Slack service for a project. -``` +```plaintext PUT /projects/:id/services/slack ``` @@ -1107,7 +1107,7 @@ Parameters: Delete Slack service for a project. -``` +```plaintext DELETE /projects/:id/services/slack ``` @@ -1115,7 +1115,7 @@ DELETE /projects/:id/services/slack Get Slack service settings for a project. -``` +```plaintext GET /projects/:id/services/slack ``` @@ -1127,7 +1127,7 @@ Group Chat Software Set Microsoft Teams service for a project. -``` +```plaintext PUT /projects/:id/services/microsoft-teams ``` @@ -1153,7 +1153,7 @@ Parameters: Delete Microsoft Teams service for a project. -``` +```plaintext DELETE /projects/:id/services/microsoft-teams ``` @@ -1161,7 +1161,7 @@ DELETE /projects/:id/services/microsoft-teams Get Microsoft Teams service settings for a project. -``` +```plaintext GET /projects/:id/services/microsoft-teams ``` @@ -1173,7 +1173,7 @@ Receive event notifications in Mattermost Set Mattermost service for a project. -``` +```plaintext PUT /projects/:id/services/mattermost ``` @@ -1212,7 +1212,7 @@ Parameters: Delete Mattermost Notifications service for a project. -``` +```plaintext DELETE /projects/:id/services/mattermost ``` @@ -1220,7 +1220,7 @@ DELETE /projects/:id/services/mattermost Get Mattermost notifications service settings for a project. -``` +```plaintext GET /projects/:id/services/mattermost ``` @@ -1234,7 +1234,7 @@ Set JetBrains TeamCity CI service for a project. > The build configuration in Teamcity must use the build format number %build.vcs.number% you will also want to configure monitoring of all branches so merge requests build, that setting is in the vsc root advanced settings. -``` +```plaintext PUT /projects/:id/services/teamcity ``` @@ -1252,7 +1252,7 @@ Parameters: Delete JetBrains TeamCity CI service for a project. -``` +```plaintext DELETE /projects/:id/services/teamcity ``` @@ -1260,7 +1260,7 @@ DELETE /projects/:id/services/teamcity Get JetBrains TeamCity CI service settings for a project. -``` +```plaintext GET /projects/:id/services/teamcity ``` @@ -1272,7 +1272,7 @@ A continuous integration and build server Set Jenkins CI service for a project. -``` +```plaintext PUT /projects/:id/services/jenkins ``` @@ -1287,7 +1287,7 @@ Parameters: Delete Jenkins CI service for a project. -``` +```plaintext DELETE /projects/:id/services/jenkins ``` @@ -1295,7 +1295,7 @@ DELETE /projects/:id/services/jenkins Get Jenkins CI service settings for a project. -``` +```plaintext GET /projects/:id/services/jenkins ``` @@ -1307,7 +1307,7 @@ A continuous integration and build server Set Jenkins CI (Deprecated) service for a project. -``` +```plaintext PUT /projects/:id/services/jenkins-deprecated ``` @@ -1321,7 +1321,7 @@ Parameters: Delete Jenkins CI (Deprecated) service for a project. -``` +```plaintext DELETE /projects/:id/services/jenkins-deprecated ``` @@ -1329,7 +1329,7 @@ DELETE /projects/:id/services/jenkins-deprecated Get Jenkins CI (Deprecated) service settings for a project. -``` +```plaintext GET /projects/:id/services/jenkins-deprecated ``` @@ -1343,7 +1343,7 @@ This service is only available when your environment is set to development. Set MockCI service for a project. -``` +```plaintext PUT /projects/:id/services/mock-ci ``` @@ -1357,7 +1357,7 @@ Parameters: Delete MockCI service for a project. -``` +```plaintext DELETE /projects/:id/services/mock-ci ``` @@ -1365,7 +1365,7 @@ DELETE /projects/:id/services/mock-ci Get MockCI service settings for a project. -``` +```plaintext GET /projects/:id/services/mock-ci ``` @@ -1379,7 +1379,7 @@ YouTrack issue tracker Set YouTrack service for a project. -``` +```plaintext PUT /projects/:id/services/youtrack ``` @@ -1396,7 +1396,7 @@ Parameters: Delete YouTrack service for a project. -``` +```plaintext DELETE /projects/:id/services/youtrack ``` @@ -1404,6 +1404,6 @@ DELETE /projects/:id/services/youtrack Get YouTrack service settings for a project. -``` +```plaintext GET /projects/:id/services/youtrack ``` diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index 235f237ba94..bd389783a1d 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -22,22 +22,23 @@ services: variables: POSTGRES_DB: nice_marmot POSTGRES_USER: runner - POSTGRES_PASSWORD: "runner-password" + POSTGRES_PASSWORD: "" + POSTGRES_HOST_AUTH_METHOD: trust ``` NOTE: **Note:** -The `POSTGRES_DB`, `POSTGRES_USER`, and `POSTGRES_PASSWORD` variables can't be set in -the GitLab UI. To set them, assign them to a variable +The `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD` +variables can't be set in the GitLab UI. To set them, assign them to a variable [in the UI](../variables/README.md#via-the-ui), and then assign that -variable to the `POSTGRES_DB`, `POSTGRES_USER`, and `POSTGRES_PASSWORD` variables in -your `.gitlab-ci.yml`. +variable to the `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD` +variables in your `.gitlab-ci.yml`. And then configure your application to use the database, for example: ```yaml Host: postgres User: runner -Password: runner-password +Password: '' Database: nice_marmot ``` diff --git a/doc/development/database/add_foreign_key_to_existing_column.md b/doc/development/database/add_foreign_key_to_existing_column.md new file mode 100644 index 00000000000..e08f0a3bd1e --- /dev/null +++ b/doc/development/database/add_foreign_key_to_existing_column.md @@ -0,0 +1,136 @@ +# Adding foreign key constraint to an existing column + +Foreign keys help ensure consistency between related database tables. The current database review process **always** encourages you to add [foreign keys](../foreign_keys.md) when creating tables that reference records from other tables. + +Starting with Rails version 4, Rails includes migration helpers to add foreign key constraints to database tables. Before Rails 4, the only way for ensuring some level of consistency was the [`dependent`](https://guides.rubyonrails.org/association_basics.html#options-for-belongs-to-dependent) option within the association definition. Ensuring data consistency on the application level could fail in some unfortunate cases, so we might end up with inconsistent data in the table. This is mostly affecting older tables, where we simply didn't have the framework support to ensure consistency on the database level. These data inconsistencies can easily cause unexpected application behavior or bugs. + +Adding a foreign key to an existing database column requires database structure changes and potential data changes. In case the table is in use, we should always assume that there is inconsistent data. + +To add a foreign key constraint to an existing column: + +1. GitLab version `N.M`: Add a `NOT VALID` foreign key constraint to the column to ensure GitLab doesn't create inconsistent records. +1. GitLab version `N.M`: Add a data migration, to fix or clean up existing records. +1. GitLab version `N.M+1`: Validate the whole table by making the foreign key `VALID`. + +## Example + +Consider the following table structures: + +`users` table: + +- `id` (integer, primary key) +- `name` (string) + +`emails` table: + +- `id` (integer, primary key) +- `user_id` (integer) +- `email` (string) + +Express the relationship in `ActiveRecord`: + +```ruby +class User < ActiveRecord::Base + has_many :emails +end + +class Email < ActiveRecord::Base + belongs_to :user +end +``` + +Problem: when the user is removed, the email records related to the removed user will stay in the `emails` table: + +```ruby +user = User.find(1) +user.destroy + +emails = Email.where(user_id: 1) # returns emails for the deleted user +``` + +### Prevent invalid records + +Add a `NOT VALID` foreign key constraint to the table, which enforces consistency on the record changes. + +In the example above, you'd be still able to update records in the `emails` table. However, when you'd try to update the `user_id` with non-existent value, the constraint causes a database error. + +Migration file for adding `NOT VALID` foreign key: + +```ruby +class AddNotValidForeignKeyToEmailsUser < ActiveRecord::Migration[5.2] + include Gitlab::Database::MigrationHelpers + + DOWNTIME = false + + def up + # safe to use: it requires short lock on the table since we don't validate the foreign key + add_foreign_key :emails, :users, on_delete: :cascade, validate: false # rubocop:disable Migration/AddConcurrentForeignKey + end + + def down + remove_foreign_key_if_exists :emails, column: :user_id + end +end +``` + +CAUTION: **Caution:** +Avoid using the `add_foreign_key` constraint more than once per migration file, unless the source and target tables are identical. + +#### Data migration to fix existing records + +The approach here depends on the data volume and the cleanup strategy. If we can easily find "invalid" records by doing a simple database query and the record count is not that high, then the data migration can be executed within a Rails migration. + +In case the data volume is higher (>1000 records), it's better to create a background migration. If unsure, please contact the database team for advice. + +Example for cleaning up records in the `emails` table within a database migration: + +```ruby +class RemoveRecordsWithoutUserFromEmailsTable < ActiveRecord::Migration[5.2] + include Gitlab::Database::MigrationHelpers + + DOWNTIME = false + + disable_ddl_transaction! + + class Email < ActiveRecord::Base + include EachBatch + end + + def up + Email.where('user_id NOT IN (SELECT id FROM users)').each_batch do |relation| + relation.delete_all + end + end + + def down + # Can be a no-op when data inconsistency is not affecting the pre and post deploymnet version of the application. + # In this case we might have records in the `emails` table where the associated record in the `users` table is not there anymore. + end +end +``` + +### Validate the foreign key + +Validating the foreign key will scan the whole table and make sure that each relation is correct. + +NOTE: **Note:** When using [background migrations](../background_migrations.md), foreign key validation should happen in the next GitLab release. + +Migration file for validating the foreign key: + +```ruby +# frozen_string_literal: true + +class ValidateForeignKeyOnEmailUsers < ActiveRecord::Migration[5.2] + include Gitlab::Database::MigrationHelpers + + DOWNTIME = false + + def up + validate_foreign_key :emails, :user_id + end + + def down + # Can be safely a no-op if we don't roll back the inconsistent data. + end +end +``` diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 57f8ff36c00..f3f46baa54f 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -399,6 +399,8 @@ For an empty table (such as a fresh one), it is recommended to use `add_reference` in a single-transaction migration, combining it with other operations that don't require `disable_ddl_transaction!`. +You can read more about adding [foreign key constraints to an existing column](database/add_foreign_key_to_existing_column.md). + ## Adding Columns With Default Values When adding columns with default values to non-empty tables, you must use diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 2deee360bde..794a68f6b8f 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1292,7 +1292,7 @@ Markdown features, like link labels. ## Testing webhooks -You can trigger the webhook manually. Sample data from the project will be used. Sample data will take from the project. +You can trigger the webhook manually. Sample data from the project will be used. > For example: for triggering `Push Events` your project should have at least one commit. ![Webhook testing](img/webhook_testing.png) |