Merge branch 'master' into feature/multi-level-container-registry-images

* master: (94 commits)
  Merge branch 'open-redirect-fix-continue-to' into 'security'
  Merge branch 'open-redirect-host-fix' into 'security'
  Merge branch 'path-disclosure-proj-import-export' into 'security'
  Merge branch '29364-private-projects-mr-fix'
  Merge branch '30125-markdown-security'
  Issue title realtime
  Update CHANGELOG.md for 8.16.9
  Update CHANGELOG.md for 8.17.5
  Update CHANGELOG.md for 9.0.4
  Add "search" optional param and docs for V4
  Use PDFLab to render PDFs in GitLab
  Separate Scala from Java in CI examples
  Fix broken link
  Reorganize CI examples, add more links
  Refactor CI index page
  Remove deprecated field from workhorse response
  Use gitlab-workhorse 1.4.3
  Document how ETag caching middleware handles query parameters
  Make group skip validation in the frontend
  Use NamespaceValidator::WILDCARD_ROUTES in ETag caching middleware
  ...

11 files changed, 345 insertions, 79 deletions

diff --git a/doc/api/issues.md b/doc/api/issues.md
index a19c965a8c3..5702cdcf3c1 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -26,16 +26,20 @@ GET /issues?labels=foo,bar&state=opened
 GET /issues?milestone=1.0.0
 GET /issues?milestone=1.0.0&state=opened
 GET /issues?iids[]=42&iids[]=43
+GET /issues?search=issue+title+or+description
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `state`   | string  | no    | Return all issues or just those that are `opened` or `closed`|
-| `labels`  | string  | no    | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels |
-| `milestone` | string| no    | The milestone title |
-| `iids`    | Array[integer] | no | Return only the issues having the given `iid` |
-| `order_by`| string  | no    | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
-| `sort`    | string  | no    | Return requests sorted in `asc` or `desc` order. Default is `desc`  |
+|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
+| Attribute   | Type           | Required | Description                                                                                                                 |
+|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
+| `state`     | string         | no       | Return all issues or just those that are `opened` or `closed`                                                               |
+| `labels`    | string         | no       | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels |
+| `milestone` | string         | no       | The milestone title                                                                                                         |
+| `iids`      | Array[integer] | no       | Return only the issues having the given `iid`                                                                               |
+| `order_by`  | string         | no       | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`                                     |
+| `sort`      | string         | no       | Return requests sorted in `asc` or `desc` order. Default is `desc`                                                          |
+| `search`    | string         | no       | Search issues against their `title` and `description`                                                                        |
+|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
 
 ```bash
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/issues
@@ -104,17 +108,21 @@ GET /groups/:id/issues?labels=foo,bar&state=opened
 GET /groups/:id/issues?milestone=1.0.0
 GET /groups/:id/issues?milestone=1.0.0&state=opened
 GET /groups/:id/issues?iids[]=42&iids[]=43
+GET /groups/:id/issues?search=issue+title+or+description
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a group |
-| `state`   | string  | no    | Return all issues or just those that are `opened` or `closed`|
-| `labels`  | string  | no    | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels |
-| `iids`    | Array[integer] | no | Return only the issues having the given `iid` |
-| `milestone` | string| no    | The milestone title |
-| `order_by`| string  | no    | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
-| `sort`    | string  | no    | Return requests sorted in `asc` or `desc` order. Default is `desc`  |
+|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
+| Attribute   | Type           | Required | Description                                                                                                                 |
+|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
+| `id`        | integer        | yes      | The ID of a group                                                                                                           |
+| `state`     | string         | no       | Return all issues or just those that are `opened` or `closed`                                                               |
+| `labels`    | string         | no       | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels |
+| `iids`      | Array[integer] | no       | Return only the issues having the given `iid`                                                                               |
+| `milestone` | string         | no       | The milestone title                                                                                                         |
+| `order_by`  | string         | no       | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`                                     |
+| `sort`      | string         | no       | Return requests sorted in `asc` or `desc` order. Default is `desc`                                                          |
+| `search`    | string         | no       | Search group issues against their `title` and `description`                                                                  |
+|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
 
 
 ```bash
@@ -184,17 +192,21 @@ GET /projects/:id/issues?labels=foo,bar&state=opened
 GET /projects/:id/issues?milestone=1.0.0
 GET /projects/:id/issues?milestone=1.0.0&state=opened
 GET /projects/:id/issues?iids[]=42&iids[]=43
+GET /projects/:id/issues?search=issue+title+or+description
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a project |
-| `iids`    | Array[integer] | no | Return only the milestone having the given `iid` |
-| `state`   | string  | no    | Return all issues or just those that are `opened` or `closed`|
-| `labels`  | string  | no    | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels |
-| `milestone` | string| no    | The milestone title |
-| `order_by`| string  | no    | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
-| `sort`    | string  | no    | Return requests sorted in `asc` or `desc` order. Default is `desc`  |
+|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
+| Attribute   | Type           | Required | Description                                                                                                                 |
+|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
+| `id`        | integer        | yes      | The ID of a project                                                                                                         |
+| `iids`      | Array[integer] | no       | Return only the milestone having the given `iid`                                                                            |
+| `state`     | string         | no       | Return all issues or just those that are `opened` or `closed`                                                               |
+| `labels`    | string         | no       | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels |
+| `milestone` | string         | no       | The milestone title                                                                                                         |
+| `order_by`  | string         | no       | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`                                     |
+| `sort`      | string         | no       | Return requests sorted in `asc` or `desc` order. Default is `desc`                                                          |
+| `search`    | string         | no       | Search project issues against their `title` and `description`                                                                |
+|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
 
 
 ```bash
@@ -258,10 +270,12 @@ Get a single project issue.
 GET /projects/:id/issues/:issue_iid
 ```
 
+|-------------+---------+----------+--------------------------------------|
 | Attribute   | Type    | Required | Description                          |
-| ---------   | ----    | -------- | -----------                          |
+|-------------+---------+----------+--------------------------------------|
 | `id`        | integer | yes      | The ID of a project                  |
 | `issue_iid` | integer | yes      | The internal ID of a project's issue |
+|-------------+---------+----------+--------------------------------------|
 
 ```bash
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/41
@@ -323,19 +337,23 @@ Creates a new project issue.
 POST /projects/:id/issues
 ```
 
-| Attribute                                 | Type    | Required | Description                                                                                                                                                                                                                                          |
-| ---------                                 | ----    | -------- | -----------                                                                                                                                                                                                                                          |
-| `id`                                      | integer | yes      | The ID of a project                                                                                                                                                                                                                                  |
-| `title`                                   | string  | yes      | The title of an issue                                                                                                                                                                                                                                |
-| `description`                             | string  | no       | The description of an issue                                                                                                                                                                                                                          |
-| `confidential`                            | boolean | no       | Set an issue to be confidential. Default is `false`.                                                                                                                                                                                                 |
-| `assignee_id`                             | integer | no       | The ID of a user to assign issue                                                                                                                                                                                                                     |
-| `milestone_id`                            | integer | no       | The ID of a milestone to assign issue                                                                                                                                                                                                                |
-| `labels`                                  | string  | no       | Comma-separated label names for an issue                                                                                                                                                                                                             |
-| `created_at`                              | string  | no       | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights)                                                                                                                                           |
-| `due_date`                                | string  | no       | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11`                                                                                                                                                                                     |
-| `merge_request_to_resolve_discussions_of` | integer | no       | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values. |
-| `discussion_to_resolve`                   | string  | no       | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`.                                                    |
+|-------------------------------------------+---------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Attribute                                 | Type    | Required | Description                                                                                                                                          |
+|-------------------------------------------+---------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `id`                                      | integer | yes      | The ID of a project                                                                                                                                  |
+| `title`                                   | string  | yes      | The title of an issue                                                                                                                                |
+| `description`                             | string  | no       | The description of an issue                                                                                                                          |
+| `confidential`                            | boolean | no       | Set an issue to be confidential. Default is `false`.                                                                                                 |
+| `assignee_id`                             | integer | no       | The ID of a user to assign issue                                                                                                                     |
+| `milestone_id`                            | integer | no       | The ID of a milestone to assign issue                                                                                                                |
+| `labels`                                  | string  | no       | Comma-separated label names for an issue                                                                                                             |
+| `created_at`                              | string  | no       | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights)                                           |
+| `due_date`                                | string  | no       | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11`                                                                                     |
+| `merge_request_to_resolve_discussions_of` | integer | no       | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. |
+| -                                         | -       | -        | When passing a description or title, these values will take precedence over the default values.                                                      |
+| `discussion_to_resolve`                   | string  | no       | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion                                    |
+| -                                         | -       | -        | as resolved. Use in combination with `merge_request_to_resolve_discussions_of`.                                                                      |
+|-------------------------------------------+---------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------|
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug
@@ -383,8 +401,9 @@ closed.
 PUT /projects/:id/issues/:issue_iid
 ```
 
+|----------------+---------+----------+------------------------------------------------------------------------------------------------------------|
 | Attribute      | Type    | Required | Description                                                                                                |
-| ---------      | ----    | -------- | -----------                                                                                                |
+|----------------+---------+----------+------------------------------------------------------------------------------------------------------------|
 | `id`           | integer | yes      | The ID of a project                                                                                        |
 | `issue_iid`    | integer | yes      | The internal ID of a project's issue                                                                       |
 | `title`        | string  | no       | The title of an issue                                                                                      |
@@ -396,6 +415,7 @@ PUT /projects/:id/issues/:issue_iid
 | `state_event`  | string  | no       | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it                      |
 | `updated_at`   | string  | no       | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) |
 | `due_date`     | string  | no       | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11`                                           |
+|----------------+---------+----------+------------------------------------------------------------------------------------------------------------|
 
 ```bash
 curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close
@@ -442,10 +462,12 @@ Only for admins and project owners. Soft deletes the issue in question.
 DELETE /projects/:id/issues/:issue_iid
 ```
 
+|-------------+---------+----------+--------------------------------------|
 | Attribute   | Type    | Required | Description                          |
-| ---------   | ----    | -------- | -----------                          |
+|-------------+---------+----------+--------------------------------------|
 | `id`        | integer | yes      | The ID of a project                  |
 | `issue_iid` | integer | yes      | The internal ID of a project's issue |
+|-------------+---------+----------+--------------------------------------|
 
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85
@@ -464,11 +486,13 @@ project, it will then be assigned to the issue that is being moved.
 POST /projects/:id/issues/:issue_iid/move
 ```
 
+|-----------------+---------+----------+--------------------------------------|
 | Attribute       | Type    | Required | Description                          |
-| ---------       | ----    | -------- | -----------                          |
+|-----------------+---------+----------+--------------------------------------|
 | `id`            | integer | yes      | The ID of a project                  |
 | `issue_iid`     | integer | yes      | The internal ID of a project's issue |
 | `to_project_id` | integer | yes      | The ID of the new project            |
+|-----------------+---------+----------+--------------------------------------|
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85/move
@@ -520,10 +544,12 @@ is returned.
 POST /projects/:id/issues/:issue_iid/subscribe
 ```
 
+|-------------+---------+----------+--------------------------------------|
 | Attribute   | Type    | Required | Description                          |
-| ---------   | ----    | -------- | -----------                          |
+|-------------+---------+----------+--------------------------------------|
 | `id`        | integer | yes      | The ID of a project                  |
 | `issue_iid` | integer | yes      | The internal ID of a project's issue |
+|-------------+---------+----------+--------------------------------------|
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe
@@ -575,10 +601,12 @@ status code `304` is returned.
 POST /projects/:id/issues/:issue_iid/unsubscribe
 ```
 
+|-------------+---------+----------+--------------------------------------|
 | Attribute   | Type    | Required | Description                          |
-| ---------   | ----    | -------- | -----------                          |
+|-------------+---------+----------+--------------------------------------|
 | `id`        | integer | yes      | The ID of a project                  |
 | `issue_iid` | integer | yes      | The internal ID of a project's issue |
+|-------------+---------+----------+--------------------------------------|
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe
@@ -594,10 +622,12 @@ returned.
 POST /projects/:id/issues/:issue_iid/todo
 ```
 
+|-------------+---------+----------+--------------------------------------|
 | Attribute   | Type    | Required | Description                          |
-| ---------   | ----    | -------- | -----------                          |
+|-------------+---------+----------+--------------------------------------|
 | `id`        | integer | yes      | The ID of a project                  |
 | `issue_iid` | integer | yes      | The internal ID of a project's issue |
+|-------------+---------+----------+--------------------------------------|
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/todo
@@ -685,11 +715,13 @@ Sets an estimated time of work for this issue.
 POST /projects/:id/issues/:issue_iid/time_estimate
 ```
 
+|-------------+---------+----------+------------------------------------------|
 | Attribute   | Type    | Required | Description                              |
-| ---------   | ----    | -------- | -----------                              |
+|-------------+---------+----------+------------------------------------------|
 | `id`        | integer | yes      | The ID of a project                      |
 | `issue_iid` | integer | yes      | The internal ID of a project's issue     |
 | `duration`  | string  | yes      | The duration in human format. e.g: 3h30m |
+|-------------+---------+----------+------------------------------------------|
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m
@@ -714,10 +746,12 @@ Resets the estimated time for this issue to 0 seconds.
 POST /projects/:id/issues/:issue_iid/reset_time_estimate
 ```
 
+|-------------+---------+----------+--------------------------------------|
 | Attribute   | Type    | Required | Description                          |
-| ---------   | ----    | -------- | -----------                          |
+|-------------+---------+----------+--------------------------------------|
 | `id`        | integer | yes      | The ID of a project                  |
 | `issue_iid` | integer | yes      | The internal ID of a project's issue |
+|-------------+---------+----------+--------------------------------------|
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate
@@ -742,11 +776,13 @@ Adds spent time for this issue
 POST /projects/:id/issues/:issue_iid/add_spent_time
 ```
 
+|-------------+---------+----------+------------------------------------------|
 | Attribute   | Type    | Required | Description                              |
-| ---------   | ----    | -------- | -----------                              |
+|-------------+---------+----------+------------------------------------------|
 | `id`        | integer | yes      | The ID of a project                      |
 | `issue_iid` | integer | yes      | The internal ID of a project's issue     |
 | `duration`  | string  | yes      | The duration in human format. e.g: 3h30m |
+|-------------+---------+----------+------------------------------------------|
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h
@@ -771,10 +807,12 @@ Resets the total spent time for this issue to 0 seconds.
 POST /projects/:id/issues/:issue_iid/reset_spent_time
 ```
 
+|-------------+---------+----------+--------------------------------------|
 | Attribute   | Type    | Required | Description                          |
-| ---------   | ----    | -------- | -----------                          |
+|-------------+---------+----------+--------------------------------------|
 | `id`        | integer | yes      | The ID of a project                  |
 | `issue_iid` | integer | yes      | The internal ID of a project's issue |
+|-------------+---------+----------+--------------------------------------|
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time
@@ -797,10 +835,12 @@ Example response:
 GET /projects/:id/issues/:issue_iid/time_stats
 ```
 
+|-------------+---------+----------+--------------------------------------|
 | Attribute   | Type    | Required | Description                          |
-| ---------   | ----    | -------- | -----------                          |
+|-------------+---------+----------+--------------------------------------|
 | `id`        | integer | yes      | The ID of a project                  |
 | `issue_iid` | integer | yes      | The internal ID of a project's issue |
+|-------------+---------+----------+--------------------------------------|
 
 ```bash
 curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats
diff --git a/doc/ci/README.md b/doc/ci/README.md
index d8fba5d7a77..b3780a08828 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -1,34 +1,147 @@
-# GitLab CI Documentation
+# GitLab Continuous Integration (GitLab CI)
 
-## CI User documentation
+![CI/CD pipeline graph](img/cicd_pipeline_infograph.png)
+
+The benefits of Continuous Integration are huge when automation plays an
+integral part of your workflow. GitLab comes with built-in Continuous
+Integration, Continuous Deployment, and Continuous Delivery support to build,
+test, and deploy your application.
+
+Here's some info we've gathered to get you started.
+
+## Getting started
+
+The first steps towards your GitLab CI journey.
 
 - [Getting started with GitLab CI](quick_start/README.md)
-- [CI examples for various languages](examples/README.md)
-- [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md)
 - [Pipelines and jobs](pipelines.md)
-- [Environments and deployments](environments.md)
-- [Learn how `.gitlab-ci.yml` works](yaml/README.md)
 - [Configure a Runner, the application that runs your jobs](runners/README.md)
-- [Use Docker images with GitLab Runner](docker/using_docker_images.md)
-- [Use CI to build Docker images](docker/using_docker_build.md)
+- **Articles:**
+  - [Getting started with GitLab and GitLab CI - Intro to CI](https://about.gitlab.com/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/)
+  - [Continuous Integration, Delivery, and Deployment with GitLab - Intro to CI/CD](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/)
+  - [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/)
+  - [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/)
+  - [GitLab CI: Deployment & environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
+- **Videos:**
+  - [Demo (March, 2017): how to get started using CI/CD with GitLab](https://about.gitlab.com/2017/03/13/ci-cd-demo/)
+  - [Webcast (April, 2016): getting started with CI in GitLab](https://about.gitlab.com/2016/04/20/webcast-recording-and-slides-introduction-to-ci-in-gitlab/)
+- **Third-party videos:**
+  - [Intégration continue avec GitLab (September, 2016)](https://www.youtube.com/watch?v=URcMBXjIr24&t=13s)
+  - [GitLab CI for Minecraft Plugins (July, 2016)](https://www.youtube.com/watch?v=Z4pcI9F8yf8)
+
+## Reference guides
+
+Once you get familiar with the getting started guides, you'll find yourself
+digging into specific reference guides.
+
+- [`.gitlab-ci.yml` reference](yaml/README.md) - Learn all about the ins and
+  outs of `.gitlab-ci.yml` definitions
 - [CI Variables](variables/README.md) - Learn how to use variables defined in
   your `.gitlab-ci.yml` or secured ones defined in your project's settings
-- [Use SSH keys in your build environment](ssh_keys/README.md)
-- [Trigger jobs through the API](triggers/README.md)
+- **The permissions model** - Learn about the access levels a user can have for
+  performing certain CI actions
+  - [User permissions](../user/permissions.md#gitlab-ci)
+  - [Jobs permissions](../user/permissions.md#jobs-permissions)
+
+## GitLab CI + Docker
+
+Leverage the power of Docker to run your CI pipelines.
+
+- [Use Docker images with GitLab Runner](docker/using_docker_images.md)
+- [Use CI to build Docker images](docker/using_docker_build.md)
+- [CI services (linked Docker containers)](services/README.md)
+- **Articles:**
+  - [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/)
+
+## Advanced use
+
+Once you get familiar with the basics of GitLab CI, it's time to dive in and
+learn how to leverage its potential even more.
+
+- [Environments and deployments](environments.md) - Separate your jobs into
+  environments and use them for different purposes like testing, building and
+  deploying
 - [Job artifacts](../user/project/pipelines/job_artifacts.md)
-- [User permissions](../user/permissions.md#gitlab-ci)
-- [Jobs permissions](../user/permissions.md#jobs-permissions)
-- [API](../api/ci/README.md)
-- [CI services (linked docker containers)](services/README.md)
-- [CI/CD pipelines settings](../user/project/pipelines/settings.md)
-- [Review Apps](review_apps/index.md)
-- [Git submodules](git_submodules.md) Using Git submodules in your CI jobs
+- [Git submodules](git_submodules.md) - How to run your CI jobs when Git
+  submodules are involved
 - [Auto deploy](autodeploy/index.md)
+- [Use SSH keys in your build environment](ssh_keys/README.md)
+- [Trigger jobs through the GitLab API](triggers/README.md)
+
+## Review Apps
+
+- [Review Apps](review_apps/index.md)
+- **Articles:**
+  - [Introducing Review Apps](https://about.gitlab.com/2016/11/22/introducing-review-apps/)
+  - [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/)
+
+## GitLab CI for GitLab Pages
+
+See the topic on [GitLab Pages](../user/project/pages/index.md).
+
+## Special configuration
+
+You can change the default behavior of GitLab CI in your whole GitLab instance
+as well as in each project.
+
+- **Project specific**
+  - [CI/CD pipelines settings](../user/project/pipelines/settings.md)
+  - [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md)
+- **Affecting the whole GitLab instance**
+  - [Continuous Integration admin settings](../user/admin_area/settings/continuous_integration.md)
+
+## Examples
+
+>**Note:**
+A collection of `.gitlab-ci.yml` files is maintained at the
+[GitLab CI Yml project][gitlab-ci-templates].
+If your favorite programming language or framework is missing we would love
+your help by sending a merge request with a `.gitlab-ci.yml`.
+
+Here is an collection of tutorials and guides on setting up your CI pipeline.
+
+- [GitLab CI examples](examples/README.md) for the following languages and frameworks:
+  - [PHP](examples/php.md)
+  - [Ruby](examples/test-and-deploy-ruby-application-to-heroku.md)
+  - [Python](examples/test-and-deploy-python-application-to-heroku.md)
+  - [Clojure](examples/test-clojure-application.md)
+  - [Scala](examples/test-scala-application.md)
+  - [Phoenix](examples/test-phoenix-application.md)
+  - [Run PHP Composer & NPM scripts then deploy them to a staging server](examples/deployment/composer-npm-deploy.md)
+- **Blog posts**
+  - [Automated Debian packaging](https://about.gitlab.com/2016/10/12/automated-debian-package-build-with-gitlab-ci/)
+  - [Spring boot application with GitLab CI and Kubernetes](https://about.gitlab.com/2016/11/30/setting-up-gitlab-ci-for-android-projects/)
+  - [Setting up CI for iOS projects](https://about.gitlab.com/2016/12/14/continuous-delivery-of-a-spring-boot-application-with-gitlab-ci-and-kubernetes/)
+  - [Using GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/)
+  - [Setting up GitLab CI for Android projects](https://about.gitlab.com/2016/11/30/setting-up-gitlab-ci-for-android-projects/)
+  - [Building a new GitLab Docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/)
+  - [CI/CD with GitLab in action](https://about.gitlab.com/2017/03/13/ci-cd-demo/)
+  - [Building an Elixir Release into a Docker image using GitLab CI](https://about.gitlab.com/2016/08/11/building-an-elixir-release-into-docker-image-using-gitlab-ci-part-1/)
+- **Miscellaneous**
+  - [Using `dpl` as deployment tool](examples/deployment/README.md)
+  - [Repositories with examples for various languages](https://gitlab.com/groups/gitlab-examples)
+  - [The .gitlab-ci.yml file for GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml)
+  - [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/)
+
+## Integrations
+
+- **Articles:**
+  - [Continuous Delivery with GitLab and Convox](https://about.gitlab.com/2016/06/09/continuous-delivery-with-gitlab-and-convox/)
+  - [Getting Started with GitLab and Shippable Continuous Integration](https://about.gitlab.com/2016/05/05/getting-started-gitlab-and-shippable/)
+  - [GitLab Partners with DigitalOcean to make Continuous Integration faster, safer, and more affordable](https://about.gitlab.com/2016/04/19/gitlab-partners-with-digitalocean-to-make-continuous-integration-faster-safer-and-more-affordable/)
+
+## Why GitLab CI?
+
+- **Articles:**
+  - [Why We Chose GitLab CI for our CI/CD Solution](https://about.gitlab.com/2016/10/17/gitlab-ci-oohlala/)
+  - [Building our web-app on GitLab CI: 5 reasons why Captain Train migrated from Jenkins to GitLab CI](https://about.gitlab.com/2016/07/22/building-our-web-app-on-gitlab-ci/)
 
 ## Breaking changes
 
-- [CI variables renaming](variables/README.md#9-0-renaming) Read about the
+- [CI variables renaming for GitLab 9.0](variables/README.md#9-0-renaming) Read about the
   deprecated CI variables and what you should use for GitLab 9.0+.
 - [New CI job permissions model](../user/project/new_ci_build_permissions_model.md)
   Read about what changed in GitLab 8.12 and how that affects your jobs.
   There's a new way to access your Git submodules and LFS objects in jobs.
+
+[gitlab-ci-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml
diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md
index 5377bf9ee80..33c27b39a8a 100644
--- a/doc/ci/examples/README.md
+++ b/doc/ci/examples/README.md
@@ -1,4 +1,4 @@
-# CI Examples
+# GitLab CI Examples
 
 A collection of `.gitlab-ci.yml` files is maintained at the [GitLab CI Yml project][gitlab-ci-templates].
 If your favorite programming language or framework are missing we would love your help by sending a merge request
@@ -6,22 +6,73 @@ with a `.gitlab-ci.yml`.
 
 Apart from those, here is an collection of tutorials and guides on setting up your CI pipeline:
 
+## Languages, frameworks, OSs
+
+### PHP
+
 - [Testing a PHP application](php.md)
+- [Run PHP Composer & NPM scripts then deploy them to a staging server](deployment/composer-npm-deploy.md)
+
+### Ruby
+
 - [Test and deploy a Ruby application to Heroku](test-and-deploy-ruby-application-to-heroku.md)
+
+### Python
+
 - [Test and deploy a Python application to Heroku](test-and-deploy-python-application-to-heroku.md)
-- [Test a Clojure application](test-clojure-application.md)
+
+### Java
+
+- **Articles:**
+  - [Continuous Delivery of a Spring Boot application with GitLab CI and Kubernetes](https://about.gitlab.com/2016/12/14/continuous-delivery-of-a-spring-boot-application-with-gitlab-ci-and-kubernetes/)
+
+### Scala
+
 - [Test a Scala application](test-scala-application.md)
+
+### Clojure
+
+- [Test a Clojure application](test-clojure-application.md)
+
+### Elixir
+
 - [Test a Phoenix application](test-phoenix-application.md)
-- [Using `dpl` as deployment tool](deployment/README.md)
-- [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/)
-- [Run PHP Composer & NPM scripts then deploy them to a staging server](deployment/composer-npm-deploy.md)
-- Help your favorite programming language and GitLab by sending a merge request
-  with a guide for that language.
+- **Articles:**
+  - [Building an Elixir Release into a Docker image using GitLab CI](https://about.gitlab.com/2016/08/11/building-an-elixir-release-into-docker-image-using-gitlab-ci-part-1/)
+
+### iOS
+
+- **Articles:**
+  - [Setting up GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/)
+
+### Android
 
-## Outside the documentation
+- **Articles:**
+  - [Setting up GitLab CI for Android projects](https://about.gitlab.com/2016/11/30/setting-up-gitlab-ci-for-android-projects/)
 
-- [Blog post about using GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/)
+### Other
+
+- [Using `dpl` as deployment tool](deployment/README.md)
 - [Repositories with examples for various languages](https://gitlab.com/groups/gitlab-examples)
 - [The .gitlab-ci.yml file for GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml)
+- **Articles:**
+  - [Continuous Deployment with GitLab: how to build and deploy a Debian Package with GitLab CI](https://about.gitlab.com/2016/10/12/automated-debian-package-build-with-gitlab-ci/)
+
+## GitLab CI for GitLab Pages
+
+- [Example projects](https://gitlab.com/pages)
+- **Articles:**
+  - [Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages](../../user/project/pages/getting_started_part_four.md)
+  - [SSGs Part 3: Build any SSG site with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/):
+  examples for Ruby-, NodeJS-, Python-, and GoLang-based SSGs
+  - [Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/)
+  - [Publish code coverage reports with GitLab Pages](https://about.gitlab.com/2016/11/03/publish-code-coverage-report-with-gitlab-pages/)
+
+See the topic [GitLab Pages](../../user/project/pages/index.md) for a complete overview.
+
+## More
+
+Contributions are very much welcomed! You can help your favorite programming
+language and GitLab by sending a merge request with a guide for that language.
 
 [gitlab-ci-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml
diff --git a/doc/ci/img/cicd_pipeline_infograph.png b/doc/ci/img/cicd_pipeline_infograph.png
new file mode 100644
index 00000000000..9ddd4aa828b
--- /dev/null
+++ b/doc/ci/img/cicd_pipeline_infograph.png
diff --git a/doc/development/img/cache-hit.svg b/doc/development/img/cache-hit.svg
new file mode 100644
index 00000000000..1c37693df2d
--- /dev/null
+++ b/doc/development/img/cache-hit.svg
@@ -0,0 +1,21 @@
+<svg version="1.1" id="mscgen_js-svg-__svg" class="mscgen_js-svg-__svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="976" height="310" viewBox="0 0 976 310"><desc>
+
+# Generated by mscgen_js - https://sverweij.github.io/mscgen_js
+msc {
+  # options
+  hscale="1.5";
+
+  # entities
+  c [label="Client", textbgcolor="lime"],
+  rails [label="Rails", textbgcolor="cyan"],
+  etag [label="EtagCaching", textbgcolor="orange"],
+  redis [label="Redis", textbgcolor="white"];
+
+  # arcs
+  c =&gt; rails [label="GET /projects/5/pipelines"];
+  rails =&gt; etag [label="GET /projects/5/pipelines"];
+  etag =&gt; redis [label="read(key = 'GET &lt;Etag&gt;')"];
+  redis =&gt; etag [label="cache hit", linecolor="green", textcolor="green"];
+    |||;
+  etag =&gt; c [label="304 Not Modified", linecolor="blue", textcolor="blue"];
+}</desc><defs><style type="text/css">svg.mscgen_js-svg-__svg{font-family:Helvetica,sans-serif;font-size:12px;font-weight:normal;font-style:normal;text-decoration:none;background-color:white;stroke:black;stroke-width:2;color:black}.mscgen_js-svg-__svg path, .mscgen_js-svg-__svg rect{fill:none;color:black;stroke:black}.mscgen_js-svg-__svg .label-text-background{fill:white;stroke:white;stroke-width:0}.mscgen_js-svg-__svg .bglayer{fill:white;stroke:white;stroke-width:0}.mscgen_js-svg-__svg line{stroke:black}.mscgen_js-svg-__svg .return, .mscgen_js-svg-__svg .comment{stroke-dasharray:5,3}.mscgen_js-svg-__svg .inline_expression_divider{stroke-dasharray:10,5}.mscgen_js-svg-__svg text{color:inherit;stroke:none;text-anchor:middle}.mscgen_js-svg-__svg text.entity-text{text-decoration:underline}.mscgen_js-svg-__svg text.anchor-start{text-anchor:start}.mscgen_js-svg-__svg .arrow-marker{overflow:visible}.mscgen_js-svg-__svg .arrow-style{stroke-width:1}.mscgen_js-svg-__svg .arcrow, .mscgen_js-svg-__svg .arcrowomit, .mscgen_js-svg-__svg .emphasised{stroke-linecap:butt}.mscgen_js-svg-__svg .arcrowomit{stroke-dasharray:2,2;}.mscgen_js-svg-__svg .box, .mscgen_js-svg-__svg .entity{fill:white;stroke-linejoin:round}.mscgen_js-svg-__svg .inherit{stroke:inherit;color:inherit}.mscgen_js-svg-__svg .inherit-fill{fill:inherit}.mscgen_js-svg-__svg .watermark{stroke:black;color:black;fill:black;font-size:48pt;font-weight:bold;opacity:0.14}</style><marker orient="auto" id="mscgen_js-svg-__svgmethod-black" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1  9,3  1,5" class="arrow-style" stroke="black" fill="black"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-black" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="black" fill="black"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-blue" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1  9,3  1,5" class="arrow-style" stroke="blue" fill="blue"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-blue" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="blue" fill="blue"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-green" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1  9,3  1,5" class="arrow-style" stroke="green" fill="green"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-green" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="green" fill="green"></polygon></marker></defs><g id="mscgen_js-svg-__svg__body" transform="translate(53,3) scale(1,1)"><g id="mscgen_js-svg-__svg__background"><rect width="976" height="310" x="-53" y="-3" class="bglayer"></rect></g><g id="mscgen_js-svg-__svg__arcspanlayer"></g><g id="mscgen_js-svg-__svg__lifelinelayer"><line x1="75" y1="38" x2="75" y2="76" class="arcrow"></line><line x1="315" y1="38" x2="315" y2="76" class="arcrow"></line><line x1="555" y1="38" x2="555" y2="76" class="arcrow"></line><line x1="795" y1="38" x2="795" y2="76" class="arcrow"></line><line x1="75" y1="76" x2="75" y2="114" class="arcrow"></line><line x1="315" y1="76" x2="315" y2="114" class="arcrow"></line><line x1="555" y1="76" x2="555" y2="114" class="arcrow"></line><line x1="795" y1="76" x2="795" y2="114" class="arcrow"></line><line x1="75" y1="114" x2="75" y2="152" class="arcrow"></line><line x1="315" y1="114" x2="315" y2="152" class="arcrow"></line><line x1="555" y1="114" x2="555" y2="152" class="arcrow"></line><line x1="795" y1="114" x2="795" y2="152" class="arcrow"></line><line x1="75" y1="152" x2="75" y2="190" class="arcrow"></line><line x1="315" y1="152" x2="315" y2="190" class="arcrow"></line><line x1="555" y1="152" x2="555" y2="190" class="arcrow"></line><line x1="795" y1="152" x2="795" y2="190" class="arcrow"></line><line x1="75" y1="190" x2="75" y2="228" class="arcrow"></line><line x1="315" y1="190" x2="315" y2="228" class="arcrow"></line><line x1="555" y1="190" x2="555" y2="228" class="arcrow"></line><line x1="795" y1="190" x2="795" y2="228" class="arcrow"></line><line x1="75" y1="228" x2="75" y2="266" class="arcrow"></line><line x1="315" y1="228" x2="315" y2="266" class="arcrow"></line><line x1="555" y1="228" x2="555" y2="266" class="arcrow"></line><line x1="795" y1="228" x2="795" y2="266" class="arcrow"></line><line x1="75" y1="266" x2="75" y2="304" class="arcrow"></line><line x1="315" y1="266" x2="315" y2="304" class="arcrow"></line><line x1="555" y1="266" x2="555" y2="304" class="arcrow"></line><line x1="795" y1="266" x2="795" y2="304" class="arcrow"></line></g><g id="mscgen_js-svg-__svg__sequencelayer"><g id="mscgen_js-svg-__svgentities"><g><rect width="150" height="38" class="entity" style="fill:lime;"></rect><g><text x="75" y="22.5" class="entity-text "><tspan>Client</tspan></text></g></g><g><rect width="150" height="38" x="240" class="entity" style="fill:cyan;"></rect><g><text x="315" y="22.5" class="entity-text "><tspan>Rails</tspan></text></g></g><g><rect width="150" height="38" x="480" class="entity" style="fill:orange;"></rect><g><text x="555" y="22.5" class="entity-text "><tspan>EtagCaching</tspan></text></g></g><g><rect width="150" height="38" x="720" class="entity" style="fill:white;"></rect><g><text x="795" y="22.5" class="entity-text "><tspan>Redis</tspan></text></g></g></g><g><line x1="75" y1="95" x2="315" y2="95" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="127.97" y="79.5" class="label-text-background"></rect><text x="195" y="90.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="315" y1="133" x2="555" y2="133" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="367.97" y="117.5" class="label-text-background"></rect><text x="435" y="128.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="555" y1="171" x2="795" y2="171" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="135.64" height="14" x="607.17" y="155.5" class="label-text-background"></rect><text x="675" y="166.5" class="directional-text method-text "><tspan>read(key = 'GET &lt;Etag&gt;')</tspan></text></g></g><g><line x1="795" y1="209" x2="555" y2="209" class="arc directional method" style="stroke:green" marker-end="url(#mscgen_js-svg-__svgmethod-green)"></line><g><rect width="48.02" height="14" x="650.98" y="193.5" class="label-text-background"></rect><text x="675" y="204.5" class="directional-text method-text " style="fill:green;"><tspan>cache hit</tspan></text></g></g><g></g><g><line x1="555" y1="285" x2="75" y2="285" class="arc directional method" style="stroke:blue" marker-end="url(#mscgen_js-svg-__svgmethod-blue)"></line><g><rect width="90.72" height="14" x="269.63" y="269.5" class="label-text-background"></rect><text x="315" y="280.5" class="directional-text method-text " style="fill:blue;"><tspan>304 Not Modified</tspan></text></g></g></g><g id="mscgen_js-svg-__svg__notelayer"></g><g id="mscgen_js-svg-__svg__watermark"></g></g></svg>
\ No newline at end of file
diff --git a/doc/development/img/cache-miss.svg b/doc/development/img/cache-miss.svg
new file mode 100644
index 00000000000..8429e6a1918
--- /dev/null
+++ b/doc/development/img/cache-miss.svg
@@ -0,0 +1,24 @@
+<svg version="1.1" id="mscgen_js-svg-__svg" class="mscgen_js-svg-__svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="976" height="386" viewBox="0 0 976 386"><desc>
+
+# Generated by mscgen_js - https://sverweij.github.io/mscgen_js
+msc {
+  # options
+  hscale="1.5";
+
+  # entities
+  c [label="Client", textbgcolor="lime"],
+  rails [label="Rails", textbgcolor="cyan"],
+  etag [label="EtagCaching", textbgcolor="orange"],
+  redis [label="Redis", textbgcolor="white"];
+
+  # arcs
+  c =&gt; rails [label="GET /projects/5/pipelines"];
+  rails =&gt; etag [label="GET /projects/5/pipelines"];
+  etag =&gt; redis [label="read(key = 'GET &lt;Etag&gt;')"];
+  redis =&gt; etag [label="cache miss", linecolor="red", textcolor="red"];
+  |||;
+  etag =&gt; redis [label="write('&lt;New Etag&gt;')"];
+  etag =&gt; rails [label="GET /projects/5/pipelines"];
+  rails =&gt; c [label="JSON response w/ ETag", linecolor="blue", textcolor="blue"];
+}
+</desc><defs><style type="text/css">svg.mscgen_js-svg-__svg{font-family:Helvetica,sans-serif;font-size:12px;font-weight:normal;font-style:normal;text-decoration:none;background-color:white;stroke:black;stroke-width:2}.mscgen_js-svg-__svg path, .mscgen_js-svg-__svg rect{fill:none}.mscgen_js-svg-__svg .label-text-background{fill:white;stroke:white;stroke-width:0}.mscgen_js-svg-__svg .bglayer{fill:white;stroke:white;stroke-width:0}.mscgen_js-svg-__svg line{}.mscgen_js-svg-__svg .return, .mscgen_js-svg-__svg .comment{stroke-dasharray:5,3}.mscgen_js-svg-__svg .inline_expression_divider{stroke-dasharray:10,5}.mscgen_js-svg-__svg text{color:inherit;stroke:none;text-anchor:middle}.mscgen_js-svg-__svg text.entity-text{text-decoration:underline}.mscgen_js-svg-__svg text.anchor-start{text-anchor:start}.mscgen_js-svg-__svg .arrow-marker{overflow:visible}.mscgen_js-svg-__svg .arrow-style{stroke-width:1}.mscgen_js-svg-__svg .arcrow, .mscgen_js-svg-__svg .arcrowomit, .mscgen_js-svg-__svg .emphasised{stroke-linecap:butt}.mscgen_js-svg-__svg .arcrowomit{stroke-dasharray:2,2}.mscgen_js-svg-__svg .box, .mscgen_js-svg-__svg .entity{fill:white;stroke-linejoin:round}.mscgen_js-svg-__svg .inherit{stroke:inherit;color:inherit}.mscgen_js-svg-__svg .inherit-fill{fill:inherit}.mscgen_js-svg-__svg .watermark{font-size:48pt;font-weight:bold;opacity:0.14}</style><marker orient="auto" id="mscgen_js-svg-__svgmethod-black" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1  9,3  1,5" class="arrow-style" stroke="black" fill="black"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-black" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="black" fill="black"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-blue" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1  9,3  1,5" class="arrow-style" stroke="blue" fill="blue"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-blue" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="blue" fill="blue"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-red" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1  9,3  1,5" class="arrow-style" stroke="red" fill="red"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-red" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="red" fill="red"></polygon></marker></defs><g id="mscgen_js-svg-__svg__body" transform="translate(53,3) scale(1,1)"><g id="mscgen_js-svg-__svg__background"><rect width="976" height="386" x="-53" y="-3" class="bglayer"></rect></g><g id="mscgen_js-svg-__svg__arcspanlayer"></g><g id="mscgen_js-svg-__svg__lifelinelayer"><line x1="75" y1="38" x2="75" y2="76" class="arcrow"></line><line x1="315" y1="38" x2="315" y2="76" class="arcrow"></line><line x1="555" y1="38" x2="555" y2="76" class="arcrow"></line><line x1="795" y1="38" x2="795" y2="76" class="arcrow"></line><line x1="75" y1="76" x2="75" y2="114" class="arcrow"></line><line x1="315" y1="76" x2="315" y2="114" class="arcrow"></line><line x1="555" y1="76" x2="555" y2="114" class="arcrow"></line><line x1="795" y1="76" x2="795" y2="114" class="arcrow"></line><line x1="75" y1="114" x2="75" y2="152" class="arcrow"></line><line x1="315" y1="114" x2="315" y2="152" class="arcrow"></line><line x1="555" y1="114" x2="555" y2="152" class="arcrow"></line><line x1="795" y1="114" x2="795" y2="152" class="arcrow"></line><line x1="75" y1="152" x2="75" y2="190" class="arcrow"></line><line x1="315" y1="152" x2="315" y2="190" class="arcrow"></line><line x1="555" y1="152" x2="555" y2="190" class="arcrow"></line><line x1="795" y1="152" x2="795" y2="190" class="arcrow"></line><line x1="75" y1="190" x2="75" y2="228" class="arcrow"></line><line x1="315" y1="190" x2="315" y2="228" class="arcrow"></line><line x1="555" y1="190" x2="555" y2="228" class="arcrow"></line><line x1="795" y1="190" x2="795" y2="228" class="arcrow"></line><line x1="75" y1="228" x2="75" y2="266" class="arcrow"></line><line x1="315" y1="228" x2="315" y2="266" class="arcrow"></line><line x1="555" y1="228" x2="555" y2="266" class="arcrow"></line><line x1="795" y1="228" x2="795" y2="266" class="arcrow"></line><line x1="75" y1="266" x2="75" y2="304" class="arcrow"></line><line x1="315" y1="266" x2="315" y2="304" class="arcrow"></line><line x1="555" y1="266" x2="555" y2="304" class="arcrow"></line><line x1="795" y1="266" x2="795" y2="304" class="arcrow"></line><line x1="75" y1="304" x2="75" y2="342" class="arcrow"></line><line x1="315" y1="304" x2="315" y2="342" class="arcrow"></line><line x1="555" y1="304" x2="555" y2="342" class="arcrow"></line><line x1="795" y1="304" x2="795" y2="342" class="arcrow"></line><line x1="75" y1="342" x2="75" y2="380" class="arcrow"></line><line x1="315" y1="342" x2="315" y2="380" class="arcrow"></line><line x1="555" y1="342" x2="555" y2="380" class="arcrow"></line><line x1="795" y1="342" x2="795" y2="380" class="arcrow"></line></g><g id="mscgen_js-svg-__svg__sequencelayer"><g id="mscgen_js-svg-__svgentities"><g><rect width="150" height="38" class="entity" style="fill:lime;"></rect><g><text x="75" y="22.5" class="entity-text "><tspan>Client</tspan></text></g></g><g><rect width="150" height="38" x="240" class="entity" style="fill:cyan;"></rect><g><text x="315" y="22.5" class="entity-text "><tspan>Rails</tspan></text></g></g><g><rect width="150" height="38" x="480" class="entity" style="fill:orange;"></rect><g><text x="555" y="22.5" class="entity-text "><tspan>EtagCaching</tspan></text></g></g><g><rect width="150" height="38" x="720" class="entity" style="fill:white;"></rect><g><text x="795" y="22.5" class="entity-text "><tspan>Redis</tspan></text></g></g></g><g><line x1="75" y1="95" x2="315" y2="95" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="127.97" y="79.5" class="label-text-background"></rect><text x="195" y="90.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="315" y1="133" x2="555" y2="133" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="367.97" y="117.5" class="label-text-background"></rect><text x="435" y="128.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="555" y1="171" x2="795" y2="171" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="135.64" height="14" x="607.17" y="155.5" class="label-text-background"></rect><text x="675" y="166.5" class="directional-text method-text "><tspan>read(key = 'GET &lt;Etag&gt;')</tspan></text></g></g><g><line x1="795" y1="209" x2="555" y2="209" class="arc directional method" style="stroke:red" marker-end="url(#mscgen_js-svg-__svgmethod-red)"></line><g><rect width="60.02" height="14" x="644.98" y="193.5" class="label-text-background"></rect><text x="675" y="204.5" class="directional-text method-text " style="fill:red;"><tspan>cache miss</tspan></text></g></g><g></g><g><line x1="555" y1="285" x2="795" y2="285" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="103.94" height="14" x="623.02" y="269.5" class="label-text-background"></rect><text x="675" y="280.5" class="directional-text method-text "><tspan>write('&lt;New Etag&gt;')</tspan></text></g></g><g><line x1="555" y1="323" x2="315" y2="323" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="367.97" y="307.5" class="label-text-background"></rect><text x="435" y="318.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="315" y1="361" x2="75" y2="361" class="arc directional method" style="stroke:blue" marker-end="url(#mscgen_js-svg-__svgmethod-blue)"></line><g><rect width="130.72" height="14" x="129.63" y="345.5" class="label-text-background"></rect><text x="195" y="356.5" class="directional-text method-text " style="fill:blue;"><tspan>JSON response w/ ETag</tspan></text></g></g></g><g id="mscgen_js-svg-__svg__notelayer"></g><g id="mscgen_js-svg-__svg__watermark"></g></g></svg>
\ No newline at end of file
diff --git a/doc/development/polling.md b/doc/development/polling.md
index a7f2962acf0..4042b8aaa61 100644
--- a/doc/development/polling.md
+++ b/doc/development/polling.md
@@ -22,6 +22,9 @@ Instead you should use polling mechanism with ETag caching in Redis.
 
 ## How it works
 
+![Cache miss](img/cache-miss.svg)
+![Cache hit](img/cache-hit.svg)
+
 1. Whenever a resource changes we generate a random value and store it in
    Redis.
 1. When a client makes a request we set the `ETag` response header to the value
@@ -36,6 +39,12 @@ Instead you should use polling mechanism with ETag caching in Redis.
 1. If the `If-None-Match` header does not match the current value in Redis
    we have to generate a new response, because the resource changed.
 
+Do not use query parameters (for example `?scope=all`) for endpoints where you
+want to enable ETag caching. The middleware takes into account only the request
+path and ignores query parameters. All parameters should be included in the
+request path. By doing this we avoid query parameter ordering problems and make
+route matching easier.
+
 For more information see:
 - [RFC 7232](https://tools.ietf.org/html/rfc7232)
 - [ETag proposal](https://gitlab.com/gitlab-org/gitlab-ce/issues/26926)
diff --git a/doc/install/requirements.md b/doc/install/requirements.md
index 7b586138f42..35586091f74 100644
--- a/doc/install/requirements.md
+++ b/doc/install/requirements.md
@@ -129,6 +129,9 @@ If you want to run the database separately, expect a size of about 1 MB per user
 
 ### PostgreSQL Requirements
 
+As of GitLab 9.0, PostgreSQL 9.6 is recommended. Lower versions of PostgreSQL
+may work but primary testing and developement takes place using PostgreSQL 9.6.
+
 Users using PostgreSQL must ensure the `pg_trgm` extension is loaded into every
 GitLab database. This extension can be enabled (using a PostgreSQL super user)
 by running the following query for every database:
diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md
index 154a0f817da..1c493599cf8 100644
--- a/doc/update/patch_versions.md
+++ b/doc/update/patch_versions.md
@@ -57,7 +57,7 @@ sudo -u git -H bundle clean
 sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production
 
 # Clean up assets and cache
-sudo -u git -H bundle exec rake gitlab:assets:clean gitlab:assets:compile cache:clear RAILS_ENV=production
+sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile cache:clear RAILS_ENV=production
 ```
 
 ### 4. Update gitlab-workhorse to the corresponding version
diff --git a/doc/user/project/integrations/img/jira_project_settings.png b/doc/user/project/integrations/img/jira_project_settings.png
new file mode 100644
index 00000000000..cb6a6ba14ce
--- /dev/null
+++ b/doc/user/project/integrations/img/jira_project_settings.png
diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md
index 4c64d1e0907..e02f81fd972 100644
--- a/doc/user/project/integrations/jira.md
+++ b/doc/user/project/integrations/jira.md
@@ -157,6 +157,11 @@ the same goal:
 
 where `PROJECT-1` is the issue ID of the JIRA project.
 
+>**Note:**
+- Only commits and merges into the project's default branch (usually **master**) will
+  close an issue in Jira. You can change your projects default branch under
+  [project settings](img/jira_project_settings.png).
+
 ### JIRA issue closing example
 
 Let's consider the following example: