Add latest changes from gitlab-org/gitlab@13-5-stable-eev13.5.0-rc42

14 files changed, 102 insertions, 29 deletions

diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md
index 443ca11be27..bb4a5b2b97f 100644
--- a/doc/user/project/integrations/irker.md
+++ b/doc/user/project/integrations/irker.md
@@ -14,8 +14,8 @@ See the project homepage for further information: <https://gitlab.com/esr/irker>
 
 ## Needed setup
 
-You will first need an Irker daemon. You can download the Irker code from its
-repository on <https://gitlab.com/esr/irker>:
+You will first need an Irker daemon. You can download the Irker code
+[from its repository](https://gitlab.com/esr/irker):
 
 ```shell
 git clone https://gitlab.com/esr/irker.git
@@ -55,6 +55,6 @@ case, `Aorimn` is treated as a nick and no more as a channel name.
 Irker can also join password-protected channels. Users need to append
 `?key=thesecretpassword` to the channel name. When using this feature remember to
 **not** put the `#` sign in front of the channel name; failing to do so will
-result on irker joining a channel literally named `#chan?key=password` henceforth
+result on Irker joining a channel literally named `#chan?key=password` henceforth
 leaking the channel key through the `/whois` IRC command (depending on IRC server
-configuration). This is due to a long standing irker bug.
+configuration). This is due to a long standing Irker bug.
diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md
index 3e0b6492477..b4e02bbd5f3 100644
--- a/doc/user/project/integrations/jira.md
+++ b/doc/user/project/integrations/jira.md
@@ -23,7 +23,7 @@ Features include:
 - **View a list of Jira issues directly in GitLab** **(PREMIUM)**
 
 For additional features, you can install the
-[Jira Development Panel integration](../../../integration/jira_development_panel.md) **(PREMIUM)**.
+[Jira Development Panel integration](../../../integration/jira_development_panel.md).
 This enables you to:
 
 - In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests.
@@ -122,6 +122,8 @@ By now you should have [configured Jira](#configuring-jira) and enabled the
 you should be able to reference and close Jira issues by just mentioning their
 ID in GitLab commits and merge requests.
 
+Jira issue IDs must be formatted in uppercase for the integration to work.
+
 ### Reference Jira issues
 
 When GitLab project has Jira issue tracker configured and enabled, mentioning
diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md
index 7a1f757c138..a502dfbf320 100644
--- a/doc/user/project/integrations/overview.md
+++ b/doc/user/project/integrations/overview.md
@@ -50,7 +50,7 @@ Click on the service links to see further configuration instructions and details
 | [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | No |
 | [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost | No |
 | [Microsoft teams](microsoft_teams.md) |  Receive notifications for actions that happen on GitLab into a room on Microsoft Teams using Office 365 Connectors | No |
-| Packagist | Update your project on Packagist, the main Composer repository | Yes |
+| Packagist | Update your projects on Packagist, the main Composer repository | Yes |
 | Pipelines emails | Email the pipeline status to a list of recipients | No |
 | [Slack Notifications](slack.md) | Send GitLab events (for example, an issue was created) to Slack as notifications | No |
 | [Slack slash commands](slack_slash_commands.md) **(CORE ONLY)** | Use slash commands in Slack to control GitLab | No |
diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md
index a19b819c823..28a9afa5bb0 100644
--- a/doc/user/project/integrations/prometheus.md
+++ b/doc/user/project/integrations/prometheus.md
@@ -1,6 +1,6 @@
 ---
 stage: Monitor
-group: APM
+group: Health
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
@@ -58,6 +58,43 @@ CPU and Memory consumption is monitored, but requires [naming conventions](prome
 
 The [NGINX Ingress](../clusters/index.md#installing-applications) that is deployed by GitLab to clusters, is automatically annotated for monitoring providing key response metrics: latency, throughput, and error rates.
 
+##### Example of Kubernetes service annotations and labels
+
+As an example, to activate Prometheus monitoring of a service:
+
+1. Add at least this annotation: `prometheus.io/scrape: 'true'`.
+1. Add two labels so GitLab can retrieve metrics dynamically for any environment:
+   - `application: ${CI_ENVIRONMENT_SLUG}`
+   - `release: ${CI_ENVIRONMENT_SLUG}`
+1. Create a dynamic PromQL query. For example, a query like
+   `temperature{application="{{ci_environment_slug}}",release="{{ci_environment_slug}}"}` to either:
+   - Add [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics).
+   - Add [custom dashboards](../../../operations/metrics/dashboards/index.md).
+
+The following is a service definition to accomplish this:
+
+```yaml
+---
+# Service
+apiVersion: v1
+kind: Service
+metadata:
+  name: service-${CI_PROJECT_NAME}-${CI_COMMIT_REF_SLUG}
+  # === Prometheus annotations ===
+  annotations:
+    prometheus.io/scrape: 'true'
+  labels:
+    application: ${CI_ENVIRONMENT_SLUG}
+    release: ${CI_ENVIRONMENT_SLUG}
+  # === End of Prometheus ===
+spec:
+  selector:
+    app: ${CI_PROJECT_NAME}
+  ports:
+    - port: ${EXPOSED_PORT}
+      targetPort: ${CONTAINER_PORT}
+```
+
 ### Manual configuration of Prometheus
 
 #### Requirements
@@ -136,10 +173,7 @@ one of them will be used:
 > - GitLab 9.3 added the [numeric comparison](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/27439) of the 30 minute averages.
 
 Developers can view the performance impact of their changes within the merge
-request workflow.
-
-NOTE: **Note:**
-Requires [Kubernetes](prometheus_library/kubernetes.md) metrics.
+request workflow. This feature requires [Kubernetes](prometheus_library/kubernetes.md) metrics.
 
 When a source branch has been deployed to an environment, a sparkline and
 numeric comparison of the average memory consumption will appear. On the
diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md
index e278c7eb664..70f8a55bb07 100644
--- a/doc/user/project/integrations/prometheus_library/cloudwatch.md
+++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md
@@ -1,6 +1,6 @@
 ---
 stage: Monitor
-group: APM
+group: Health
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md
index 712805b75f2..0fbc49ddad7 100644
--- a/doc/user/project/integrations/prometheus_library/haproxy.md
+++ b/doc/user/project/integrations/prometheus_library/haproxy.md
@@ -1,6 +1,6 @@
 ---
 stage: Monitor
-group: APM
+group: Health
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md
index 6f2c2477eee..35b111ab2b2 100644
--- a/doc/user/project/integrations/prometheus_library/index.md
+++ b/doc/user/project/integrations/prometheus_library/index.md
@@ -1,6 +1,6 @@
 ---
 stage: Monitor
-group: APM
+group: Health
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md
index 29efe08e53d..43c2d305437 100644
--- a/doc/user/project/integrations/prometheus_library/kubernetes.md
+++ b/doc/user/project/integrations/prometheus_library/kubernetes.md
@@ -1,6 +1,6 @@
 ---
 stage: Monitor
-group: APM
+group: Health
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
@@ -12,7 +12,7 @@ GitLab has support for automatically detecting and monitoring Kubernetes metrics
 
 ## Requirements
 
-The [Prometheus](../prometheus.md) and [Kubernetes](../kubernetes.md)
+The [Prometheus](../prometheus.md) and [Kubernetes](../../clusters/index.md)
 integration services must be enabled.
 
 ## Metrics supported
diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md
index 0d3042463c9..1757378fb70 100644
--- a/doc/user/project/integrations/prometheus_library/nginx.md
+++ b/doc/user/project/integrations/prometheus_library/nginx.md
@@ -1,6 +1,6 @@
 ---
 stage: Monitor
-group: APM
+group: Health
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md
index 7bebe7b1e65..fdea800c410 100644
--- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md
+++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md
@@ -1,6 +1,6 @@
 ---
 stage: Monitor
-group: APM
+group: Health
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
@@ -8,11 +8,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22133) in GitLab 11.7.
 
+GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the built-in Prometheus metrics included with Kubernetes NGINX Ingress controller [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160) onward.
+
 NOTE: **Note:**
 NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics exporter](nginx_ingress_vts.md), which exports metrics different than the built-in metrics.
 
-GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the built-in Prometheus metrics included with Kubernetes NGINX Ingress controller [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160) onward.
-
 ## Requirements
 
 [Prometheus integration](../prometheus.md) must be active.
diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md
index 326931e9790..ec7b1ee6d10 100644
--- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md
+++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md
@@ -1,6 +1,6 @@
 ---
 stage: Monitor
-group: APM
+group: Health
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md
index 688643a85a7..abb072c9a0a 100644
--- a/doc/user/project/integrations/services_templates.md
+++ b/doc/user/project/integrations/services_templates.md
@@ -6,20 +6,52 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Service templates
 
-Using a service template, GitLab administrators can provide default values for configuring integrations at the project level.
+Using a service template, GitLab administrators can:
 
-When you enable a service template, the defaults are applied to **all** projects that do not
-already have the integration enabled or do not otherwise have custom values saved.
-The values are pre-filled on each project's configuration page for the applicable integration.
+- Provide default values for configuring integrations when creating new projects.
+- Bulk configure all existing projects in one step.
 
-If you disable the template, these values no longer appear as defaults, while
-any values already saved for an integration remain unchanged.
+When you enable a service template:
+
+- The defaults are applied to **all** existing projects that either:
+  - Don't already have the integration enabled.
+  - Don't have custom values stored for already enabled integrations.
+- Values are populated on each project's configuration page for the applicable
+  integration.
+- Settings are stored at the project level.
+
+If you disable the template:
+
+- GitLab default values again become the default values for integrations on
+  new projects.
+- Projects previously configured using the template will continue to use
+  those settings.
+
+If you change the template, the revised values are applied to new projects. This feature
+does not provide central administration of integration settings.
+
+## Central administration of project integrations
+
+A new set of features is being introduced in GitLab to provide more control over
+how integrations are configured at the instance, group, and project level.
+
+[Read more about setting up project integration management](../../admin_area/settings/project_integration_management.md)
+(introduced in GitLab 13.3) and [our plans for managing integrations](https://gitlab.com/groups/gitlab-org/-/epics/2137).
 
 ## Enable a service template
 
 Navigate to the **Admin Area > Service Templates** and choose the service
 template you wish to create.
 
+Recommendation:
+
+- Test the settings on some projects individually before enabling a template.
+- Copy the working settings from a project to the template.
+
+There is no "Test settings" option when enabling templates. If the settings do not work,
+these incorrect settings will be applied to all existing projects that do not already have
+the integration configured. Fixing the integration then needs to be done project-by-project.
+
 ## Service for external issue trackers
 
 The following image shows an example service template for Redmine.
diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md
index 03ff5f845b6..e6f12c2532f 100644
--- a/doc/user/project/integrations/slack.md
+++ b/doc/user/project/integrations/slack.md
@@ -64,7 +64,7 @@ The following triggers are available for Slack notifications:
 - **Tag push**: Triggered when a new tag is pushed to the repository.
 - **Pipeline**: Triggered when a pipeline status changes.
 - **Wiki page**: Triggered when a wiki page is created or updated.
-- **Deployment**: Triggered when a deployment finishes.
+- **Deployment**: Triggered when a deployment starts or finishes.
 - **Alert**: Triggered when a new, unique alert is recorded.
 
 ## Troubleshooting
diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md
index 800eb1d3359..7adea5ebcd6 100644
--- a/doc/user/project/integrations/webhooks.md
+++ b/doc/user/project/integrations/webhooks.md
@@ -1303,7 +1303,12 @@ Note that `commit.id` is the ID of the pipeline, not the ID of the commit.
 
 ### Deployment events
 
-Triggered when deployment is finished/failed/canceled.
+Triggered when a deployment:
+
+- Starts ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41214) in GitLab 13.5.)
+- Succeeds
+- Fails
+- Is cancelled
 
 **Request Header**: