Merge branch 'master' of gitlab.com:gitlab-org/gitlab-ce into update-ruby-2.2.4

# Conflicts:
#	.gitlab-ci.yml

8 files changed, 242 insertions, 6 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index 4cdd2e1ad33..5886829be51 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -12,6 +12,7 @@
 * [Using Variables](variables/README.md)
 * [Using SSH keys](ssh_keys/README.md)
 * [Triggering builds through the API](triggers/README.md)
+* [Build artifacts](build_artifacts/README.md)
 
 ### Languages
 
diff --git a/doc/ci/api/commits.md b/doc/ci/api/commits.md
index 4df7afc6c52..871de7abcce 100644
--- a/doc/ci/api/commits.md
+++ b/doc/ci/api/commits.md
@@ -1,5 +1,12 @@
 # Commits API
 
+**DEPRECATED**
+
+Since GitLab 8.1, there is a new commit status API. Please see the [revised
+documentation](../../api/commits.md#commit-status).
+
+---
+
 __Authentication is done by GitLab CI project token__
 
 ## Commits
diff --git a/doc/ci/build_artifacts/README.md b/doc/ci/build_artifacts/README.md
new file mode 100644
index 00000000000..61418cef2c6
--- /dev/null
+++ b/doc/ci/build_artifacts/README.md
@@ -0,0 +1,171 @@
+# Introduction to build artifacts
+
+Artifacts is a list of files and directories which are attached to a build
+after it completes successfully.
+
+Since GitLab 8.2 and [GitLab Runner] 0.7.0, build artifacts that are created by
+GitLab Runner are uploaded to GitLab and are downloadable as a single archive
+(`tar.gz`) using the GitLab UI.
+
+Starting from GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format
+changed to `ZIP`, and it is now possible to browse its contents, with the added
+ability of downloading the files separately.
+
+## Enabling build artifacts
+
+_If you are searching for ways to use artifacts, jump to
+[Defining artifacts in `.gitlab-ci.yml`](#defining-artifacts-in-gitlab-ciyml)._
+
+The artifacts feature is enabled by default in all GitLab installations.
+To disable it site-wide, follow the steps below.
+
+---
+
+**In Omnibus installations:**
+
+1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
+
+    ```ruby
+    gitlab_rails['artifacts_enabled'] = false
+    ```
+
+1. Save the file and [reconfigure GitLab][] for the changes to take effect.
+
+---
+
+**In installations from source:**
+
+1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
+
+    ```yaml
+    artifacts:
+      enabled: false
+    ```
+
+1. Save the file and [restart GitLab][] for the changes to take effect.
+
+## Defining artifacts in `.gitlab-ci.yml`
+
+A simple example of using the artifacts definition in `.gitlab-ci.yml` would be
+the following:
+
+```yaml
+pdf:
+  script: xelatex mycv.tex
+  artifacts:
+    paths:
+    - mycv.pdf
+```
+
+A job named `pdf` calls the `xelatex` command in order to build a pdf file from
+the latex source file `mycv.tex`. We then define the `artifacts` paths which in
+turn are defined with the `paths` keyword. All paths to files and directories
+are relative to the repository that was cloned during the build.
+
+For more examples on artifacts, follow the
+[separate artifacts yaml documentation](../yaml/README.md#artifacts).
+
+## Storing build artifacts
+
+After a successful build, GitLab Runner uploads an archive containing the build
+artifacts to GitLab.
+
+To change the location where the artifacts are stored, follow the steps below.
+
+---
+
+**In Omnibus installations:**
+
+_The artifacts are stored by default in
+`/var/opt/gitlab/gitlab-rails/shared/artifacts`._
+
+1. To change the storage path for example to `/mnt/storage/artifacts`, edit
+   `/etc/gitlab/gitlab.rb` and add the following line:
+
+    ```ruby
+    gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts"
+    ```
+
+1. Save the file and [reconfigure GitLab][] for the changes to take effect.
+
+---
+
+**In installations from source:**
+
+_The artifacts are stored by default in
+`/home/git/gitlab/shared/artifacts`._
+
+1. To change the storage path for example to `/mnt/storage/artifacts`, edit
+   `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
+
+    ```yaml
+    artifacts:
+      enabled: true
+      path: /mnt/storage/artifacts
+    ```
+
+1. Save the file and [restart GitLab][] for the changes to take effect.
+
+## Browsing build artifacts
+
+When GitLab receives an artifacts archive, an archive metadata file is also
+generated. This metadata file describes all the entries that are located in the
+artifacts archive itself. The metadata file is in a binary format, with
+additional GZIP compression.
+
+GitLab does not extract the artifacts archive in order to save space, memory
+and disk I/O. It instead inspects the metadata file which contains all the
+relevant information. This is especially important when there is a lot of
+artifacts, or an archive is a very large file.
+
+---
+
+After a successful build, if you visit the build's specific page, you can see
+that there are two buttons.
+
+One is for downloading the artifacts archive and the other for browsing its
+contents.
+
+![Build artifacts browser button](img/build_artifacts_browser_button.png)
+
+---
+
+The archive browser shows the name and the actual file size of each file in the
+archive. If your artifacts contained directories, then you are also able to
+browse inside them.
+
+Below you can see an image of three different file formats, as well as two
+directories.
+
+![Build artifacts browser](img/build_artifacts_browser.png)
+
+---
+
+## Downloading build artifacts
+
+If you need to download the whole archive, there are buttons in various places
+inside GitLab that make that possible.
+
+1. While on the builds page, you can see the download icon for each build's
+   artifacts archive in the right corner
+
+1. While inside a specific build, you are presented with a download button
+   along with the one that browses the archive
+
+1. And finally, when browsing and archive you can see the download button at
+   the top right corner
+
+---
+
+Note that GitLab does not extract the entire artifacts archive to send just a
+single file to the user.
+
+When clicking on a specific file, [GitLab Workhorse] extracts it from the
+archive and the download begins.
+
+This implementation saves space, memory and disk I/O.
+
+[gitlab runner]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner "GitLab Runner repository"
+[reconfigure gitlab]: ../../administration/restart_gitlab.md "How to restart GitLab documentation"
+[restart gitlab]: ../../administration/restart_gitlab.md "How to restart GitLab documentation"
+[gitlab workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse "GitLab Workhorse repository"
diff --git a/doc/ci/build_artifacts/img/build_artifacts_browser.png b/doc/ci/build_artifacts/img/build_artifacts_browser.png
new file mode 100644
index 00000000000..73ed4eeb927
--- /dev/null
+++ b/doc/ci/build_artifacts/img/build_artifacts_browser.png
diff --git a/doc/ci/build_artifacts/img/build_artifacts_browser_button.png b/doc/ci/build_artifacts/img/build_artifacts_browser_button.png
new file mode 100644
index 00000000000..f5d15bc3e7d
--- /dev/null
+++ b/doc/ci/build_artifacts/img/build_artifacts_browser_button.png
diff --git a/doc/ci/languages/php.md b/doc/ci/languages/php.md
index dacb67fa3ff..77f9fae5bb6 100644
--- a/doc/ci/languages/php.md
+++ b/doc/ci/languages/php.md
@@ -12,7 +12,7 @@ configuration from the developer. To overcome this we will be using the
 official [PHP docker image][php-hub] that can be found in Docker Hub.
 
 This will allow us to test PHP projects against different versions of PHP.
-However, not everything is plug 'n' play, you still need to onfigure some
+However, not everything is plug 'n' play, you still need to configure some
 things manually.
 
 As with every build, you need to create a valid `.gitlab-ci.yml` describing the
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index b99ea25a3fe..862cacda586 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -56,7 +56,7 @@ export CI_SERVER_VERSION=""
 ```
 
 ### YAML-defined variables
-**This feature requires GitLab Runner 0.5.0 or higher**
+**This feature requires GitLab Runner 0.5.0 or higher and GitLab CI 7.14 or higher **
 
 GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in build environment.
 The variables are stored in repository and are meant to store non-sensitive project configuration, ie. RAILS_ENV or DATABASE_URL.
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 779b9db6486..4d280297dbb 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -135,10 +135,9 @@ thus allowing to fine tune them.
 ### cache
 
 `cache` is used to specify a list of files and directories which should be
-cached between builds. Caches are stored according to the branch/ref and the
-job name. They are not currently shared between different job names or between
-branches/refs, which means that caching will benefit you if you push subsequent
-commits to an existing feature branch.
+cached between builds.
+
+**By default the caching is enabled per-job and per-branch.**
 
 If `cache` is defined outside the scope of the jobs, it means it is set
 globally and all jobs will use its definition.
@@ -152,6 +151,64 @@ cache:
   - binaries/
 ```
 
+#### cache:key
+
+_**Note:** Introduced in GitLab Runner v1.0.0._
+
+The `key` directive allows you to define the affinity of caching
+between jobs, allowing to have a single cache for all jobs,
+cache per-job, cache per-branch or any other way you deem proper.
+
+This allows you to fine tune caching, allowing you to cache data between
+different jobs or even different branches.
+
+The `cache:key` variable can use any of the [predefined variables](../variables/README.md).
+
+---
+
+**Example configurations**
+
+To enable per-job caching:
+
+```yaml
+cache:
+  key: "$CI_BUILD_NAME"
+  untracked: true
+```
+
+To enable per-branch caching:
+
+```yaml
+cache:
+  key: "$CI_BUILD_REF_NAME"
+  untracked: true
+```
+
+To enable per-job and per-branch caching:
+
+```yaml
+cache:
+  key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME"
+  untracked: true
+```
+
+To enable per-branch and per-stage caching:
+
+```yaml
+cache:
+  key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME"
+  untracked: true
+```
+
+If you use **Windows Batch** to run your shell scripts you need to replace
+`$` with `%`:
+
+```yaml
+cache:
+  key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%"
+  untracked: true
+```
+
 ## Jobs
 
 `.gitlab-ci.yml` allows you to specify an unlimited number of jobs. Each job