Add latest changes from gitlab-org/gitlab@master

10 files changed, 170 insertions, 52 deletions

diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md
index 3e887e11ca6..896c08d7a43 100644
--- a/doc/administration/repository_storage_types.md
+++ b/doc/administration/repository_storage_types.md
@@ -78,6 +78,58 @@ by another folder with the next 2 characters. They are both stored in a special
 "@hashed/#{hash[0..1]}/#{hash[2..3]}/#{hash}.wiki.git"
 ```
 
+### Translating hashed storage paths
+
+Troubleshooting problems with the Git repositories, adding hooks, and other
+tasks will require you translate between the human readable project name
+and the hashed storage path.
+
+#### From project name to hashed path
+
+The hashed path is shown on the project's page in the [admin area](../user/admin_area/index.md#administering-projects).
+
+To access the Projects page, go to **Admin Area > Overview > Projects** and then
+open up the page for the project.
+
+The "Gitaly relative path" is shown there, for example:
+
+```
+"@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git"
+```
+
+This is the path under `/var/opt/gitlab/git-data/repositories/` on a
+default Omnibus installation.
+
+In a [Rails console](troubleshooting/debug.md#starting-a-rails-console),
+get this information using either the numeric project ID or the full path:
+
+```ruby
+Project.find(16).disk_path
+Project.find_by_full_path('group/project').disk_path
+```
+
+#### From hashed path to project name
+
+To translate from a hashed storage path to a project name:
+
+1. Start a [Rails console](troubleshooting/debug.md#starting-a-rails-console).
+1. Run the following:
+
+```ruby
+ProjectRepository.find_by(disk_path: '@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9').project
+```
+
+The quoted string in that command is the directory tree you'll find on your
+GitLab server. For example, on a default Omnibus installation this would be
+`/var/opt/gitlab/git-data/repositories/@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git`
+with `.git` from the end of the directory name removed.
+
+The output includes the project id and the project name:
+
+```
+=> #<Project id:16 it/supportteam/ticketsystem>
+```
+
 ### Hashed object pools
 
 > [Introduced](https://gitlab.com/gitlab-org/gitaly/issues/1606) in GitLab 12.1.
diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md
index 37fffcdce22..06c560a01ca 100644
--- a/doc/administration/server_hooks.md
+++ b/doc/administration/server_hooks.md
@@ -96,6 +96,10 @@ The hooks are searched and executed in this order:
 The hooks of the same type are executed in order and execution stops on the
 first script exiting with a non-zero value.
 
+For `<project>.git` you'll need to
+[translate your project name into the hashed storage format](repository_storage_types.md#translating-hashed-storage-paths)
+that GitLab uses.
+
 ## Custom error messages
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5073) in GitLab 8.10.
diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md
index c1f2a5c92a3..34d42b8b5b8 100644
--- a/doc/administration/troubleshooting/debug.md
+++ b/doc/administration/troubleshooting/debug.md
@@ -3,22 +3,32 @@
 Sometimes things don't work the way they should. Here are some tips on debugging issues out
 in production.
 
-## Mail not working
+## Starting a Rails console
 
-A common problem is that mails are not being sent for some reason. Suppose you configured
-an SMTP server, but you're not seeing mail delivered. Here's how to check the settings:
+Troubleshooting and debugging often requires a rails console.
 
-1. Run a Rails console:
+**For Omnibus installations**
 
-   ```shell
-   sudo gitlab-rails console -e production
-   ```
+```shell
+sudo gitlab-rails console
+```
 
-   or for source installs:
+---
 
-   ```shell
-   bundle exec rails console -e production
-   ```
+**For installations from source**
+
+```shell
+bundle exec rails console production
+```
+
+Kubernetes: the console is in the task-runner pod, refer to our [Kubernetes cheat sheet](kubernetes_cheat_sheet.md#gitlab-specific-kubernetes-information) for details.
+
+## Mail not working
+
+A common problem is that mails are not being sent for some reason. Suppose you configured
+an SMTP server, but you're not seeing mail delivered. Here's how to check the settings:
+
+1. Run a [Rails console.](#starting-a-rails-console)
 
 1. Look at the ActionMailer `delivery_method` to make sure it matches what you
    intended. If you configured SMTP, it should say `:smtp`. If you're using
@@ -160,22 +170,17 @@ separate Rails process to debug the issue:
 1. Log in to your GitLab account.
 1. Copy the URL that is causing problems (e.g. `https://gitlab.com/ABC`).
 1. Create a Personal Access Token for your user (Profile Settings -> Access Tokens).
-1. Bring up the GitLab Rails console. For omnibus users, run:
-
-   ```shell
-   sudo gitlab-rails console
-   ```
-
+1. Bring up the [GitLab Rails console.](#starting-a-rails-console)
 1. At the Rails console, run:
 
    ```ruby
-   [1] pry(main)> app.get '<URL FROM STEP 2>/?private_token=<TOKEN FROM STEP 3>'
+   app.get '<URL FROM STEP 2>/?private_token=<TOKEN FROM STEP 3>'
    ```
 
    For example:
 
    ```ruby
-   [1] pry(main)> app.get 'https://gitlab.com/gitlab-org/gitlab-foss/issues/1?private_token=123456'
+   app.get 'https://gitlab.com/gitlab-org/gitlab-foss/issues/1?private_token=123456'
    ```
 
 1. In a new window, run `top`. It should show this ruby process using 100% CPU. Write down the PID.
diff --git a/doc/api/graphql/reference/gitlab_schema.graphql b/doc/api/graphql/reference/gitlab_schema.graphql
index 65934e53260..6d02b2905e2 100644
--- a/doc/api/graphql/reference/gitlab_schema.graphql
+++ b/doc/api/graphql/reference/gitlab_schema.graphql
@@ -306,7 +306,7 @@ type Commit {
   id: ID!
 
   """
-  Latest pipeline of the commit
+  Latest pipeline of the commit. Deprecated in 12.5: Use `pipelines`
   """
   latestPipeline(
     """
@@ -323,7 +323,7 @@ type Commit {
     Filter pipelines by their status
     """
     status: PipelineStatusEnum
-  ): Pipeline @deprecated(reason: "Use pipelines")
+  ): Pipeline @deprecated(reason: "Use `pipelines`. Deprecated in 12.5")
 
   """
   Raw commit message
@@ -2493,9 +2493,9 @@ type EpicIssue implements Noteable {
   designCollection: DesignCollection
 
   """
-  Deprecated. Use `designCollection`
+  The designs associated with this issue. Deprecated in 12.2: Use `designCollection`
   """
-  designs: DesignCollection @deprecated(reason: "Use designCollection")
+  designs: DesignCollection @deprecated(reason: "Use `designCollection`. Deprecated in 12.2")
 
   """
   Indicates discussion is locked on the issue
@@ -2548,7 +2548,7 @@ type EpicIssue implements Noteable {
   epicIssueId: ID!
 
   """
-  Current health status. Available only when feature flag `save_issuable_health_status` is enabled.
+  Current health status. Available only when feature flag `save_issuable_health_status` is enabled
   """
   healthStatus: HealthStatus
 
@@ -2984,9 +2984,9 @@ type GrafanaIntegration {
   id: ID!
 
   """
-  API token for the Grafana integration. Field is permanently masked.
+  API token for the Grafana integration. Deprecated in 12.7: Plain text token has been masked for security reasons
   """
-  token: String! @deprecated(reason: "Plain text token has been masked for security reasons")
+  token: String! @deprecated(reason: "Plain text token has been masked for security reasons. Deprecated in 12.7")
 
   """
   Timestamp of the issue's last activity
@@ -3489,9 +3489,9 @@ type Issue implements Noteable {
   designCollection: DesignCollection
 
   """
-  Deprecated. Use `designCollection`
+  The designs associated with this issue. Deprecated in 12.2: Use `designCollection`
   """
-  designs: DesignCollection @deprecated(reason: "Use designCollection")
+  designs: DesignCollection @deprecated(reason: "Use `designCollection`. Deprecated in 12.2")
 
   """
   Indicates discussion is locked on the issue
@@ -3539,7 +3539,7 @@ type Issue implements Noteable {
   epic: Epic
 
   """
-  Current health status. Available only when feature flag `save_issuable_health_status` is enabled.
+  Current health status. Available only when feature flag `save_issuable_health_status` is enabled
   """
   healthStatus: HealthStatus
 
@@ -4242,9 +4242,9 @@ type MergeRequest implements Noteable {
   ): LabelConnection
 
   """
-  Deprecated - renamed to defaultMergeCommitMessage
+  Default merge commit message of the merge request. Deprecated in 11.8: Use `defaultMergeCommitMessage`
   """
-  mergeCommitMessage: String @deprecated(reason: "Renamed to defaultMergeCommitMessage")
+  mergeCommitMessage: String @deprecated(reason: "Use `defaultMergeCommitMessage`. Deprecated in 11.8")
 
   """
   SHA of the merge request commit (set once merged)
@@ -6191,7 +6191,7 @@ type Project {
   visibility: String
 
   """
-  Vulnerabilities reported on the project. Available only when feature flag `first_class_vulnerabilities` is enabled.
+  Vulnerabilities reported on the project. Available only when feature flag `first_class_vulnerabilities` is enabled
   """
   vulnerabilities(
     """
diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json
index 6da44c36cae..40053199d72 100644
--- a/doc/api/graphql/reference/gitlab_schema.json
+++ b/doc/api/graphql/reference/gitlab_schema.json
@@ -968,7 +968,7 @@
             },
             {
               "name": "latestPipeline",
-              "description": "Latest pipeline of the commit",
+              "description": "Latest pipeline of the commit. Deprecated in 12.5: Use `pipelines`",
               "args": [
                 {
                   "name": "status",
@@ -1007,7 +1007,7 @@
                 "ofType": null
               },
               "isDeprecated": true,
-              "deprecationReason": "Use pipelines"
+              "deprecationReason": "Use `pipelines`. Deprecated in 12.5"
             },
             {
               "name": "message",
@@ -7244,7 +7244,7 @@
             },
             {
               "name": "designs",
-              "description": "Deprecated. Use `designCollection`",
+              "description": "The designs associated with this issue. Deprecated in 12.2: Use `designCollection`",
               "args": [
 
               ],
@@ -7254,7 +7254,7 @@
                 "ofType": null
               },
               "isDeprecated": true,
-              "deprecationReason": "Use designCollection"
+              "deprecationReason": "Use `designCollection`. Deprecated in 12.2"
             },
             {
               "name": "discussionLocked",
@@ -7397,7 +7397,7 @@
             },
             {
               "name": "healthStatus",
-              "description": "Current health status. Available only when feature flag `save_issuable_health_status` is enabled.",
+              "description": "Current health status. Available only when feature flag `save_issuable_health_status` is enabled",
               "args": [
 
               ],
@@ -8659,7 +8659,7 @@
             },
             {
               "name": "token",
-              "description": "API token for the Grafana integration. Field is permanently masked.",
+              "description": "API token for the Grafana integration. Deprecated in 12.7: Plain text token has been masked for security reasons",
               "args": [
 
               ],
@@ -8673,7 +8673,7 @@
                 }
               },
               "isDeprecated": true,
-              "deprecationReason": "Plain text token has been masked for security reasons"
+              "deprecationReason": "Plain text token has been masked for security reasons. Deprecated in 12.7"
             },
             {
               "name": "updatedAt",
@@ -9990,7 +9990,7 @@
             },
             {
               "name": "designs",
-              "description": "Deprecated. Use `designCollection`",
+              "description": "The designs associated with this issue. Deprecated in 12.2: Use `designCollection`",
               "args": [
 
               ],
@@ -10000,7 +10000,7 @@
                 "ofType": null
               },
               "isDeprecated": true,
-              "deprecationReason": "Use designCollection"
+              "deprecationReason": "Use `designCollection`. Deprecated in 12.2"
             },
             {
               "name": "discussionLocked",
@@ -10125,7 +10125,7 @@
             },
             {
               "name": "healthStatus",
-              "description": "Current health status. Available only when feature flag `save_issuable_health_status` is enabled.",
+              "description": "Current health status. Available only when feature flag `save_issuable_health_status` is enabled",
               "args": [
 
               ],
@@ -12105,7 +12105,7 @@
             },
             {
               "name": "mergeCommitMessage",
-              "description": "Deprecated - renamed to defaultMergeCommitMessage",
+              "description": "Default merge commit message of the merge request. Deprecated in 11.8: Use `defaultMergeCommitMessage`",
               "args": [
 
               ],
@@ -12115,7 +12115,7 @@
                 "ofType": null
               },
               "isDeprecated": true,
-              "deprecationReason": "Renamed to defaultMergeCommitMessage"
+              "deprecationReason": "Use `defaultMergeCommitMessage`. Deprecated in 11.8"
             },
             {
               "name": "mergeCommitSha",
@@ -18522,7 +18522,7 @@
             },
             {
               "name": "vulnerabilities",
-              "description": "Vulnerabilities reported on the project. Available only when feature flag `first_class_vulnerabilities` is enabled.",
+              "description": "Vulnerabilities reported on the project. Available only when feature flag `first_class_vulnerabilities` is enabled",
               "args": [
                 {
                   "name": "after",
diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md
index 2acb4822e95..cce8603a54f 100644
--- a/doc/api/graphql/reference/index.md
+++ b/doc/api/graphql/reference/index.md
@@ -82,7 +82,7 @@ Represents a project or group board
 | `authoredDate` | Time | Timestamp of when the commit was authored |
 | `description` | String | Description of the commit message |
 | `id` | ID! | ID (global ID) of the commit |
-| `latestPipeline` **{warning-solid}** | Pipeline | **Deprecated:** Use pipelines |
+| `latestPipeline` **{warning-solid}** | Pipeline | **Deprecated:** Use `pipelines`. Deprecated in 12.5 |
 | `message` | String | Raw commit message |
 | `sha` | String! | SHA1 ID of the commit |
 | `signatureHtml` | String | Rendered HTML of the commit signature |
@@ -413,13 +413,13 @@ Relationship between an epic and an issue
 | `description` | String | Description of the issue |
 | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
 | `designCollection` | DesignCollection | Collection of design images associated with this issue |
-| `designs` **{warning-solid}** | DesignCollection | **Deprecated:** Use designCollection |
+| `designs` **{warning-solid}** | DesignCollection | **Deprecated:** Use `designCollection`. Deprecated in 12.2 |
 | `discussionLocked` | Boolean! | Indicates discussion is locked on the issue |
 | `downvotes` | Int! | Number of downvotes the issue has received |
 | `dueDate` | Time | Due date of the issue |
 | `epic` | Epic | Epic to which this issue belongs |
 | `epicIssueId` | ID! | ID of the epic-issue relation |
-| `healthStatus` | HealthStatus | Current health status. Available only when feature flag `save_issuable_health_status` is enabled. |
+| `healthStatus` | HealthStatus | Current health status. Available only when feature flag `save_issuable_health_status` is enabled |
 | `id` | ID | Global ID of the epic-issue relation |
 | `iid` | ID! | Internal ID of the issue |
 | `milestone` | Milestone | Milestone of the issue |
@@ -483,7 +483,7 @@ Autogenerated return type of EpicTreeReorder
 | `enabled` | Boolean! | Indicates whether Grafana integration is enabled |
 | `grafanaUrl` | String! | Url for the Grafana host for the Grafana integration |
 | `id` | ID! | Internal ID of the Grafana integration |
-| `token` **{warning-solid}** | String! | **Deprecated:** Plain text token has been masked for security reasons |
+| `token` **{warning-solid}** | String! | **Deprecated:** Plain text token has been masked for security reasons. Deprecated in 12.7 |
 | `updatedAt` | Time! | Timestamp of the issue's last activity |
 
 ## Group
@@ -535,12 +535,12 @@ Autogenerated return type of EpicTreeReorder
 | `description` | String | Description of the issue |
 | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
 | `designCollection` | DesignCollection | Collection of design images associated with this issue |
-| `designs` **{warning-solid}** | DesignCollection | **Deprecated:** Use designCollection |
+| `designs` **{warning-solid}** | DesignCollection | **Deprecated:** Use `designCollection`. Deprecated in 12.2 |
 | `discussionLocked` | Boolean! | Indicates discussion is locked on the issue |
 | `downvotes` | Int! | Number of downvotes the issue has received |
 | `dueDate` | Time | Due date of the issue |
 | `epic` | Epic | Epic to which this issue belongs |
-| `healthStatus` | HealthStatus | Current health status. Available only when feature flag `save_issuable_health_status` is enabled. |
+| `healthStatus` | HealthStatus | Current health status. Available only when feature flag `save_issuable_health_status` is enabled |
 | `iid` | ID! | Internal ID of the issue |
 | `milestone` | Milestone | Milestone of the issue |
 | `reference` | String! | Internal reference of the issue. Returned in shortened format by default |
@@ -644,7 +644,7 @@ Autogenerated return type of MarkAsSpamSnippet
 | `id` | ID! | ID of the merge request |
 | `iid` | String! | Internal ID of the merge request |
 | `inProgressMergeCommitSha` | String | Commit SHA of the merge request if merge is in progress |
-| `mergeCommitMessage` **{warning-solid}** | String | **Deprecated:** Renamed to defaultMergeCommitMessage |
+| `mergeCommitMessage` **{warning-solid}** | String | **Deprecated:** Use `defaultMergeCommitMessage`. Deprecated in 11.8 |
 | `mergeCommitSha` | String | SHA of the merge request commit (set once merged) |
 | `mergeError` | String | Error message due to a merge error |
 | `mergeOngoing` | Boolean! | Indicates if a merge is currently occurring |
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md
index 3002289f6a6..1c93527da0c 100644
--- a/doc/development/api_graphql_styleguide.md
+++ b/doc/development/api_graphql_styleguide.md
@@ -283,6 +283,51 @@ the `some_feature_flag` feature flag is enabled.
 
 If the feature flag is not enabled, an error will be returned saying the field does not exist.
 
+## Deprecating fields
+
+GitLab's GraphQL API is versionless, which means we maintain backwards
+compatibility with older versions of the API with every change. Rather
+than removing a field, we need to _deprecate_ the field instead. In
+future, GitLab
+[may remove deprecated fields](https://gitlab.com/gitlab-org/gitlab/issues/32292).
+
+Fields are deprecated using the `deprecated` property. The value
+of the property is a `Hash` of:
+
+- `reason` - Reason for the deprecation.
+- `milestone` - Milestone that the field was deprecated.
+
+Example:
+
+```ruby
+field :token, GraphQL::STRING_TYPE, null: true,
+      deprecated: { reason: 'Login via token has been removed', milestone: 10.0 },
+      description: 'Token for login'
+```
+
+The original `description:` of the field should be maintained, and should
+_not_ be updated to mention the deprecation.
+
+### Deprecation reason styleguide
+
+Where the reason for deprecation is due to the field being replaced
+with another field, the `reason` must be:
+
+```plaintext
+Use `otherFieldName`
+```
+
+Example:
+
+```ruby
+field :designs, ::Types::DesignManagement::DesignCollectionType, null: true,
+      deprecated: { reason: 'Use `designCollection`', milestone: 10.0 },
+      description: 'The designs associated with this issue',
+```
+
+If the field is not being replaced by another field, a descriptive
+deprecation `reason` should be given.
+
 ## Enums
 
 GitLab GraphQL enums are defined in `app/graphql/types`. When defining new enums, the
diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md
index 075536ce9ad..acf54ada0d6 100644
--- a/doc/user/application_security/container_scanning/index.md
+++ b/doc/user/application_security/container_scanning/index.md
@@ -25,6 +25,10 @@ merge request.
 
 ![Container Scanning Widget](img/container_scanning_v12_9.png)
 
+## Contribute your scanner
+
+The [Security Scanner Integration](../../../development/integrations/secure.md) documentation explains how to integrate other security scanners into GitLab.
+
 ## Use cases
 
 If you distribute your application with Docker, then there's a great chance
diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md
index 1a0a7a7711f..9a56734f4d0 100644
--- a/doc/user/application_security/dependency_scanning/index.md
+++ b/doc/user/application_security/dependency_scanning/index.md
@@ -67,6 +67,10 @@ The following languages and dependency managers are supported.
 | Scala ([sbt](https://www.scala-sbt.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
 | Go ([Go Modules](https://github.com/golang/go/wiki/Modules)) | yes ([alpha](https://gitlab.com/gitlab-org/gitlab/issues/7132)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
 
+## Contribute your scanner
+
+The [Security Scanner Integration](../../../development/integrations/secure.md) documentation explains how to integrate other security scanners into GitLab.
+
 ## Configuration
 
 For GitLab 11.9 and later, to enable Dependency Scanning, you must
diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md
index 82a7256a984..90e6fcbf1d1 100644
--- a/doc/user/application_security/sast/index.md
+++ b/doc/user/application_security/sast/index.md
@@ -90,6 +90,10 @@ The Java analyzers can also be used for variants like the
 [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html),
 [Grails](https://grails.org/) and the [Maven wrapper](https://github.com/takari/maven-wrapper).
 
+## Contribute your scanner
+
+The [Security Scanner Integration](../../../development/integrations/secure.md) documentation explains how to integrate other security scanners into GitLab.
+
 ## Configuration
 
 NOTE: **Note:**