Merge branch 'master' into 'update-trace-handling-code'update-trace-handling-code

# Conflicts:
#   app/assets/javascripts/build.js

6 files changed, 332 insertions, 80 deletions

diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md
new file mode 100644
index 00000000000..affb4d17861
--- /dev/null
+++ b/doc/administration/raketasks/github_import.md
@@ -0,0 +1,36 @@
+# GitHub import
+
+>**Note:**
+>
+>  - [Introduced][ce-10308] in GitLab 9.1.
+>  - You need a personal access token in order to retrieve and import GitHub 
+>    projects. You can get it from: https://github.com/settings/tokens
+>  - You also need to pass an username as the second argument to the rake task
+>    which will become the owner of the project.
+
+To import a project from the list of your GitHub projects available:
+
+```bash
+# Omnibus installations
+sudo gitlab-rake import:github[access_token,root,foo/bar]
+
+# Installations from source
+bundle exec rake import:github[access_token,root,foo/bar] RAILS_ENV=production
+```
+
+In this case, `access_token` is your GitHub personal access token, `root`
+is your GitLab username, and  `foo/bar` is the new GitLab namespace/project that 
+will get created from your GitHub project. Subgroups are also possible: `foo/foo/bar`.
+
+
+To import a specific GitHub project (named `foo/github_repo` here):
+
+```bash
+# Omnibus installations
+sudo gitlab-rake import:github[access_token,root,foo/bar,foo/github_repo]
+
+# Installations from source
+bundle exec rake import:github[access_token,root,foo/bar,foo/github_repo] RAILS_ENV=production
+```
+
+[ce-10308]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10308
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/migration_style_guide.md b/doc/development/migration_style_guide.md
index fd8335d251e..587922d0136 100644
--- a/doc/development/migration_style_guide.md
+++ b/doc/development/migration_style_guide.md
@@ -58,10 +58,22 @@ migration was tested.
 
 ## Removing indices
 
-If you need to remove index, please add a condition like in following example:
+When removing an index make sure to use the method `remove_concurrent_index` instead
+of the regular `remove_index` method. The `remove_concurrent_index` method
+automatically drops concurrent indexes when using PostgreSQL, removing the
+need for downtime. To use this method you must disable transactions by calling
+the method `disable_ddl_transaction!` in the body of your migration class like
+so:
 
 ```ruby
-remove_index :namespaces, column: :name if index_exists?(:namespaces, :name)
+class MyMigration < ActiveRecord::Migration
+  include Gitlab::Database::MigrationHelpers
+  disable_ddl_transaction!
+
+  def up
+    remove_concurrent_index :table_name, :column_name if index_exists?(:table_name, :column_name)
+  end
+end
 ```
 
 ## Adding indices