Added description of artifacts:when

1 files changed, 27 insertions, 0 deletions

diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index a3481f58c6c..39fad549a04 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -30,6 +30,7 @@ If you want a quick introduction to GitLab CI, follow our
     - [when](#when)
     - [artifacts](#artifacts)
         - [artifacts:name](#artifacts-name)
+        - [artifacts:when](#artifacts-when)
     - [dependencies](#dependencies)
     - [before_script and after_script](#before_script-and-after_script)
 - [Hidden jobs](#hidden-jobs)
@@ -651,6 +652,32 @@ job:
     untracked: true
 ```
 
+#### artifacts:when
+
+>**Note:**
+Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
+
+`artifacts:when` is used to upload artifacts on build failure or despite the
+failure.
+
+`artifacts:when` can be set to one of the following values:
+
+1. `on_success` - upload artifacts only when build succeeds. This is the default
+1. `on_failure` - upload artifacts only when build fails
+1. `always` - upload artifacts despite the build status
+
+---
+
+**Example configurations**
+
+To upload artifacts only when build fails
+
+```yaml
+job:
+  artifacts:
+    when: on_failure
+```
+
 ### dependencies
 
 >**Note:**