1 files changed, 74 insertions, 16 deletions
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 5d35d1da4ee..3dbf1afc7a9 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -56,6 +56,7 @@ There are a few `keywords` that can't be used as job names:
 | types         | optional | Alias for `stages` |
 | before_script | optional | Define commands prepended for each job's script |
 | variables     | optional | Define build variables |
+| cache         | optional | Define list of files that should be cached between subsequent runs |
 
 ### image and services
 This allows to specify a custom Docker image and a list of services that can be used for time of the build.
@@ -110,6 +111,19 @@ These variables can be later used in all executed commands and scripts.
 
 The YAML-defined variables are also set to all created service containers, thus allowing to fine tune them.
 
+### cache
+`cache` is used to specify list of files and directories which should be cached between builds.
+
+**The global setting allows to specify default cached files for all jobs.**
+
+To cache all git untracked files and files in `binaries`:
+```
+cache:
+  untracked: true
+  paths:
+  - binaries/
+```
+
 ## Jobs
 `.gitlab-ci.yml` allows you to specify an unlimited number of jobs.
 Each job has to have a unique `job_name`, which is not one of the keywords mentioned above.
@@ -142,6 +156,7 @@ job_name:
 | allow_failure | optional | Allow build to fail. Failed build doesn't contribute to commit status |
 | when          | optional | Define when to run build. Can be `on_success`, `on_failure` or `always` |
 | artifacts     | optional | Define list build artifacts |
+| cache         | optional | Define list of files that should be cached between subsequent runs |
 
 ### script
 `script` is a shell script which is executed by runner. The shell script is prepended with `before_script`.
@@ -263,31 +278,74 @@ The above script will:
 `artifacts` is used to specify list of files and directories which should be attached to build after success.
 
 1. Send all files in `binaries` and `.config`:
-```
-artifacts:
-  paths:
-  - binaries/
-  - .config
-```
+
+        artifacts:
+          paths:
+          - binaries/
+          - .config
 
 2. Send all git untracked files:
-```
-artifacts:
-  untracked: true
-```
+
+        artifacts:
+          untracked: true
 
 3. Send all git untracked files and files in `binaries`:
-```
-artifacts:
-  untracked: true
-  paths:
-  - binaries/
-```
+
+        artifacts:
+          untracked: true
+          paths:
+          - binaries/
 
 The artifacts will be send after the build success to GitLab and will be accessible in GitLab interface to download.
 
 This feature requires GitLab Runner v0.7.0 or higher.
 
+### cache
+`cache` is used to specify list of files and directories which should be cached between builds.
+
+1. Cache all files in `binaries` and `.config`:
+
+        rspec:
+          script: test
+          cache:
+            paths:
+            - binaries/
+            - .config
+
+2. Cache all git untracked files:
+
+        rspec:
+          script: test
+          cache:
+            untracked: true
+            
+3. Cache all git untracked files and files in `binaries`:
+
+        rspec:
+          script: test
+          cache:
+            untracked: true
+            paths:
+            - binaries/
+
+4. Locally defined cache overwrites globally defined options. This will cache only `binaries/`:
+
+        cache:
+          paths:
+          - my/files
+        
+        rspec:
+          script: test
+          cache:
+            paths:
+            - binaries/
+
+The cache is provided on best effort basis, so don't expect that cache will be present.
+For implementation details please check GitLab Runner.
+
+This feature requires GitLab Runner v0.7.0 or higher.
+
+
 ## Validate the .gitlab-ci.yml
 Each instance of GitLab CI has an embedded debug tool called Lint.
 You can find the link to the Lint in the project's settings page or use short url `/lint`.