Add latest changes from gitlab-org/gitlab@master

20 files changed, 418 insertions, 79 deletions

diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md
index 87be9d500fb..26c83ab6034 100644
--- a/doc/administration/packages/container_registry.md
+++ b/doc/administration/packages/container_registry.md
@@ -619,7 +619,7 @@ provided by `gitlab-ctl`.
 
 Consider the following example, where you first build the image:
 
-```bash
+```shell
 # This builds a image with content of sha256:111111
 docker build -t my.registry.com/my.group/my.project:latest .
 docker push my.registry.com/my.group/my.project:latest
@@ -627,7 +627,7 @@ docker push my.registry.com/my.group/my.project:latest
 
 Now, you do overwrite `:latest` with a new version:
 
-```bash
+```shell
 # This builds a image with content of sha256:222222
 docker build -t my.registry.com/my.group/my.project:latest .
 docker push my.registry.com/my.group/my.project:latest
@@ -774,7 +774,7 @@ once a week.
 
 Create a file under `/etc/cron.d/registry-garbage-collect`:
 
-```bash
+```shell
 SHELL=/bin/sh
 PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
 
diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md
index 4c72634d4ff..37fffcdce22 100644
--- a/doc/administration/server_hooks.md
+++ b/doc/administration/server_hooks.md
@@ -88,11 +88,10 @@ pattern (`*~`).
 
 The hooks are searched and executed in this order:
 
-1. `gitlab-shell/hooks` directory as known to Gitaly.
-1. `<project>.git/hooks/<hook_name>` -  executed by `git` itself, this is symlinked to `gitlab-shell/hooks/<hook_name>`.
+1. Built-in GitLab server hooks (not user-customizable).
 1. `<project>.git/custom_hooks/<hook_name>` - per-project hook (this was kept as the already existing behavior).
 1. `<project>.git/custom_hooks/<hook_name>.d/*` - per-project hooks.
-1. `<project>.git/hooks/<hook_name>.d/*` OR `<custom_hooks_dir>/<hook_name.d>/*` - global hooks: all executable files (except editor backup files).
+1. `<custom_hooks_dir>/<hook_name>.d/*` - global hooks: all executable files (except editor backup files).
 
 The hooks of the same type are executed in order and execution stops on the
 first script exiting with a non-zero value.
diff --git a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md
index 48d415c6bdf..4ffce11aed0 100644
--- a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md
+++ b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md
@@ -74,7 +74,7 @@ and they will assist you with any issues you are having.
 
 - How to get cronjobs configured on a cluster
 
-  ```bash
+  ```shell
   kubectl get cronjobs
   ```
   
diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md
index 7d4e62a8ff5..852a5ae6e71 100644
--- a/doc/api/protected_environments.md
+++ b/doc/api/protected_environments.md
@@ -17,7 +17,7 @@ Currently, these levels are recognized:
 
 Gets a list of protected environments from a project:
 
-```bash
+```shell
 GET /projects/:id/protected_environments
 ```
 
@@ -25,7 +25,7 @@ GET /projects/:id/protected_environments
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
 
-```bash
+```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments/'
 ```
 
@@ -51,7 +51,7 @@ Example response:
 
 Gets a single protected environment:
 
-```bash
+```shell
 GET /projects/:id/protected_environments/:name
 ```
 
@@ -60,7 +60,7 @@ GET /projects/:id/protected_environments/:name
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `name` | string | yes | The name of the protected environment |
 
-```bash
+```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments/production'
 ```
 
@@ -84,11 +84,11 @@ Example response:
 
 Protects a single environment:
 
-```bash
+```shell
 POST /projects/:id/protected_environments
 ```
 
-```bash
+```shell
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments?name=staging&deploy_access_levels%5B%5D%5Buser_id%5D=1'
 ```
 
@@ -122,11 +122,11 @@ Example response:
 
 Unprotects the given protected environment:
 
-```bash
+```shell
 DELETE /projects/:id/protected_environments/:name
 ```
 
-```bash
+```shell
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments/staging'
 ```
 
diff --git a/doc/ci/README.md b/doc/ci/README.md
index f25a0ade42a..5206807cf7a 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -50,6 +50,7 @@ To get started with GitLab CI/CD, we recommend you read through
 the following documents:
 
 - [How GitLab CI/CD works](introduction/index.md#how-gitlab-cicd-works).
+- [Fundamental pipeline architectures](pipelines/pipeline_architectures.md).
 - [GitLab CI/CD basic workflow](introduction/index.md#basic-cicd-workflow).
 - [Step-by-step guide for writing `.gitlab-ci.yml` for the first time](../user/project/pages/getting_started_part_four.md).
 
diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md
index 621b679de73..08419685388 100644
--- a/doc/ci/docker/using_docker_images.md
+++ b/doc/ci/docker/using_docker_images.md
@@ -397,7 +397,7 @@ Before the new extended Docker configuration options, you would need to create
 your own image based on the `super/sql:latest` image, add the default command,
 and then use it in job's configuration, like:
 
-```Dockerfile
+```dockerfile
 # my-super-sql:latest image's Dockerfile
 
 FROM super/sql:latest
diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md
index f59401c6f87..848808f65ea 100644
--- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md
+++ b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md
@@ -63,7 +63,7 @@ Next, we'll create a small subset of tests that exemplify most of the states I e
 this `Weapon` class to go through. To get started, create a folder called `lib/tests`
 and add the following code to a new file `weaponTests.ts`:
 
-```ts
+```typescript
 import { expect } from 'chai';
 import { Weapon, BulletFactory } from '../lib/weapon';
 
@@ -114,7 +114,7 @@ describe('Weapon', () => {
 To build and run these tests using gulp, let's also add the following gulp functions
 to the existing `gulpfile.js` file:
 
-```ts
+```typescript
 gulp.task('build-test', function () {
     return gulp.src('src/tests/**/*.ts', { read: false })
     .pipe(tap(function (file) {
@@ -140,7 +140,7 @@ to trigger the weapon. In the `src/lib` folder create a `weapon.ts` file. We'll
 to it: `Weapon` and `BulletFactory` which will encapsulate Phaser's **sprite** and
 **group** objects, and the logic specific to our game.
 
-```ts
+```typescript
 export class Weapon {
     private isTriggered: boolean = false;
     private currentTimer: number = 0;
@@ -210,7 +210,7 @@ export class BulletFactory {
 Lastly, we'll redo our entry point, `game.ts`, to tie together both `Player` and `Weapon` objects
 as well as add them to the update loop. Here is what the updated `game.ts` file looks like:
 
-```ts
+```typescript
 import { Player } from "./player";
 import { Weapon, BulletFactory } from "./weapon";
 
diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md
new file mode 100644
index 00000000000..0e6745a59eb
--- /dev/null
+++ b/doc/ci/pipelines/pipeline_architectures.md
@@ -0,0 +1,269 @@
+---
+type: reference
+---
+
+# Pipeline Architecture
+
+Pipelines are the fundamental building blocks for CI/CD in GitLab. This page documents
+some of the important concepts related to them.
+
+There are three main ways to structure your pipelines, each with their
+own advantages. These methods can be mixed and matched if needed:
+
+- [Basic](#basic-pipelines): Good for straightforward projects where all the configuration is in one easy to find place.
+- [Directed Acylic Graph](#directed-acyclic-graph-pipelines): Good for large, complex projects that need efficient execution.
+- [Child/Parent Pipelines](#child--parent-pipelines): Good for monorepos and projects with lots of independently defined components.
+
+For more details about
+any of the keywords used below, check out our [CI YAML reference](../yaml/) for details.
+
+## Basic Pipelines
+
+This is the simplest pipeline in GitLab. It will run everything in the build stage concurrently,
+and once all of those finish, it will run everything in the test stage the same way, and so on.
+It's not the most efficient, and if you have lots of steps it can grow quite complex, but it's
+easier to maintain:
+
+```mermaid
+graph LR
+  subgraph deploy stage
+    deploy --> deploy_a
+    deploy --> deploy_b
+  end
+  subgraph test stage
+    test --> test_a
+    test --> test_b
+  end
+  subgraph build stage
+    build --> build_a
+    build --> build_b
+  end
+  build_a -.-> test
+  build_b -.-> test
+  test_a -.-> deploy
+  test_b -.-> deploy
+```
+
+Example basic `/.gitlab-ci.yml` pipeline configuration matching the diagram:
+
+```yaml
+stages:
+  - build
+  - test
+  - deploy
+
+image: alpine
+
+build_a:
+  stage: build
+  script:
+    - echo "This job builds something."
+
+build_b:
+  stage: build
+  script:
+    - echo "This job builds something else."
+
+test_a:
+  stage: test
+  script:
+    - echo "This job tests something. It will only run when all jobs in the"
+    - echo "build stage are complete."
+
+test_b:
+  stage: test
+  script:
+    - echo "This job tests something else. It will only run when all jobs in the"
+    - echo "build stage are complete too. It will start at about the same time as test_a."
+
+deploy_a:
+  stage: deploy
+  script:
+    - echo "This job deploys something. It will only run when all jobs in the"
+    - echo "test stage complete."
+
+deploy_b:
+  stage: deploy
+  script:
+    - echo "This job deploys something else. It will only run when all jobs in the"
+    - echo "test stage complete. It will start at about the same time as deploy_a."
+```
+
+## Directed Acyclic Graph Pipelines
+
+If efficiency is important to you and you want everything to run as quickly as possible,
+you can use [Directed Acylic Graphs (DAG)](../directed_acyclic_graph/index.md). Use the
+[`needs` keyword](../yaml/README.md#needs) to define dependency relationships between
+your jobs. When GitLab knows the relationships between your jobs, it can run everything
+as fast as possible, and even skips into subsequent stages when possible.
+
+In the example below, if `build_a` and `test_a` are much faster than `build_b` and
+`test_b`, GitLab will start `deploy_a` even if `build_b` is still running.
+
+```mermaid
+graph LR
+  subgraph Pipeline using DAG
+    build_a --> test_a --> deploy_a
+    build_b --> test_b --> deploy_b
+  end
+```
+
+Example DAG `/.gitlab-ci.yml` configuration matching the diagram:
+
+```yaml
+stages:
+  - build
+  - test
+  - deploy
+
+image: alpine
+
+build_a:
+  stage: build
+  script:
+    - echo "This job builds something quickly."
+
+build_b:
+  stage: build
+  script:
+    - echo "This job builds something else slowly."
+
+test_a:
+  stage: test
+  needs: build_a
+  script:
+    - echo "This test job will start as soon as build_a finishes."
+    - echo "It will not wait for build_b, or other jobs in the build stage, to finish."
+
+test_b:
+  stage: test
+  needs: build_b
+  script:
+    - echo "This test job will start as soon as build_b finishes."
+    - echo "It will not wait for other jobs in the build stage to finish."
+
+deploy_a:
+  stage: deploy
+  needs: test_a
+  script:
+    - echo "Since build_a and test_a run quickly, this deploy job can run much earlier."
+    - echo "It does not need to wait for build_b or test_b."
+
+deploy_b:
+  stage: deploy
+  needs: test_b
+  script:
+    - echo "Since build_b and test_b run slowly, this deploy job will run much later."
+```
+
+## Child / Parent Pipelines
+
+In the examples above, it's clear we've got two types of things that could be built independently.
+This is an ideal case for using [Child / Parent Pipelines](../parent_child_pipelines.md)) via
+the [`trigger` keyword](../yaml/README.md#trigger). It will separate out the configuration
+into multiple files, keeping things very simple. You can also combine this with:
+
+- The [`rules` keyword](../yaml/README.md#rules): For example, have the child pipelines triggered only
+  when there are changes to that area.
+- The [`include` keyword](../yaml/README.md#include): Bring in common behaviors, ensuring
+  you are not repeating yourself.
+- [DAG pipelines](#directed-acyclic-graph-pipelines) inside of child pipelines, achieving the benefits of both.
+
+```mermaid
+graph LR
+  subgraph Parent pipeline
+    trigger_a -.-> build_a
+  trigger_b -.-> build_b
+    subgraph child pipeline B
+    build_b --> test_b --> deploy_b
+    end
+
+    subgraph child pipeline A
+      build_a --> test_a --> deploy_a
+    end
+  end
+```
+
+Example `/.gitlab-ci.yml` configuration for the parent pipeline matching the diagram:
+
+```yaml
+stages:
+  - triggers
+
+trigger_a:
+  stage: triggers
+  trigger:
+    include: a/.gitlab-ci.yml
+  rules:
+    - changes:
+      - a/*
+
+trigger_b:
+  stage: triggers
+  trigger:
+    include: b/.gitlab-ci.yml
+  rules:
+    - changes:
+      - b/*
+```
+
+Example child `a` pipeline configuration, located in `/a/.gitlab-ci.yml`, making
+use of the DAG `needs:` keyword:
+
+```yaml
+stages:
+  - build
+  - test
+  - deploy
+
+image: alpine
+
+build_a:
+  stage: build
+  script:
+    - echo "This job builds something."
+
+test_a:
+  stage: test
+  needs: build_a
+  script:
+    - echo "This job tests something."
+
+deploy_a:
+  stage: deploy
+  needs: test_a
+  script:
+    - echo "This job deploys something."
+```
+
+Example child `b` pipeline configuration, located in `/b/.gitlab-ci.yml`, making
+use of the DAG `needs:` keyword:
+
+```yaml
+stages:
+  - build
+  - test
+  - deploy
+
+image: alpine
+
+build_b:
+  stage: build
+  script:
+    - echo "This job builds something else."
+
+test_b:
+  stage: test
+  needs: build_b
+  script:
+    - echo "This job tests something else."
+
+deploy_b:
+  stage: deploy
+  needs: test_b
+  script:
+    - echo "This job deploys something else."
+```
+
+It's also possible to set jobs to run before or after triggering child pipelines,
+for example if you have common setup steps or a unified deployment at the end.
diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md
index 6de3eaf8831..83b3ec44314 100644
--- a/doc/ci/quick_start/README.md
+++ b/doc/ci/quick_start/README.md
@@ -17,6 +17,11 @@ NOTE: **Note:**
 Coming over to GitLab from Jenkins? Check out our [reference](../jenkins/index.md)
 for converting your pre-existing pipelines over to our format.
 
+NOTE: **Note:**
+There are a few different [basic pipeline architectures](../pipelines/pipeline_architectures.md)
+that you can consider for use in your project. You may want to familiarize
+yourself with these prior to getting started.
+
 GitLab offers a [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) service. For each commit or push to trigger your CI
 [pipeline](../pipelines.md), you must:
 
diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md
index a137f10949f..235f237ba94 100644
--- a/doc/ci/services/postgres.md
+++ b/doc/ci/services/postgres.md
@@ -17,12 +17,12 @@ First, in your `.gitlab-ci.yml` add:
 
 ```yaml
 services:
-  - postgres:latest
+  - postgres:12.2-alpine
 
 variables:
   POSTGRES_DB: nice_marmot
   POSTGRES_USER: runner
-  POSTGRES_PASSWORD: ""
+  POSTGRES_PASSWORD: "runner-password"
 ```
 
 NOTE: **Note:**
@@ -37,7 +37,7 @@ And then configure your application to use the database, for example:
 ```yaml
 Host: postgres
 User: runner
-Password:
+Password: runner-password
 Database: nice_marmot
 ```
 
diff --git a/doc/development/code_comments.md b/doc/development/code_comments.md
index c1d58c1bd4b..a71e2b3c792 100644
--- a/doc/development/code_comments.md
+++ b/doc/development/code_comments.md
@@ -7,7 +7,7 @@ check if a comment is still relevant and what needs to be done to address it.
 
 Examples:
 
-```rb
+```ruby
 # Deprecated scope until code_owner column has been migrated to rule_type.
 # To be removed with https://gitlab.com/gitlab-org/gitlab/issues/11834.
 scope :code_owner, -> { where(code_owner: true).or(where(rule_type: :code_owner)) }
diff --git a/doc/development/creating_enums.md b/doc/development/creating_enums.md
index 64385a2ea79..79ed465b121 100644
--- a/doc/development/creating_enums.md
+++ b/doc/development/creating_enums.md
@@ -8,7 +8,7 @@ To use this type, add `limit: 2` to the migration that creates the column.
 
 Example:
 
-```rb
+```ruby
 def change
   add_column :ci_job_artifacts, :file_format, :integer, limit: 2
 end
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index e2f84e1200e..de7a437a1d6 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -783,33 +783,64 @@ nicely on different mobile devices.
 - When providing a shell command and its output, prefix the shell command with `$` and
   leave a blank line between the command and the output.
 - When providing a command without output, don't prefix the shell command with `$`.
+- If you need to include triple backticks inside a code block, use four backticks
+  for the codeblock fences instead of three.
 - For regular code blocks, always use a highlighting class corresponding to the
   language for better readability. Examples:
 
-  ~~~md
+  ````markdown
   ```ruby
   Ruby code
   ```
 
-  ```js
+  ```javascript
   JavaScript code
   ```
 
-  ```md
+  ```markdown
   [Markdown code example](example.md)
   ```
 
-  ```text
+  ```plaintext
   Code or text for which no specific highlighting class is available.
   ```
-  ~~~
-
-- To display raw Markdown instead of rendered Markdown, you can use triple backticks
-  with `md`, like the `Markdown code` example above, unless you want to include triple
-  backticks in the code block as well. In that case, use triple tildes (`~~~`) instead.
-- [Syntax highlighting for code blocks](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers)
-  is available for many languages. Use `shell` instead of `bash` or `sh` for shell output.
-- For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks).
+  ````
+
+Syntax highlighting is required for code blocks added to the GitLab documentation.
+Refer to the table below for the most common language classes, or check the
+[complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers)
+of language classes available.
+
+| Preferred language tags | Language aliases and notes                                                   |
+|-------------------------|------------------------------------------------------------------------------|
+| `asciidoc`              |                                                                              |
+| `dockerfile`            | Alias: `docker`.                                                             |
+| `elixir`                |                                                                              |
+| `erb`                   |                                                                              |
+| `golang`                | Alias: `go`.                                                                 |
+| `graphql`               |                                                                              |
+| `haml`                  |                                                                              |
+| `html`                  |                                                                              |
+| `ini`                   | For some simple config files that are not in TOML format.                    |
+| `javascript`            | Alias `js`.                                                                  |
+| `json`                  |                                                                              |
+| `markdown`              | Alias: `md`.                                                                 |
+| `mermaid`               |                                                                              |
+| `nginx`                 |                                                                              |
+| `perl`                  |                                                                              |
+| `php`                   |                                                                              |
+| `plaintext`             | Examples with no defined language, such as output from shell commands or API calls. If a codeblock has no language, it defaults to `plaintext`. Alias: `text`. |
+| `prometheus`            | Prometheus configuration examples.                                           |
+| `python`                |                                                                              |
+| `ruby`                  | Alias: `rb`.                                                                 |
+| `shell`                 | Aliases: `bash` or `sh`.                                                     |
+| `sql`                   |                                                                              |
+| `toml`                  | Runner configuration examples, and other toml formatted configuration files. |
+| `typescript`            | Alias: `ts`.                                                                 |
+| `xml`                   |                                                                              |
+| `yaml`                  | Alias: `yml`.                                                                |
+
+For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks).
 
 ## GitLab SVG icons
 
diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md
index 32017a284d5..b275a265cc6 100644
--- a/doc/development/gitaly.md
+++ b/doc/development/gitaly.md
@@ -240,13 +240,13 @@ Here are the steps to gate a new feature in Gitaly behind a feature flag.
 
 1. Create a package scoped flag name:
 
-   ```go
+   ```golang
    var findAllTagsFeatureFlag = "go-find-all-tags"
    ```
 
 1. Create a switch in the code using the `featureflag` package:
 
-   ```go
+   ```golang
    if featureflag.IsEnabled(ctx, findAllTagsFeatureFlag) {
      // go implementation
    } else {
@@ -256,7 +256,7 @@ Here are the steps to gate a new feature in Gitaly behind a feature flag.
 
 1. Create Prometheus metrics:
 
-   ```go
+   ```golang
    var findAllTagsRequests = prometheus.NewCounterVec(
      prometheus.CounterOpts{
        Name: "gitaly_find_all_tags_requests_total",
@@ -280,7 +280,7 @@ Here are the steps to gate a new feature in Gitaly behind a feature flag.
 
 1. Set headers in tests:
 
-   ```go
+   ```golang
    import (
      "google.golang.org/grpc/metadata"
 
diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md
index 73a1dd8ad8a..ae215026f56 100644
--- a/doc/development/go_guide/index.md
+++ b/doc/development/go_guide/index.md
@@ -195,7 +195,7 @@ When comparing expected and actual values in tests, use
 and others to improve readability when comparing structs, errors,
 large portions of text, or JSON documents:
 
-```go
+```golang
 type TestData struct {
     // ...
 }
diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md
index dcd822705f9..aa210f3550f 100644
--- a/doc/topics/autodevops/index.md
+++ b/doc/topics/autodevops/index.md
@@ -918,12 +918,12 @@ instead of the default `ruby:latest`:
 1. Set `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` to `--build-arg=RUBY_VERSION=alpine`.
 1. Add the following to a custom `Dockerfile`:
 
-    ```docker
-    ARG RUBY_VERSION=latest
-    FROM ruby:$RUBY_VERSION
+   ```dockerfile
+   ARG RUBY_VERSION=latest
+   FROM ruby:$RUBY_VERSION
 
-    # ... put your stuff here
-    ```
+   # ... put your stuff here
+   ```
 
 NOTE: **Note:**
 Passing in complex values (newlines and spaces, for example) will likely
@@ -955,14 +955,14 @@ In projects:
   1. Activate the experimental `Dockerfile` syntax by adding the following
      to the top of the file:
 
-     ```docker
+     ```dockerfile
      # syntax = docker/dockerfile:experimental
      ```
 
   1. To make secrets available in any `RUN $COMMAND` in the `Dockerfile`, mount
      the secret file and source it prior to running `$COMMAND`:
 
-     ```docker
+     ```dockerfile
      RUN --mount=type=secret,id=auto-devops-build-secrets . /run/secrets/auto-devops-build-secrets && $COMMAND
      ```
 
diff --git a/doc/topics/web_application_firewall/quick_start_guide.md b/doc/topics/web_application_firewall/quick_start_guide.md
index e3cf0bcd498..96c2da4e963 100644
--- a/doc/topics/web_application_firewall/quick_start_guide.md
+++ b/doc/topics/web_application_firewall/quick_start_guide.md
@@ -80,11 +80,11 @@ under which this application will be deployed.
    ![Google auth](../autodevops/img/guide_google_auth_v12_3.png)
 
 1. The last step is to provide the cluster details.
-    1. Give it a name, leave the environment scope as is, and choose the GCP project under which the cluster
-   will be created (per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you).
-    1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) under which the cluster will be created.
-    1. Enter the number of nodes you want it to have.
-    1. Choose the [machine type](https://cloud.google.com/compute/docs/machine-types).
+   1. Give it a name, leave the environment scope as is, and choose the GCP project under which the cluster
+      will be created (per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you).
+   1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) under which the cluster will be created.
+   1. Enter the number of nodes you want it to have.
+   1. Choose the [machine type](https://cloud.google.com/compute/docs/machine-types).
 
    ![GitLab GKE cluster details](../autodevops/img/guide_gitlab_gke_details_v12_3.png)
 
@@ -180,40 +180,40 @@ your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the
 
 1. After connecting to your cluster, check if the Ingress-NGINX controller is running and ModSecurity is enabled.
 
-    This is done by running the following commands:
+   This is done by running the following commands:
 
-    ```bash
-    $ kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller'
-    ingress-nginx-ingress-controller-55f9cf6584-dxljn        2/2     Running
+   ```shell
+   $ kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller'
+   ingress-nginx-ingress-controller-55f9cf6584-dxljn        2/2     Running
 
-    $ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /etc/nginx/nginx.conf | grep 'modsecurity on;'
-            modsecurity on;
-    ```
+   $ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /etc/nginx/nginx.conf | grep 'modsecurity on;'
+           modsecurity on;
+   ```
 
 1. Verify the Rails application has been installed properly.
 
-    ```bash
-    $ kubectl get ns
-    auto-devv-2-16730183-production     Active
+   ```shell
+   $ kubectl get ns
+   auto-devv-2-16730183-production     Active
 
-    $ kubectl get pods -n auto-devv-2-16730183-production
-    NAME                                   READY   STATUS    RESTARTS
-    production-5778cfcfcd-nqjcm            1/1     Running   0
-    production-postgres-6449f8cc98-r7xgg   1/1     Running   0
-    ```
+   $ kubectl get pods -n auto-devv-2-16730183-production
+   NAME                                   READY   STATUS    RESTARTS
+   production-5778cfcfcd-nqjcm            1/1     Running   0
+   production-postgres-6449f8cc98-r7xgg   1/1     Running   0
+   ```
 
 1. To make sure the Rails application is responding, send a request to it by running:
 
-    ```bash
-    $ kubectl get ing -n auto-devv-2-16730183-production
-    NAME  HOSTS  PORTS
-    production-auto-deploy  fjdiaz-auto-devv-2.34.68.60.207.nip.io,le-16730183.34.68.60.207.nip.io  80, 443
+   ```shell
+   $ kubectl get ing -n auto-devv-2-16730183-production
+   NAME  HOSTS  PORTS
+   production-auto-deploy  fjdiaz-auto-devv-2.34.68.60.207.nip.io,le-16730183.34.68.60.207.nip.io  80, 443
 
-    $ curl --location --insecure fjdiaz-auto-devv-2.34.68.60.207.nip.io | grep 'Rails!' --after 2 --before 2
-    <body>
-        <p>You're on Rails!</p>
-    </body>
-    ```
+   $ curl --location --insecure fjdiaz-auto-devv-2.34.68.60.207.nip.io | grep 'Rails!' --after 2 --before 2
+   <body>
+       <p>You're on Rails!</p>
+   </body>
+   ```
 
 Now that we have confirmed our system is properly setup, we can go ahead and test
 the WAF with OWASP CRS!
@@ -223,7 +223,7 @@ the WAF with OWASP CRS!
 Now let's send a potentially malicious request, as if we were a scanner,
 checking for vulnerabilities within our application and examine the modsecurity logs:
 
-```bash
+```shell
 $ curl --location --insecure fjdiaz-auto-devv-2.34.68.60.207.nip.io --header "User-Agent: absinthe" | grep 'Rails!' --after 2 --before 2
 <body>
     <p>You're on Rails!</p>
diff --git a/doc/user/project/integrations/img/prometheus_dashboard_environments_v12_8.png b/doc/user/project/integrations/img/prometheus_dashboard_environments_v12_8.png
new file mode 100644
index 00000000000..467deb86881
--- /dev/null
+++ b/doc/user/project/integrations/img/prometheus_dashboard_environments_v12_8.png
diff --git a/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v12_8.png b/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v12_8.png
new file mode 100644
index 00000000000..8899852ed04
--- /dev/null
+++ b/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v12_8.png
diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md
index e703f15b4d3..2f6c77c8217 100644
--- a/doc/user/project/integrations/prometheus.md
+++ b/doc/user/project/integrations/prometheus.md
@@ -55,6 +55,17 @@ will help you to quickly create a deployment:
 1. Navigate to your project's **CI/CD > Pipelines** page, and run a pipeline on any branch.
 1. When the pipeline has run successfully, graphs will be available on the **Operations > Metrics** page.
 
+![Monitoring Dashboard](img/prometheus_monitoring_dashboard_v12_8.png)
+
+#### Using the Metrics Dashboard
+
+##### Select an environment
+
+The **Environment** dropdown box above the dashboard displays the list of all [environments](#monitoring-cicd-environments).
+It enables you to search as you type through all environments and select the one you're looking for.
+
+![Monitoring Dashboard Environments](img/prometheus_dashboard_environments_v12_8.png)
+
 #### About managed Prometheus deployments
 
 Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/).
@@ -428,6 +439,29 @@ Note the following properties:
 
 ![single stat panel type](img/prometheus_dashboard_single_stat_panel_type.png)
 
+###### Percentile based results
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/201946) in GitLab 12.8.
+
+Query results sometimes need to be represented as a percentage value out of 100. You can use the `max_value` property at the root of the panel definition:
+
+```yaml
+dashboard: 'Dashboard Title'
+panel_groups:
+  - group: 'Group Title'
+    panels:
+      - title: "Single Stat"
+        type: "single-stat"
+        max_value: 100
+        metrics:
+        - id: 10
+          query: 'max(go_memstats_alloc_bytes{job="prometheus"})'
+          unit: '%'
+          label: "Total"
+```
+
+For example, if you have a query value of `53.6`, adding `%` as the unit results in a single stat value of `53.6%`, but if the maximum expected value of the query is `120`, the value would be `44.6%`. Adding the `max_value` causes the correct percentage value to display.
+
 ##### Heatmaps
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/30581) in GitLab 12.5.