Add documentation for job-level build variables

2 files changed, 24 insertions, 1 deletions

diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index b0e53cbc261..35dac4c9337 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -70,12 +70,14 @@ 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.
 
+Variables can be defined on a global level, but also on a job level.
+
 More information about Docker integration can be found in [Using Docker Images](../docker/using_docker_images.md).
 
 ### User-defined variables (Secure Variables)
 **This feature requires GitLab Runner 0.4.0 or higher**
 
-GitLab CI allows you to define per-project **Secure Variables** that are set in build environment. 
+GitLab CI allows you to define per-project **Secure Variables** that are set in build environment.
 The secure variables are stored out of the repository (the `.gitlab-ci.yml`).
 The variables are securely passed to GitLab Runner and are available in build environment.
 It's desired method to use them for storing passwords, secret keys or whatever you want.
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index abb6e97e5e6..ea7d6dfa465 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -23,6 +23,7 @@ If you want a quick introduction to GitLab CI, follow our
 - [Jobs](#jobs)
     - [script](#script)
     - [stage](#stage)
+    - [job variables](#job-variables)
     - [only and except](#only-and-except)
     - [tags](#tags)
     - [when](#when)
@@ -174,6 +175,8 @@ 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.
 
+Variables can be also defined on [job level](#job-variables).
+
 ### cache
 
 >**Note:**
@@ -324,6 +327,7 @@ job_name:
 | services      | no | Use docker services, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) |
 | stage         | no | Defines a build stage (default: `test`) |
 | type          | no | Alias for `stage` |
+| variables     | no | Define build variables on a job level |
 | only          | no | Defines a list of git refs for which build is created |
 | except        | no | Defines a list of git refs for which build is not created |
 | tags          | no | Defines a list of tags which are used to select Runner |
@@ -414,6 +418,23 @@ job:
 The above example will run `job` for all branches on `gitlab-org/gitlab-ce`,
 except master.
 
+### job variables
+
+It is possible to define build variables using a `variables` keyword on a job
+level. It works basically the same way like it's global-level equivalent but
+allows you to define a job specific build variables.
+
+When `variables` keyword is used on a job level, it can override global YAML
+build variables and predefined variables.
+
+Build variables priority is defined as follows:
+
+* predefined variables
+* global YAML variables
+* job YAML variables
+* secure variables
+* trigger variables
+
 ### tags
 
 `tags` is used to select specific Runners from the list of all Runners that are