3 files changed, 72 insertions, 1 deletions
diff --git a/doc/docker/using_docker_images.md b/doc/docker/using_docker_images.md
index a88bb62..9170783 100644
--- a/doc/docker/using_docker_images.md
+++ b/doc/docker/using_docker_images.md
@@ -66,6 +66,39 @@ Alias hostname for the service is made from the image name:
 1. Everything after `:` is stripped,
 2. '/' is replaced to `_`.
 
+### Configuring services
+Many services accepts environment variables, thus allowing to change database name or set account name.
+
+GitLab Runner with version equal or greater than 0.5.0 passes all YAML-defined variables to created service containers.
+
+1. To configure database name for [postgres](https://registry.hub.docker.com/u/library/postgres/) service,
+you need to set POSTGRES_DB.
+
+    ```yaml
+    services:
+    - postgres
+    
+    variables:
+      POSTGRES_DB: gitlab
+    ```
+
+1. To use [mysql](https://registry.hub.docker.com/u/library/mysql/) service with empty password for time of build, 
+you need to set MYSQL_ALLOW_EMPTY_PASSWORD.
+
+    ```yaml
+    services:
+    - mysql
+    
+    variables:
+      MYSQL_ALLOW_EMPTY_PASSWORD: yes
+    ```
+
+For more possible configuration variables check the 
+https://registry.hub.docker.com/u/library/mysql/ or https://registry.hub.docker.com/u/library/postgres/
+or README page for any other Docker image.
+
+**Note: All variables will passed to all service containers. It's not designed to distinguish which variable should go where.**
+
 ### Overwrite image and services
 It's possible to overwrite `docker-image` and specify services from `.gitlab-ci.yml`.
 If you add to your YAML the `image` and the `services` these parameters
diff --git a/doc/variables/README.md b/doc/variables/README.md
index d61474a..cef5680 100644
--- a/doc/variables/README.md
+++ b/doc/variables/README.md
@@ -1,6 +1,11 @@
 ## Variables
 When receiving a build from GitLab CI, the runner prepares the build environment.
-It starts by setting a list of **predefined variables** (Environment Variables) and a list of **user-defined variables** (Secure Variables)
+It starts by setting a list of **predefined variables** (Environment Variables) and a list of **user-defined variables**
+
+The precedence of variables override:
+1. Predefined variables
+2. YAML-defined variables
+3. Secure variables
 
 ### Predefined variables (Environment Variables)
 
@@ -36,6 +41,23 @@ export CI_SERVER_REVISION=""
 export CI_SERVER_VERSION=""
 ```
 
+### YAML-defined variables
+**This feature requires `gitlab-runner` with version equal or greater than 0.5.0.**
+
+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.
+
+```yaml
+variables:
+  DATABASE_URL: "postgres://postgres@postgres/my_database"
+```
+
+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.
+
+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` with version equal or greater than 0.4.0.**
 
diff --git a/doc/yaml/README.md b/doc/yaml/README.md
index 301144a..4caecca 100644
--- a/doc/yaml/README.md
+++ b/doc/yaml/README.md
@@ -55,6 +55,7 @@ There are a few `keywords` that can't be used as job names:
 | stages        | optional | Define build stages |
 | types         | optional | Alias for `stages` |
 | before_script | optional | Define commands prepended for each job's script |
+| variables     | optional | Define build variables |
 
 ### 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.
@@ -94,6 +95,21 @@ There are also two edge cases worth mentioning:
 ### types
 Alias for [stages](#stages).
 
+### variables
+**This feature requires `gitlab-runner` with version equal or greater than 0.5.0.**
+
+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.
+
+```yaml
+variables:
+  DATABASE_URL: "postgres://postgres@postgres/my_database"
+```
+
+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.
+
 ## 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.