5 files changed, 111 insertions, 13 deletions
diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md
index cc059dc4376..61294be599d 100644
--- a/doc/ci/examples/README.md
+++ b/doc/ci/examples/README.md
@@ -4,12 +4,12 @@
 - [Test and deploy a Ruby application to Heroku](test-and-deploy-ruby-application-to-heroku.md)
 - [Test and deploy a Python application to Heroku](test-and-deploy-python-application-to-heroku.md)
 - [Test a Clojure application](test-clojure-application.md)
-- [Using `dpl` as deployment tool](deployment/README.md)
+- [Using `dpl` as deployment tool](../deployment/README.md)
 - Help your favorite programming language and GitLab by sending a merge request
   with a guide for that language.
 
 ## Outside the documentation
 
-- [Blost post about using GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/)
+- [Blog post about using GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/)
 - [Repo's with examples for various languages](https://gitlab.com/groups/gitlab-examples)
 - [The .gitlab-ci.yml file for GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml)
diff --git a/doc/ci/examples/deployment/README.md b/doc/ci/examples/deployment/README.md
new file mode 100644
index 00000000000..7d91ce6710f
--- /dev/null
+++ b/doc/ci/examples/deployment/README.md
@@ -0,0 +1,98 @@
+## Using Dpl as deployment tool
+Dpl (dee-pee-ell) is a deploy tool made for continuous deployment that's developed and used by Travis CI, but can also be used with GitLab CI. 
+
+**We recommend to use Dpl, if you're deploying to any of these of these services: https://github.com/travis-ci/dpl#supported-providers**.
+
+### Requirements
+To use Dpl you need at least Ruby 1.8.7 with ability to install gems.
+
+### Basic usage
+The Dpl can be installed on any machine with:
+```
+gem install dpl
+```
+
+This allows you to test all commands from your shell, rather than having to test it on a CI server.
+
+If you don't have Ruby installed you can do it on Debian-compatible Linux with:
+```
+apt-get update
+apt-get install ruby-dev
+```
+
+The Dpl provides support for vast number of services, including: Heroku, Cloud Foundry, AWS/S3, and more.
+To use it simply define provider and any additional parameters required by the provider.
+
+For example if you want to use it to deploy your application to heroku, you need to specify `heroku` as provider, specify `api-key` and `app`.
+There's more and all possible parameters can be found here: https://github.com/travis-ci/dpl#heroku
+
+```
+staging:
+  type: deploy
+  - gem install dpl
+  - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY
+```
+
+In the above example we use Dpl to deploy `my-app-staging` to Heroku server with api-key stored in `HEROKU_STAGING_API_KEY` secure variable.
+
+To use different provider take a look at long list of [Supported Providers](https://github.com/travis-ci/dpl#supported-providers).
+
+### Using Dpl with Docker
+When you use GitLab Runner you most likely configured it to use your server's shell commands.
+This means that all commands are run in context of local user (ie. gitlab_runner or gitlab_ci_multi_runner).
+It also means that most probably in your Docker container you don't have the Ruby runtime installed.
+You will have to install it:
+```
+staging:
+  type: deploy
+  - apt-get update -yq
+  - apt-get install -y ruby-dev
+  - gem install dpl
+  - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY
+  only:
+  - master
+```
+
+The first line `apt-get update -yq` updates the list of available packages, where second `apt-get install -y ruby-dev` install `Ruby` runtime on system.
+The above example is valid for all Debian-compatible systems.
+
+### Usage in staging and production
+It's pretty common in developer workflow to have staging (development) and production environment.
+If we consider above example: we would like to deploy `master` branch to `staging` and `all tags` to `production` environment.
+The final `.gitlab-ci.yml` for that setup would look like this:
+
+```
+staging:
+  type: deploy
+  - gem install dpl
+  - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY
+  only:
+  - master
+  
+production:
+  type: deploy
+  - gem install dpl
+  - dpl --provider=heroku --app=my-app-production --api-key=$HEROKU_PRODUCTION_API_KEY
+  only:
+  - tags
+```
+
+We created two deploy jobs that are executed on different events:
+1. `staging` is executed for all commits that were pushed to `master` branch,
+2. `production` is executed for all pushed tags.
+
+We also use two secure variables:
+1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app,
+2. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app.
+
+### Storing API keys
+In GitLab CI 7.12 a new feature was introduced: Secure Variables.
+Secure Variables can added by going to `Project > Variables > Add Variable`. 
+**This feature requires `gitlab-runner` with version equal or greater than 0.4.0.**
+The variables that are defined in the project settings are sent along with the build script to the runner.
+The secure variables are stored out of the repository. Never store secrets in your projects' .gitlab-ci.yml.
+It is also important that secret's value is hidden in the build log.
+
+You access added variable by prefixing it's name with `$` (on non-Windows runners) or `%` (for Windows Batch runners):
+1. `$SECRET_VARIABLE` - use it for non-Windows runners
+2. `%SECRET_VARIABLE%` - use it for Windows Batch runners
diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md
index db077927126..26953014502 100644
--- a/doc/ci/examples/php.md
+++ b/doc/ci/examples/php.md
@@ -60,7 +60,7 @@ docker-php-ext-install pdo_mysql
 You might wonder what `docker-php-ext-install` is. In short, it is a script
 provided by the official php docker image that you can use to easilly install
 extensions. For more information read the the documentation at
-<https://hub.docker.com/_/php/>.
+<https://hub.docker.com/r/_/php/>.
 
 Now that we created the script that contains all prerequisites for our build
 environment, let's add it in `.gitlab-ci.yml`:
@@ -92,7 +92,7 @@ Finally, commit your files and push them to GitLab to see your build succeeding
 The final `.gitlab-ci.yml` should look similar to this:
 
 ```yaml
-# Select image from https://hub.docker.com/_/php/
+# Select image from https://hub.docker.com/r/_/php/
 image: php:5.6
 
 before_script:
@@ -278,7 +278,7 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available
 Want to hack on it? Simply fork it, commit and push  your changes. Within a few
 moments the changes will be picked by a public runner and the build will begin.
 
-[php-hub]: https://hub.docker.com/_/php/
+[php-hub]: https://hub.docker.com/r/_/php/
 [phpenv]: https://github.com/phpenv/phpenv
 [phpenv-installation]: https://github.com/phpenv/phpenv#installation
 [php-example-repo]: https://gitlab.com/gitlab-examples/php
diff --git a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md
index a236da53fe9..e4d3970deac 100644
--- a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md
+++ b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md
@@ -8,7 +8,7 @@ This is what the `.gitlab-ci.yml` file looks like for this project:
 ```yaml
 test:
   script:
-  # this configures django application to use attached postgres database that is run on `postgres` host
+  # this configures Django application to use attached postgres database that is run on `postgres` host
   - export DATABASE_URL=postgres://postgres:@postgres:5432/python-test-app
   - apt-get update -qy
   - apt-get install -y python-dev python-pip
@@ -37,7 +37,7 @@ production:
 ```
 
 This project has three jobs:
-1. `test` - used to test rails application,
+1. `test` - used to test Django application,
 2. `staging` - used to automatically deploy staging environment every push to `master` branch
 3. `production` - used to automatically deploy production environmnet for every created tag
 
@@ -61,12 +61,12 @@ gitlab-ci-multi-runner register \
   --non-interactive \
   --url "https://gitlab.com/ci/" \
   --registration-token "PROJECT_REGISTRATION_TOKEN" \
-  --description "python-3.2" \
+  --description "python-3.5" \
   --executor "docker" \
-  --docker-image python:3.2 \
+  --docker-image python:3.5 \
   --docker-postgres latest
 ```
 
-With the command above, you create a runner that uses [python:3.2](https://registry.hub.docker.com/u/library/python/) image and uses [postgres](https://registry.hub.docker.com/u/library/postgres/) database.
+With the command above, you create a runner that uses [python:3.5](https://hub.docker.com/r/_/python/) image and uses [postgres](https://hub.docker.com/r/_/postgres/) database.
 
 To access PostgreSQL database you need to connect to `host: postgres` as user `postgres` without password.
diff --git a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md
index f5645d586ae..08c10d391ea 100644
--- a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md
+++ b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md
@@ -1,5 +1,5 @@
 ## Test and Deploy a ruby application
-This example will guide you how to run tests in your Ruby application and deploy it automatically as Heroku application.
+This example will guide you how to run tests in your Ruby on Rails application and deploy it automatically as Heroku application.
 
 You can checkout the example [source](https://gitlab.com/ayufan/ruby-getting-started) and check [CI status](https://gitlab.com/ayufan/ruby-getting-started/builds?scope=all).
 
@@ -32,7 +32,7 @@ production:
 ```
 
 This project has three jobs:
-1. `test` - used to test rails application,
+1. `test` - used to test Rails application,
 2. `staging` - used to automatically deploy staging environment every push to `master` branch
 3. `production` - used to automatically deploy production environmnet for every created tag
 
@@ -62,6 +62,6 @@ gitlab-ci-multi-runner register \
   --docker-postgres latest
 ```
 
-With the command above, you create a runner that uses [ruby:2.2](https://registry.hub.docker.com/u/library/ruby/) image and uses [postgres](https://registry.hub.docker.com/u/library/postgres/) database.
+With the command above, you create a runner that uses [ruby:2.2](https://hub.docker.com/r/_/ruby/) image and uses [postgres](https://hub.docker.com/r/_/postgres/) database.
 
 To access PostgreSQL database you need to connect to `host: postgres` as user `postgres` without password.