19 files changed, 415 insertions, 235 deletions

diff --git a/doc/administration/build_artifacts.md b/doc/administration/build_artifacts.md
index 64353f7282b..3ba8387c7f0 100644
--- a/doc/administration/build_artifacts.md
+++ b/doc/administration/build_artifacts.md
@@ -84,7 +84,7 @@ _The artifacts are stored by default in
 ## Set the maximum file size of the artifacts
 
 Provided the artifacts are enabled, you can change the maximum file size of the
-artifacts through the [Admin area settings](../user/admin_area/settings/continuous_integration#maximum-artifacts-size).
+artifacts through the [Admin area settings](../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size).
 
 [reconfigure gitlab]: restart_gitlab.md "How to restart GitLab"
 [restart gitlab]: restart_gitlab.md "How to restart GitLab"
diff --git a/doc/api/branches.md b/doc/api/branches.md
index 07dfa5d4d7f..ffcfea41453 100644
--- a/doc/api/branches.md
+++ b/doc/api/branches.md
@@ -22,6 +22,7 @@ Example response:
 [
   {
     "name": "master",
+    "merged": false,
     "protected": true,
     "developers_can_push": false,
     "developers_can_merge": false,
@@ -65,6 +66,7 @@ Example response:
 ```json
 {
   "name": "master",
+  "merged": false,
   "protected": true,
   "developers_can_push": false,
   "developers_can_merge": false,
@@ -123,6 +125,7 @@ Example response:
     ]
   },
   "name": "master",
+  "merged": false,
   "protected": true,
   "developers_can_push": true,
   "developers_can_merge": true
@@ -166,6 +169,7 @@ Example response:
     ]
   },
   "name": "master",
+  "merged": false,
   "protected": false,
   "developers_can_push": false,
   "developers_can_merge": false
@@ -206,6 +210,7 @@ Example response:
     ]
   },
   "name": "newbranch",
+  "merged": false,
   "protected": false,
   "developers_can_push": false,
   "developers_can_merge": false
diff --git a/doc/api/projects.md b/doc/api/projects.md
index de57f91bb8e..132be644b59 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -626,6 +626,7 @@ Parameters:
 | `path` | string | no | Custom repository name for new project. By default generated based on name |
 | `default_branch` | string | no | `master` by default |
 | `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) |
+| `default_branch` | string | no | `master` by default |
 | `description` | string | no | Short project description |
 | `issues_enabled` | boolean | no | Enable issues for this project |
 | `merge_requests_enabled` | boolean | no | Enable merge requests for this project |
diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md
index 1bc6a24e914..b8c9eb2c9a8 100644
--- a/doc/api/repository_files.md
+++ b/doc/api/repository_files.md
@@ -60,7 +60,7 @@ Parameters:
 
 - `file_path` (required) - Full path to new file. Ex. lib/class.rb
 - `branch_name` (required) - The name of branch
-- `encoding` (optional) - 'text' or 'base64'. Text is default.
+- `encoding` (optional) - Change encoding to 'base64'. Default is text.
 - `author_email` (optional) - Specify the commit author's email address
 - `author_name` (optional) - Specify the commit author's name
 - `content` (required) - File content
@@ -89,7 +89,7 @@ Parameters:
 
 - `file_path` (required) - Full path to file. Ex. lib/class.rb
 - `branch_name` (required) - The name of branch
-- `encoding` (optional) - 'text' or 'base64'. Text is default.
+- `encoding` (optional) - Change encoding to 'base64'. Default is text.
 - `author_email` (optional) - Specify the commit author's email address
 - `author_name` (optional) - Specify the commit author's name
 - `content` (required) - New file content
diff --git a/doc/ci/README.md b/doc/ci/README.md
index 545cc72682d..db236ce2a66 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -21,6 +21,7 @@
 - [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
 
 ## Breaking changes
 
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md
index 89088cf9b83..28141cced3b 100644
--- a/doc/ci/docker/using_docker_build.md
+++ b/doc/ci/docker/using_docker_build.md
@@ -270,12 +270,16 @@ which can be avoided if a different driver is used, for example `overlay`.
 
 ## Using the GitLab Container Registry
 
-> **Note:**
-This feature requires GitLab 8.8 and GitLab Runner 1.2.
-
-Once you've built a Docker image, you can push it up to the built-in [GitLab Container Registry](../../user/project/container_registry.md). For example, if you're using
-docker-in-docker on your runners, this is how your `.gitlab-ci.yml` could look:
+> **Notes:**
+- This feature requires GitLab 8.8 and GitLab Runner 1.2.
+- Starting from GitLab 8.12, if you have 2FA enabled in your account, you need
+  to pass a personal access token instead of your password in order to login to
+  GitLab's Container Registry.
 
+Once you've built a Docker image, you can push it up to the built-in
+[GitLab Container Registry](../../user/project/container_registry.md). For example,
+if you're using docker-in-docker on your runners, this is how your `.gitlab-ci.yml`
+could look like:
 
 ```yaml
  build:
@@ -354,10 +358,20 @@ deploy:
 ```
 
 Some things you should be aware of when using the Container Registry:
-* You must log in to the container registry before running commands. Putting this in `before_script` will run it before each build job.
-* Using `docker build --pull` makes sure that Docker fetches any changes to base images before building just in case your cache is stale. It takes slightly longer, but means you don’t get stuck without security patches to base images.
-* Doing an explicit `docker pull` before each `docker run` makes sure to fetch the latest image that was just built. This is especially important if you are using multiple runners that cache images locally. Using the git SHA in your image tag makes this less necessary since each build will be unique and you shouldn't ever have a stale image, but it's still possible if you re-build a given commit after a dependency has changed.
-* You don't want to build directly to `latest` in case there are multiple builds happening simultaneously.
+
+- You must log in to the container registry before running commands. Putting
+  this in `before_script` will run it before each build job.
+- Using `docker build --pull` makes sure that Docker fetches any changes to base
+  images before building just in case your cache is stale. It takes slightly
+  longer, but means you don’t get stuck without security patches to base images.
+- Doing an explicit `docker pull` before each `docker run` makes sure to fetch
+  the latest image that was just built. This is especially important if you are
+  using multiple runners that cache images locally. Using the git SHA in your
+  image tag makes this less necessary since each build will be unique and you
+  shouldn't ever have a stale image, but it's still possible if you re-build a
+  given commit after a dependency has changed.
+- You don't want to build directly to `latest` in case there are multiple builds
+  happening simultaneously.
 
 [docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/
 [docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities
diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md
new file mode 100644
index 00000000000..1d782200cca
--- /dev/null
+++ b/doc/ci/git_submodules.md
@@ -0,0 +1,86 @@
+# Using Git submodules with GitLab CI
+
+> **Notes:**
+- GitLab 8.12 introduced a new [CI build permissions model][newperms] and you
+  are encouraged to upgrade your GitLab instance if you haven't done already.
+  If you are **not** using GitLab 8.12 or higher, you would need to work your way
+  around submodules in order to access the sources of e.g., `gitlab.com/group/project`
+  with the use of [SSH keys](ssh_keys/README.md).
+- With GitLab 8.12 onward, your permissions are used to evaluate what a CI build
+  can access. More information about how this system works can be found in the
+  [Build permissions model](../user/permissions.md#builds-permissions).
+- The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance.
+
+## Configuring the `.gitmodules` file
+
+If dealing with [Git submodules][gitscm], your project will probably have a file
+named `.gitmodules`.
+
+Let's consider the following example:
+
+1. Your project is located at `https://gitlab.com/secret-group/my-project`.
+1. To checkout your sources you usually use an SSH address like
+   `git@gitlab.com:secret-group/my-project.git`.
+1. Your project depends on `https://gitlab.com/group/project`, which you want
+   to include as a submodule.
+
+If you are using GitLab 8.12+ and your submodule is on the same GitLab server,
+you must update your `.gitmodules` file to use **relative URLs**.
+Since Git allows the usage of relative URLs for your `.gitmodules` configuration,
+this easily allows you to use HTTP(S) for cloning all your CI builds and SSH
+for all your local checkouts. The `.gitmodules` would look like:
+
+```ini
+[submodule "project"]
+  path = project
+  url = ../../group/project.git
+```
+
+The above configuration will instruct Git to automatically deduce the URL that
+should be used when cloning sources. Whether you use HTTP(S) or SSH, Git will use
+that same channel and it will allow to make all your CI builds use HTTP(S)
+(because GitLab CI only uses HTTP(S) for cloning your sources), and all your local
+clones will continue using SSH.
+
+For all other submodules not located on the same GitLab server, use the full
+HTTP(S) protocol URL:
+
+```ini
+[submodule "project-x"]
+  path = project-x
+  url = https://gitserver.com/group/project-x.git
+```
+
+Once `.gitmodules` is correctly configured, you can move on to
+[configuring your `.gitlab-ci.yml`](#using-git-submodules-in-your-ci-jobs).
+
+## Using Git submodules in your CI jobs
+
+There are a few steps you need to take in order to make submodules work
+correctly with your CI builds:
+
+1. First, make sure you have used [relative URLs](#configuring-the-gitmodules-file)
+   for the submodules located in the same GitLab server.
+1. Then, use `git submodule sync/update` in `before_script`:
+
+    ```yaml
+    before_script:
+      - git submodule sync --recursive
+      - git submodule update --init --recursive
+    ```
+
+    `--recursive` should be used in either both or none (`sync/update`) depending on
+    whether you have recursive submodules.
+
+The rationale to set the `sync` and `update` in `before_script` is because of
+the way Git submodules work. On a fresh Runner workspace, Git will set the
+submodule URL including the token in `.git/config`
+(or `.git/modules/<submodule>/config`) based on `.gitmodules` and the current
+remote URL. On subsequent builds on the same Runner, `.git/config` is cached
+and already contains a full URL for the submodule, corresponding to the previous
+build, and to **a token from a previous build**. `sync` allows to force updating
+the full URL.
+
+[gitpro]: ../user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols
+[gitscm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules "Git submodules documentation"
+[newperms]: ../user/project/new_ci_build_permissions_model.md
diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md
index cf7c55f75f2..efca05af7b8 100644
--- a/doc/ci/triggers/README.md
+++ b/doc/ci/triggers/README.md
@@ -6,7 +6,7 @@
 GitLab 8.12 has a completely redesigned build permissions system.
 Read all about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#build-triggers).
 
-Triggers can be used to force a rebuild of a specific branch, tag or commit,
+Triggers can be used to force a rebuild of a specific `ref` (branch or tag)
 with an API call.
 
 ## Add a trigger
@@ -29,6 +29,10 @@ irreversible.
 
 ## Trigger a build
 
+> **Note**:
+Valid refs are only the branches and tags. If you pass a commit SHA as a ref,
+it will not trigger a build.
+
 To trigger a build you need to send a `POST` request to GitLab's API endpoint:
 
 ```
@@ -36,8 +40,8 @@ POST /projects/:id/trigger/builds
 ```
 
 The required parameters are the trigger's `token` and the Git `ref` on which
-the trigger will be performed. Valid refs are the branch, the tag or the commit
-SHA. The `:id` of a project can be found by [querying the API](../../api/projects.md)
+the trigger will be performed. Valid refs are the branch and the tag. The `:id`
+of a project can be found by [querying the API](../../api/projects.md)
 or by visiting the **Triggers** page which provides self-explanatory examples.
 
 When a rebuild is triggered, the information is exposed in GitLab's UI under
diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md
index 7bfc9cb361f..0f78e8238af 100644
--- a/doc/development/gotchas.md
+++ b/doc/development/gotchas.md
@@ -141,51 +141,3 @@ in an initializer._
 ### Further reading
 
 - Stack Overflow: [Why you should not write inline JavaScript](http://programmers.stackexchange.com/questions/86589/why-should-i-avoid-inline-scripting)
-
-## ID-based CSS selectors need to be a bit more specific
-
-Normally, because HTML `id` attributes need to be unique to the page, it's
-perfectly fine to write some JavaScript like the following:
-
-```javascript
-$('#js-my-selector').hide();
-```
-
-However, there's a feature of GitLab's Markdown processing that [automatically
-adds anchors to header elements][ToC Processing], with the `id` attribute being
-automatically generated based on the content of the header.
-
-Unfortunately, this feature makes it possible for user-generated content to
-create a header element with the same `id` attribute we're using in our
-selector, potentially breaking the JavaScript behavior. A user could break the
-above example with the following Markdown:
-
-```markdown
-## JS My Selector
-```
-
-Which gets converted to the following HTML:
-
-```html
-<h2>
-  <a id="js-my-selector" class="anchor" href="#js-my-selector" aria-hidden="true"></a>
-  JS My Selector
-</h2>
-```
-
-[ToC Processing]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-4-stable/lib/banzai/filter/table_of_contents_filter.rb#L31-37
-
-### Solution
-
-The current recommended fix for this is to make our selectors slightly more
-specific:
-
-```javascript
-$('div#js-my-selector').hide();
-```
-
-### Further reading
-
-- Issue: [Merge request ToC anchor conflicts with tabs](https://gitlab.com/gitlab-org/gitlab-ce/issues/3908)
-- Merge Request: [Make tab target selectors less naive](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2023)
-- Merge Request: [Make cross-project reference's clipboard target less naive](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2024)
diff --git a/doc/install/installation.md b/doc/install/installation.md
index ee02d6024d9..4b0c585e51e 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -175,7 +175,7 @@ We recommend using a PostgreSQL database. For MySQL check the
     ```bash
     sudo -u postgres psql -d template1 -c "CREATE USER git CREATEDB;"
     ```
-    
+
 1. Create the `pg_trgm` extension (required for GitLab 8.6+):
 
     ```bash
@@ -396,15 +396,13 @@ GitLab Shell is an SSH access and repository management software developed speci
 
 ### Install gitlab-workhorse
 
-GitLab-Workhorse uses [GNU Make](https://www.gnu.org/software/make/).
-If you are not using Linux you may have to run `gmake` instead of
-`make` below.
+GitLab-Workhorse uses [GNU Make](https://www.gnu.org/software/make/). The
+following command-line will install GitLab-Workhorse in `/home/git/gitlab-workhorse`
+which is the recommended location.
 
-    cd /home/git
-    sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-workhorse.git
-    cd gitlab-workhorse
-    sudo -u git -H git checkout v1.0.1
-    sudo -u git -H make
+    cd /home/git/gitlab
+
+    sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production
 
 ### Initialize Database and Activate Advanced Features
 
diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md
index 17485b11c09..f42bb6a81a2 100644
--- a/doc/raketasks/backup_restore.md
+++ b/doc/raketasks/backup_restore.md
@@ -353,7 +353,7 @@ restore:
 
 ```shell
 # This command will overwrite the contents of your GitLab database!
-sudo gitlab-rake gitlab:backup:restore BACKUP=1393513186
+sudo gitlab-rake gitlab:backup:restore BACKUP=1393513186_2014_02_27
 ```
 
 Restart and check GitLab:
diff --git a/doc/update/8.12-to-8.13.md b/doc/update/8.12-to-8.13.md
index c0084d9d59c..8c0d3f78b55 100644
--- a/doc/update/8.12-to-8.13.md
+++ b/doc/update/8.12-to-8.13.md
@@ -166,7 +166,7 @@ See [smtp_settings.rb.sample] as an example.
 Ensure you're still up-to-date with the latest init script changes:
 
     sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
-    
+
 For Ubuntu 16.04.1 LTS:
 
     sudo systemctl daemon-reload
diff --git a/doc/update/8.14-to-8.15.md b/doc/update/8.14-to-8.15.md
new file mode 100644
index 00000000000..576b943b98c
--- /dev/null
+++ b/doc/update/8.14-to-8.15.md
@@ -0,0 +1,202 @@
+# From 8.14 to 8.15
+
+Make sure you view this update guide from the tag (version) of GitLab you would
+like to install. In most cases this should be the highest numbered production
+tag (without rc in it). You can select the tag in the version dropdown at the
+top left corner of GitLab (below the menu bar).
+
+If the highest number stable branch is unclear please check the
+[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation
+guide links by version.
+
+### 1. Stop server
+
+    sudo service gitlab stop
+
+### 2. Backup
+
+```bash
+cd /home/git/gitlab
+sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
+```
+
+### 3. Update Ruby
+
+We will continue supporting Ruby < 2.3 for the time being but we recommend you
+upgrade to Ruby 2.3 if you're running a source installation, as this is the same
+version that ships with our Omnibus package.
+
+You can check which version you are running with `ruby -v`.
+
+Download and compile Ruby:
+
+```bash
+mkdir /tmp/ruby && cd /tmp/ruby
+curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.1.tar.gz
+echo 'c39b4001f7acb4e334cb60a0f4df72d434bef711  ruby-2.3.1.tar.gz' | shasum --check - && tar xzf ruby-2.3.1.tar.gz
+cd ruby-2.3.1
+./configure --disable-install-rdoc
+make
+sudo make install
+```
+
+Install Bundler:
+
+```bash
+sudo gem install bundler --no-ri --no-rdoc
+```
+
+### 4. Get latest code
+
+```bash
+sudo -u git -H git fetch --all
+sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically
+```
+
+For GitLab Community Edition:
+
+```bash
+sudo -u git -H git checkout 8-15-stable
+```
+
+OR
+
+For GitLab Enterprise Edition:
+
+```bash
+sudo -u git -H git checkout 8-15-stable-ee
+```
+
+### 5. Update gitlab-shell
+
+```bash
+cd /home/git/gitlab-shell
+sudo -u git -H git fetch --all --tags
+sudo -u git -H git checkout v4.0.0
+```
+
+### 6. Update gitlab-workhorse
+
+Install and compile gitlab-workhorse. This requires
+[Go 1.5](https://golang.org/dl) which should already be on your system from
+GitLab 8.1.
+
+```bash
+sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production
+```
+
+### 7. Install libs, migrations, etc.
+
+```bash
+cd /home/git/gitlab
+
+# MySQL installations (note: the line below states '--without postgres')
+sudo -u git -H bundle install --without postgres development test --deployment
+
+# PostgreSQL installations (note: the line below states '--without mysql')
+sudo -u git -H bundle install --without mysql development test --deployment
+
+# Optional: clean up old gems
+sudo -u git -H bundle clean
+
+# Run database migrations
+sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production
+
+# Clean up assets and cache
+sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production
+```
+
+### 8. Update configuration files
+
+#### New configuration options for `gitlab.yml`
+
+There are new configuration options available for [`gitlab.yml`](config/gitlab.yml.example). View them with the command below and apply them manually to your current `gitlab.yml`:
+
+```sh
+git diff origin/8-13-stable:config/gitlab.yml.example origin/8-15-stable:config/gitlab.yml.example
+```
+
+#### Git configuration
+
+Configure Git to generate packfile bitmaps (introduced in Git 2.0) on
+the GitLab server during `git gc`.
+
+```sh
+sudo -u git -H git config --global repack.writeBitmaps true
+```
+
+#### Nginx configuration
+
+Ensure you're still up-to-date with the latest NGINX configuration changes:
+
+```sh
+# For HTTPS configurations
+git diff origin/8-13-stable:lib/support/nginx/gitlab-ssl origin/8-15-stable:lib/support/nginx/gitlab-ssl
+
+# For HTTP configurations
+git diff origin/8-13-stable:lib/support/nginx/gitlab origin/8-15-stable:lib/support/nginx/gitlab
+```
+
+If you are using Apache instead of NGINX please see the updated [Apache templates].
+Also note that because Apache does not support upstreams behind Unix sockets you
+will need to let gitlab-workhorse listen on a TCP port. You can do this
+via [/etc/default/gitlab].
+
+[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache
+[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-15-stable/lib/support/init.d/gitlab.default.example#L38
+
+#### SMTP configuration
+
+If you're installing from source and use SMTP to deliver mail, you will need to add the following line
+to config/initializers/smtp_settings.rb:
+
+```ruby
+ActionMailer::Base.delivery_method = :smtp
+```
+
+See [smtp_settings.rb.sample] as an example.
+
+[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-15-stable/config/initializers/smtp_settings.rb.sample#L13
+
+#### Init script
+
+Ensure you're still up-to-date with the latest init script changes:
+
+    sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
+
+For Ubuntu 16.04.1 LTS:
+
+    sudo systemctl daemon-reload
+
+### 9. Start application
+
+    sudo service gitlab start
+    sudo service nginx restart
+
+### 10. Check application status
+
+Check if GitLab and its environment are configured correctly:
+
+    sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production
+
+To make sure you didn't miss anything run a more thorough check:
+
+    sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production
+
+If all items are green, then congratulations, the upgrade is complete!
+
+## Things went south? Revert to previous version (8.14)
+
+### 1. Revert the code to the previous version
+
+Follow the [upgrade guide from 8.13 to 8.14](8.13-to-8.14.md), except for the
+database migration (the backup is already migrated to the previous version).
+
+### 2. Restore from the backup
+
+```bash
+cd /home/git/gitlab
+sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
+```
+
+If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above.
diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md
index 60729316cde..e98c40ca4c0 100644
--- a/doc/update/patch_versions.md
+++ b/doc/update/patch_versions.md
@@ -45,10 +45,9 @@ sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_SHELL_VERSION` -b v`ca
 ### 4. Update gitlab-workhorse to the corresponding version
 
 ```bash
-cd /home/git/gitlab-workhorse
-sudo -u git -H git fetch
-sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_WORKHORSE_VERSION` -b v`cat /home/git/gitlab/GITLAB_WORKHORSE_VERSION`
-sudo -u git -H make
+cd /home/git/gitlab
+
+sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production
 ```
 
 ### 5. Install libs, migrations, etc.
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index cea78864df2..39fe2409a29 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -141,10 +141,9 @@ instance and project. In addition, all admins can use the admin interface under
 | See events in the system              |                 |             |          | ✓      |
 | Admin interface                       |                 |             |          | ✓      |
 
-### Build permissions
-
-> Changed in GitLab 8.12.
+### Builds permissions
 
+>**Note:**
 GitLab 8.12 has a completely redesigned build permissions system.
 Read all about the [new model and its implications][new-mod].
 
diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md
index b205fea2c40..47a4a3f85d0 100644
--- a/doc/user/project/container_registry.md
+++ b/doc/user/project/container_registry.md
@@ -4,13 +4,15 @@
 
 ---
 
-> **Note**
-Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker
-versions earlier than 1.10.
->
-This document is about the user guide. To learn how to enable GitLab Container
-Registry across your GitLab instance, visit the
-[administrator documentation](../../administration/container_registry.md).
+>**Notes:**
+- Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker
+  versions earlier than 1.10.
+- This document is about the user guide. To learn how to enable GitLab Container
+  Registry across your GitLab instance, visit the
+  [administrator documentation](../../administration/container_registry.md).
+- Starting from GitLab 8.12, if you have 2FA enabled in your account, you need
+  to pass a personal access token instead of your password in order to login to
+  GitLab's Container Registry.
 
 With the Docker Container Registry integrated into GitLab, every project can
 have its own space to store its Docker images.
diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md
index 60b7bec2ba7..320faff65c5 100644
--- a/doc/user/project/new_ci_build_permissions_model.md
+++ b/doc/user/project/new_ci_build_permissions_model.md
@@ -34,9 +34,9 @@ as created be the pusher (local push or via the UI) and any build created in thi
 pipeline will have the permissions of the pusher.
 
 This allows us to make it really easy to evaluate the access for all projects
-that have Git submodules or are using container images that the pusher would
-have access too. **The permission is granted only for time that build is running.
-The access is revoked after the build is finished.**
+that have [Git submodules][gitsub] or are using container images that the pusher
+would have access too. **The permission is granted only for time that build is
+running. The access is revoked after the build is finished.**
 
 ## Types of users
 
@@ -141,7 +141,7 @@ with GitLab 8.12.
 With the new build permissions model, there is now an easy way to access all
 dependent source code in a project. That way, we can:
 
-1. Access a project's Git submodules
+1. Access a project's [Git submodules][gitsub]
 1. Access private container images
 1. Access project's and submodule LFS objects
 
@@ -179,119 +179,25 @@ As a user:
 
 ### Git submodules
 
->
-It often happens that while working on one project, you need to use another
-project from within it; perhaps it’s a library that a third party developed or
-you’re developing a project separately and are using it in multiple parent
-projects.
-A common issue arises in these scenarios: you want to be able to treat the two
-projects as separate yet still be able to use one from within the other.
->
-_Excerpt from the [Git website][git-scm] about submodules._
-
-If dealing with submodules, your project will probably have a file named
-`.gitmodules`. And this is how it usually looks like:
-
-```
-[submodule "tools"]
-	path = tools
-	url = git@gitlab.com/group/tools.git
-```
-
-> **Note:**
-If you are **not** using GitLab 8.12 or higher, you would need to work your way
-around this issue in order to access the sources of `gitlab.com/group/tools`
-(e.g., use [SSH keys](../ssh_keys/README.md)).
->
-With GitLab 8.12 onward, your permissions are used to evaluate what a CI build
-can access. More information about how this system works can be found in the
-[Build permissions model](../../user/permissions.md#builds-permissions).
-
-To make use of the new changes, you have to update your `.gitmodules` file to
-use a relative URL.
-
-Let's consider the following example:
-
-1. Your project is located at `https://gitlab.com/secret-group/my-project`.
-1. To checkout your sources you usually use an SSH address like
-   `git@gitlab.com:secret-group/my-project.git`.
-1. Your project depends on `https://gitlab.com/group/tools`.
-1. You have the `.gitmodules` file with above content.
-
-Since Git allows the usage of relative URLs for your `.gitmodules` configuration,
-this easily allows you to use HTTP for cloning all your CI builds and SSH
-for all your local checkouts.
-
-For example, if you change the `url` of your `tools` dependency, from
-`git@gitlab.com/group/tools.git` to `../../group/tools.git`, this will instruct
-Git to automatically deduce the URL that should be used when cloning sources.
-Whether you use HTTP or SSH, Git will use that same channel and it will allow
-to make all your CI builds use HTTPS (because GitLab CI uses HTTPS for cloning
-your sources), and all your local clones will continue using SSH.
-
-Given the above explanation, your `.gitmodules` file should eventually look
-like this:
-
-```
-[submodule "tools"]
-	path = tools
-	url = ../../group/tools.git
-```
-
-However, you have to explicitly tell GitLab CI to clone your submodules as this
-is not done automatically. You can achieve that by adding a `before_script`
-section to your `.gitlab-ci.yml`:
-
-```
-before_script:
-  - git submodule update --init --recursive
-
-test:
-  script:
-    - run-my-tests
-```
-
-This will make GitLab CI initialize (fetch) and update (checkout) all your
-submodules recursively.
-
-If Git does not use the newly added relative URLs but still uses your old URLs,
-you might need to add `git submodule sync --recursive` to your `.gitlab-ci.yml`,
-prior to running `git submodule update --init --recursive`. This transfers the
-changes from your `.gitmodules` file into the `.git` folder, which is kept by
-runners between runs.
-
-In case your environment or your Docker image doesn't have Git installed,
-you have to either ask your Administrator or install the missing dependency
-yourself:
-
-```
-# Debian / Ubuntu
-before_script:
-  - apt-get update -y
-  - apt-get install -y git-core
-  - git submodule update --init --recursive
-
-# CentOS / RedHat
-before_script:
-  - yum install git
-  - git submodule update --init --recursive
-
-# Alpine
-before_script:
-  - apk add -U git
-  - git submodule update --init --recursive
-```
+To properly configure submodules with GitLab CI, read the
+[Git submodules documentation][gitsub].
 
 ### Container Registry
 
 With the update permission model we also extended the support for accessing
 Container Registries for private projects.
 
-> **Note:**
-As GitLab Runner 1.6 doesn't yet incorporate the introduced changes for
-permissions, this makes the `image:` directive to not work with private projects
-automatically. The manual configuration by an Administrator is required to use
-private images. We plan to remove that limitation in one of the upcoming releases.
+> **Notes:**
+- GitLab Runner versions prior to 1.8 don't incorporate the introduced changes
+  for permissions. This makes the `image:` directive to not work with private
+  projects automatically and it needs to be configured manually on Runner's host
+  with a predefined account (for example administrator's personal account with
+  access token created explicitly for this purpose). This issue is resolved with
+  latest changes in GitLab Runner 1.8 which receives GitLab credentials with
+  build data.
+- Starting with GitLab 8.12, if you have 2FA enabled in your account, you need
+  to pass a personal access token instead of your password in order to login to
+  GitLab's Container Registry.
 
 Your builds can access all container images that you would normally have access
 to. The only implication is that you can push to the Container Registry of the
@@ -310,7 +216,7 @@ test:
 [build permissions]: ../permissions.md#builds-permissions
 [comment]: https://gitlab.com/gitlab-org/gitlab-ce/issues/22484#note_16648302
 [ext]: ../permissions.md#external-users
-[git-scm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
+[gitsub]: ../../ci/git_submodules.md
 [https]: ../admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols
 [triggers]: ../../ci/triggers/README.md
 [update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update
diff --git a/doc/web_hooks/ssl.png b/doc/web_hooks/ssl.png
index a552888ed96..21ddec4ebdf 100644
--- a/doc/web_hooks/ssl.png
+++ b/doc/web_hooks/ssl.png
diff --git a/doc/web_hooks/web_hooks.md b/doc/web_hooks/web_hooks.md
index cd37189fdd2..1659dd1f6cb 100644
--- a/doc/web_hooks/web_hooks.md
+++ b/doc/web_hooks/web_hooks.md
@@ -1,17 +1,21 @@
 # Webhooks
 
-_**Note:**
-Starting from GitLab 8.5:_
+>**Note:**
+Starting from GitLab 8.5:
+- the `repository` key is deprecated in favor of the `project` key
+- the `project.ssh_url` key is deprecated in favor of the `project.git_ssh_url` key
+- the `project.http_url` key is deprecated in favor of the `project.git_http_url` key
 
-- _the `repository` key is deprecated in favor of the `project` key_
-- _the `project.ssh_url` key is deprecated in favor of the `project.git_ssh_url` key_
-- _the `project.http_url` key is deprecated in favor of the `project.git_http_url` key_
+Project webhooks allow you to trigger a URL if for example new code is pushed or
+a new issue is created. You can configure webhooks to listen for specific events
+like pushes, issues or merge requests. GitLab will send a POST request with data
+to the webhook URL.
 
-Project webhooks allow you to trigger an URL if new code is pushed or a new issue is created.
+Webhooks can be used to update an external issue tracker, trigger CI builds,
+update a backup mirror, or even deploy to your production server.
 
-You can configure webhooks to listen for specific events like pushes, issues or merge requests. GitLab will send a POST request with data to the webhook URL.
-
-Webhooks can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server.
+Navigate to the webhooks page by choosing **Webhooks** from your project's
+settings which can be found under the wheel icon in the upper right corner.
 
 ## Webhook endpoint tips
 
@@ -26,21 +30,27 @@ GitLab webhooks keep in mind the following things:
     you are writing a low-level hook this is important to remember.
 -   GitLab ignores the HTTP status code returned by your endpoint.
 
-## Secret Token
+## Secret token
 
-If you specify a secret token, it will be sent with the hook request in the `X-Gitlab-Token` HTTP header. Your webhook endpoint can check that to verify that the request is legitimate.
+If you specify a secret token, it will be sent with the hook request in the
+`X-Gitlab-Token` HTTP header. Your webhook endpoint can check that to verify
+that the request is legitimate.
 
-## SSL Verification
+## SSL verification
 
 By default, the SSL certificate of the webhook endpoint is verified based on
-an internal list of Certificate Authorities,
-which means the certificate cannot be self-signed.
+an internal list of Certificate Authorities, which means the certificate cannot
+be self-signed.
 
 You can turn this off in the webhook settings in your GitLab projects.
 
 ![SSL Verification](ssl.png)
 
-## Push events
+## Events
+
+Below are described the supported events.
+
+### Push events
 
 Triggered when you push to the repository except when pushing tags.
 
@@ -121,7 +131,7 @@ X-Gitlab-Event: Push Hook
 }
 ```
 
-## Tag events
+### Tag events
 
 Triggered when you create (or delete) tags to the repository.
 
@@ -174,7 +184,7 @@ X-Gitlab-Event: Tag Push Hook
 }
 ```
 
-## Issues events
+### Issues events
 
 Triggered when a new issue is created or an existing issue was updated/closed/reopened.
 
@@ -240,7 +250,7 @@ X-Gitlab-Event: Issue Hook
   }
 }
 ```
-## Comment events
+### Comment events
 
 Triggered when a new comment is made on commits, merge requests, issues, and code snippets.
 The note data will be stored in `object_attributes` (e.g. `note`, `noteable_type`). The
@@ -253,7 +263,7 @@ Valid target types:
 3. `issue`
 4. `snippet`
 
-### Comment on commit
+#### Comment on commit
 
 **Request header**:
 
@@ -332,7 +342,7 @@ X-Gitlab-Event: Note Hook
 }
 ```
 
-### Comment on merge request
+#### Comment on merge request
 
 **Request header**:
 
@@ -459,7 +469,7 @@ X-Gitlab-Event: Note Hook
 }
 ```
 
-### Comment on issue
+#### Comment on issue
 
 **Request header**:
 
@@ -534,7 +544,7 @@ X-Gitlab-Event: Note Hook
 }
 ```
 
-### Comment on code snippet
+#### Comment on code snippet
 
 **Request header**:
 
@@ -607,7 +617,7 @@ X-Gitlab-Event: Note Hook
 }
 ```
 
-## Merge request events
+### Merge request events
 
 Triggered when a new merge request is created, an existing merge request was updated/merged/closed or a commit is added in the source branch.
 
@@ -699,7 +709,7 @@ X-Gitlab-Event: Merge Request Hook
 }
 ```
 
-## Wiki Page events
+### Wiki Page events
 
 Triggered when a wiki page is created or edited.
 
@@ -737,9 +747,9 @@ X-Gitlab-Event: Wiki Page Hook
   },
   "wiki": {
     "web_url": "http://example.com/root/awesome-project/wikis/home",
-    "git_ssh_url": "git@example.com:root/awesome-project.wiki.git", 
-    "git_http_url": "http://example.com/root/awesome-project.wiki.git", 
-    "path_with_namespace": "root/awesome-project.wiki", 
+    "git_ssh_url": "git@example.com:root/awesome-project.wiki.git",
+    "git_http_url": "http://example.com/root/awesome-project.wiki.git",
+    "path_with_namespace": "root/awesome-project.wiki",
     "default_branch": "master"
   },
   "object_attributes": {
@@ -754,7 +764,7 @@ X-Gitlab-Event: Wiki Page Hook
 }
 ```
 
-## Pipeline events
+### Pipeline events
 
 Triggered on status change of Pipeline.
 
@@ -922,8 +932,7 @@ X-Gitlab-Event: Pipeline Hook
 }
 ```
 
-
-## Build events
+### Build events
 
 Triggered on status change of a Build.
 
@@ -935,7 +944,7 @@ X-Gitlab-Event: Build Hook
 
 **Request Body**:
 
-```
+```json
 {
   "object_kind": "build",
   "ref": "gitlab-script-trigger",
@@ -980,12 +989,13 @@ X-Gitlab-Event: Build Hook
 }
 ```
 
-#### Example webhook receiver
+## Example webhook receiver
 
 If you want to see GitLab's webhooks in action for testing purposes you can use
-a simple echo script running in a console session.
+a simple echo script running in a console session. For the following script to
+work you need to have Ruby installed.
 
-Save the following file as `print_http_body.rb`.
+Save the following file as `print_http_body.rb`:
 
 ```ruby
 require 'webrick'
@@ -1005,7 +1015,8 @@ Pick an unused port (e.g. 8000) and start the script: `ruby print_http_body.rb
 8000`.  Then add your server as a webhook receiver in GitLab as
 `http://my.host:8000/`.
 
-When you press 'Test Hook' in GitLab, you should see something like this in the console.
+When you press 'Test Hook' in GitLab, you should see something like this in the
+console:
 
 ```
 {"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>}