Merge branch 'master' into ci-scala-example

22 files changed, 563 insertions, 256 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index 4abc45bf9bb..ef72df97ce6 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -14,5 +14,5 @@
 - [Trigger builds through the API](triggers/README.md)
 - [Build artifacts](build_artifacts/README.md)
 - [User permissions](permissions/README.md)
-- [API](api/README.md)
+- [API](../../api/ci/README.md)
 - [CI services (linked docker containers)](services/README.md)
diff --git a/doc/ci/api/README.md b/doc/ci/api/README.md
index aea808007fc..4ca8d92d7cc 100644
--- a/doc/ci/api/README.md
+++ b/doc/ci/api/README.md
@@ -1,22 +1,3 @@
 # GitLab CI API
 
-## Purpose
-
-Main purpose of GitLab CI API is to provide necessary data and context for
-GitLab CI Runners.
-
-For consumer API take a look at this [documentation](../../api/README.md) where
-you will find all relevant information.
-
-## API Prefix
-
-Current CI API prefix is `/ci/api/v1`.
-
-You need to prepend this prefix to all examples in this documentation, like:
-
-    GET /ci/api/v1/builds/:id/artifacts
-
-## Resources
-
-- [Builds](builds.md)
-- [Runners](runners.md)
+This document was moved to a [new location](../../api/ci/README.md).
diff --git a/doc/ci/api/builds.md b/doc/ci/api/builds.md
index d100e261178..f5bd3181c02 100644
--- a/doc/ci/api/builds.md
+++ b/doc/ci/api/builds.md
@@ -1,73 +1,3 @@
 # Builds API
 
-API used by runners to receive and update builds.
-
-_**Note:** This API is intended to be used only by Runners as their own
-communication channel. For the consumer API see the
-[Builds API](../../api/builds.md)._
-
-## Authentication
-
-This API uses two types of authentication:
-
-1.   Unique runner's token
-
-     Token assigned to runner after it has been registered.
-
-2.   Using build authorization token
-
-     This is project's CI token that can be found in Continuous Integration
-     project settings.
-
-     Build authorization token can be passed as a parameter or a value of
-     `BUILD-TOKEN` header. This method are interchangeable.
-
-## Builds
-
-### Runs oldest pending build by runner
-
-    POST /ci/api/v1/builds/register
-
-Parameters:
-
-  * `token` (required) - Unique runner token
-
-
-### Update details of an existing build
-
-    PUT /ci/api/v1/builds/:id
-
-Parameters:
-
-  * `id` (required) - The ID of a project
-  * `token` (required) - Unique runner token
-  * `state` (optional) - The state of a build
-  * `trace` (optional) - The trace of a build
-
-### Upload artifacts to build
-
-    POST /ci/api/v1/builds/:id/artifacts
-
-Parameters:
-
-  * `id` (required) - The ID of a build
-  * `token` (required) - The build authorization token
-  * `file` (required) - Artifacts file
-
-### Download the artifacts file from build
-
-    GET /ci/api/v1/builds/:id/artifacts
-
-Parameters:
-
-  * `id` (required) - The ID of a build
-  * `token` (required) - The build authorization token
-
-### Remove the artifacts file from build
-
-    DELETE /ci/api/v1/builds/:id/artifacts
-
-Parameters:
-
-  * ` id` (required) - The ID of a build
-  * `token` (required) - The build authorization token
+This document was moved to a [new location](../../api/ci/builds.md).
diff --git a/doc/ci/api/runners.md b/doc/ci/api/runners.md
index 2f01da4bd76..b14ea99db76 100644
--- a/doc/ci/api/runners.md
+++ b/doc/ci/api/runners.md
@@ -1,46 +1,3 @@
 # Runners API
 
-API used by runners to register and delete themselves.
-
-_**Note:** This API is intended to be used only by Runners as their own
-communication channel. For the consumer API see the
-[new Runners API](../../api/runners.md)._
-
-## Authentication
-
-This API uses two types of authentication:
-
-1.   Unique runner's token
-
-     Token assigned to runner after it has been registered.
-
-2.   Using runners' registration token
-
-     This is a token that can be found in project's settings.
-     It can be also found in Admin area » Runners settings.
-
-     There are two types of tokens you can pass - shared runner registration
-     token or project specific registration token.
-
-## Runners
-
-### Register a new runner
-
-Used to make GitLab CI aware of available runners.
-
-    POST /ci/api/v1/runners/register
-
-Parameters:
-
-  * `token` (required) - Registration token
-
-
-### Delete a runner
-
-Used to remove runner.
-
-    DELETE /ci/api/v1/runners/delete
-
-Parameters:
-
-  * `token` (required) - Unique runner token
+This document was moved to a [new location](../../api/ci/runners.md).
diff --git a/doc/ci/build_artifacts/README.md b/doc/ci/build_artifacts/README.md
index 71db5aa5dc8..9553bb11e9d 100644
--- a/doc/ci/build_artifacts/README.md
+++ b/doc/ci/build_artifacts/README.md
@@ -1,7 +1,10 @@
 # Introduction to build artifacts
 
 Artifacts is a list of files and directories which are attached to a build
-after it completes successfully.
+after it completes successfully.  This feature is enabled by default in all GitLab installations.
+
+_If you are searching for ways to use artifacts, jump to
+[Defining artifacts in `.gitlab-ci.yml`](#defining-artifacts-in-gitlab-ciyml)._
 
 Since GitLab 8.2 and [GitLab Runner] 0.7.0, build artifacts that are created by
 GitLab Runner are uploaded to GitLab and are downloadable as a single archive
@@ -16,13 +19,9 @@ The artifacts browser will be available only for new artifacts that are sent
 to GitLab using GitLab Runner version 1.0 and up. It will not be possible to
 browse old artifacts already uploaded to GitLab.
 
-## Enabling build artifacts
-
-_If you are searching for ways to use artifacts, jump to
-[Defining artifacts in `.gitlab-ci.yml`](#defining-artifacts-in-gitlab-ciyml)._
+## Disabling build artifacts
 
-The artifacts feature is enabled by default in all GitLab installations.
-To disable it site-wide, follow the steps below.
+To disable artifacts site-wide, follow the steps below.
 
 ---
 
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md
index 4b1788a9af0..7f83f846454 100644
--- a/doc/ci/docker/using_docker_build.md
+++ b/doc/ci/docker/using_docker_build.md
@@ -4,14 +4,14 @@ GitLab CI allows you to use Docker Engine to build and test docker-based project
 
 **This also allows to you to use `docker-compose` and other docker-enabled tools.**
 
-This is one of new trends in Continuous Integration/Deployment to:
+One of the new trends in Continuous Integration/Deployment is to:
 
-1. create application image,
-1. run test against created image,
-1. push image to remote registry, 
-1. deploy server from pushed image
+1. create an application image,
+1. run tests against the created image,
+1. push image to a remote registry, and
+1. deploy to a server from the pushed image.
 
-It's also useful in case when your application already has the `Dockerfile` that can be used to create and test image:
+It's also useful when your application already has the `Dockerfile` that can be used to create and test an image:
 ```bash
 $ docker build -t my-image dockerfiles/
 $ docker run my-docker-image /script/to/run/tests
@@ -19,49 +19,50 @@ $ docker tag my-image my-registry:5000/my-image
 $ docker push my-registry:5000/my-image
 ```
 
-However, this requires special configuration of GitLab Runner to enable `docker` support during build.
-**This requires running GitLab Runner in privileged mode which can be harmful when untrusted code is run.**
+This requires special configuration of GitLab Runner to enable `docker` support during builds.
 
-There are two methods to enable the use of `docker build` and `docker run` during build.
+## Runner Configuration
 
-## 1. Use shell executor
+There are three methods to enable the use of `docker build` and `docker run` during builds; each with their own tradeoffs.
+
+### Use shell executor
 
 The simplest approach is to install GitLab Runner in `shell` execution mode.
-GitLab Runner then executes build scripts as `gitlab-runner` user.
+GitLab Runner then executes build scripts as the `gitlab-runner` user.
 
 1. Install [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/#installation).
 
 1. During GitLab Runner installation select `shell` as method of executing build scripts or use command:
 
     ```bash
-    $ sudo gitlab-runner register -n \
+    $ sudo gitlab-ci-multi-runner register -n \
       --url https://gitlab.com/ci \
-      --token RUNNER_TOKEN \
+      --registration-token REGISTRATION_TOKEN \
       --executor shell
       --description "My Runner"
     ```
 
-2. Install Docker on server.
+2. Install Docker Engine on server.
 
-    For more information how to install Docker on different systems checkout the [Supported installations](https://docs.docker.com/installation/).
+    For more information how to install Docker Engine on different systems checkout the [Supported installations](https://docs.docker.com/engine/installation/).
 
 3. Add `gitlab-runner` user to `docker` group:
-    
+
     ```bash
     $ sudo usermod -aG docker gitlab-runner
     ```
 
 4. Verify that `gitlab-runner` has access to Docker:
-  
+
     ```bash
     $ sudo -u gitlab-runner -H docker info
     ```
-    
+
     You can now verify that everything works by adding `docker info` to `.gitlab-ci.yml`:
     ```yaml
     before_script:
       - docker info
-    
+
     build_image:
       script:
         - docker build -t my-docker-image .
@@ -70,42 +71,246 @@ GitLab Runner then executes build scripts as `gitlab-runner` user.
 
 5. You can now use `docker` command and install `docker-compose` if needed.
 
-6. However, by adding `gitlab-runner` to `docker` group you are effectively granting `gitlab-runner` full root permissions.
-For more information please checkout [On Docker security: `docker` group considered harmful](https://www.andreas-jung.com/contents/on-docker-security-docker-group-considered-harmful).
+> **Note:**
+* By adding `gitlab-runner` to the `docker` group you are effectively granting `gitlab-runner` full root permissions.
+For more information please read [On Docker security: `docker` group considered harmful](https://www.andreas-jung.com/contents/on-docker-security-docker-group-considered-harmful).
 
-## 2. Use docker-in-docker executor
+### Use docker-in-docker executor
 
-Second approach is to use special Docker image with all tools installed (`docker` and `docker-compose`) and run build script in context of that image in privileged mode.
-In order to do that follow the steps:
+The second approach is to use the special docker-in-docker (dind)
+[Docker image](https://hub.docker.com/_/docker/) with all tools installed
+(`docker` and `docker-compose`) and run the build script in context of that
+image in privileged mode.
+
+In order to do that, follow the steps:
 
 1. Install [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/#installation).
 
-1. Register GitLab Runner from command line to use `docker` and `privileged` mode:
+1. Register GitLab Runner from the command line to use `docker` and `privileged`
+   mode:
 
     ```bash
-    $ sudo gitlab-runner register -n \
+    sudo gitlab-ci-multi-runner register -n \
       --url https://gitlab.com/ci \
-      --token RUNNER_TOKEN \
+      --registration-token REGISTRATION_TOKEN \
       --executor docker \
       --description "My Docker Runner" \
-      --docker-image "gitlab/dind:latest" \
+      --docker-image "docker:latest" \
       --docker-privileged
     ```
-  
-    The above command will register new Runner to use special [gitlab/dind](https://registry.hub.docker.com/u/gitlab/dind/) image which is provided by GitLab Inc.
-    The image at the start runs Docker daemon in [docker-in-docker](https://blog.docker.com/2013/09/docker-can-now-run-within-docker/) mode.
 
-1. You can now use `docker` from build script:
-    
+    The above command will register a new Runner to use the special
+    `docker:latest` image which is provided by Docker. **Notice that it's using
+    the `privileged` mode to start the build and service containers.** If you
+    want to use [docker-in-docker] mode, you always have to use `privileged = true`
+    in your Docker containers.
+
+    The above command will create a `config.toml` entry similar to this:
+
+    ```
+    [[runners]]
+      url = "https://gitlab.com/ci"
+      token = TOKEN
+      executor = "docker"
+      [runners.docker]
+        tls_verify = false
+        image = "docker:latest"
+        privileged = true
+        disable_cache = false
+        volumes = ["/cache"]
+      [runners.cache]
+        Insecure = false
+    ```
+
+1. You can now use `docker` in the build script (note the inclusion of the `docker:dind` service):
+
     ```yaml
+    image: docker:latest
+
+    services:
+    - docker:dind
+
     before_script:
-      - docker info
-    
-    build_image:
+    - docker info
+
+    build:
+      stage: build
       script:
-        - docker build -t my-docker-image .
-        - docker run my-docker-image /script/to/run/tests
+      - docker build -t my-docker-image .
+      - docker run my-docker-image /script/to/run/tests
+    ```
+
+Docker-in-Docker works well, and is the recommended configuration, but it is not without its own challenges:
+* By enabling `--docker-privileged`, you are effectively disabling all of
+the security mechanisms of containers and exposing your host to privilege
+escalation which can lead to container breakout. For more information, check out the official Docker documentation on
+[Runtime privilege and Linux capabilities][docker-cap].
+* Using docker-in-docker, each build is in a clean environment without the past
+history. Concurrent builds work fine because every build gets it's own instance of docker engine so they won't conflict with each other. But this also means builds can be slower because there's no caching of layers.
+* By default, `docker:dind` uses `--storage-driver vfs` which is the slowest form
+offered.
+
+An example project using this approach can be found here: https://gitlab.com/gitlab-examples/docker.
+
+### Use Docker socket binding
+
+The third approach is to bind-mount `/var/run/docker.sock` into the container so that docker is available in the context of that image.
+
+In order to do that, follow the steps:
+
+1. Install [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/#installation).
+
+1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`:
+
+    ```bash
+    sudo gitlab-ci-multi-runner register -n \
+      --url https://gitlab.com/ci \
+      --registration-token REGISTRATION_TOKEN \
+      --executor docker \
+      --description "My Docker Runner" \
+      --docker-image "docker:latest" \
+      --docker-volumes /var/run/docker.sock:/var/run/docker.sock
     ```
 
-1. However, by enabling `--docker-privileged` you are effectively disables all security mechanisms of containers and exposing your host to privilege escalation which can lead to container breakout.
-For more information, check out [Runtime privilege](https://docs.docker.com/reference/run/#runtime-privilege-linux-capabilities-and-lxc-configuration).
\ No newline at end of file
+    The above command will register a new Runner to use the special
+    `docker:latest` image which is provided by Docker. **Notice that it's using
+    the Docker daemon of the Runner itself, and any containers spawned by docker commands will be siblings of the Runner rather than children of the runner.** This may have complications and limitations that are unsuitable for your workflow.
+
+    The above command will create a `config.toml` entry similar to this:
+
+    ```
+    [[runners]]
+      url = "https://gitlab.com/ci"
+      token = REGISTRATION_TOKEN
+      executor = "docker"
+      [runners.docker]
+        tls_verify = false
+        image = "docker:latest"
+        privileged = false
+        disable_cache = false
+        volumes = ["/var/run/docker.sock", "/cache"]
+      [runners.cache]
+        Insecure = false
+    ```
+
+1. You can now use `docker` in the build script (note that you don't need to include the `docker:dind` service as when using the Docker in Docker executor):
+
+    ```yaml
+    image: docker:latest
+
+    before_script:
+    - docker info
+
+    build:
+      stage: build
+      script:
+      - docker build -t my-docker-image .
+      - docker run my-docker-image /script/to/run/tests
+    ```
+
+While the above method avoids using Docker in privileged mode, you should be aware of the following implications:
+* By sharing the docker daemon, you are effectively disabling all
+the security mechanisms of containers and exposing your host to privilege
+escalation which can lead to container breakout. For example, if a project
+ran `docker rm -f $(docker ps -a -q)` it would remove the GitLab Runner
+containers.
+* Concurrent builds may not work; if your tests
+create containers with specific names, they may conflict with each other.
+* Sharing files and directories from the source repo into containers may not
+work as expected since volume mounting is done in the context of the host
+machine, not the build container.
+e.g. `docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests`
+
+## Using the GitLab Container Registry
+
+> **Note:**
+This feature requires GitLab 8.8 and GitLab Runner 1.2.
+
+Once you've built a Docker image, you can push it up to the built-in [GitLab Container Registry](../../container_registry/README.md). For example, if you're using
+docker-in-docker on your runners, this is how your `.gitlab-ci.yml` could look:
+
+
+```yaml
+ build:
+   image: docker:latest
+   services:
+   - docker:dind
+   stage: build
+   script:
+     - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.example.com
+     - docker build -t registry.example.com/group/project:latest .
+     - docker push registry.example.com/group/project:latest
+```
+
+You have to use the credentials of the special `gitlab-ci-token` user with its
+password stored in `$CI_BUILD_TOKEN` in order to push to the Registry connected
+to your project. This allows you to automate building and deployment of your
+Docker images.
+
+Here's a more elaborate example that splits up the tasks into 4 pipeline stages,
+including two tests that run in parallel. The build is stored in the container
+registry and used by subsequent stages, downloading the image
+when needed. Changes to `master` also get tagged as `latest` and deployed using
+an application-specific deploy script:
+
+```yaml
+image: docker:latest
+services:
+- docker:dind
+
+stages:
+- build
+- test
+- release
+- deploy
+
+variables:
+  CONTAINER_TEST_IMAGE: registry.example.com/my-group/my-project:$CI_BUILD_REF_NAME
+  CONTAINER_RELEASE_IMAGE: registry.example.com/my-group/my-project:latest
+
+before_script:
+  - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.example.com
+
+build:
+  stage: build
+  script:
+    - docker build --pull -t $CONTAINER_TEST_IMAGE .
+    - docker push $CONTAINER_TEST_IMAGE
+
+test1:
+  stage: test
+  script:
+    - docker pull $CONTAINER_TEST_IMAGE
+    - docker run $CONTAINER_TEST_IMAGE /script/to/run/tests
+
+test2:
+  stage: test
+  script:
+    - docker pull $CONTAINER_TEST_IMAGE
+    - docker run $CONTAINER_TEST_IMAGE /script/to/run/another/test
+
+release-image:
+  stage: release
+  script:
+    - docker pull $CONTAINER_TEST_IMAGE
+    - docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE
+    - docker push $CONTAINER_RELEASE_IMAGE
+  only:
+    - master
+
+deploy:
+  stage: deploy
+  script:
+    - ./deploy.sh
+  only:
+    - master
+```
+
+Some things you should be aware of when using the Container Registry:
+* You must log in to the container registry before running commands. Putting this in `before_script` will run it before each build job.
+* Using `docker build --pull` makes sure that Docker fetches any changes to base images before building just in case your cache is stale. It takes slightly longer, but means you don’t get stuck without security patches to base images.
+* Doing an explicit `docker pull` before each `docker run` makes sure to fetch the latest image that was just built. This is especially important if you are using multiple runners that cache images locally. Using the git SHA in your image tag makes this less necessary since each build will be unique and you shouldn't ever have a stale image, but it's still possible if you re-build a given commit after a dependency has changed.
+* You don't want to build directly to `latest` in case there are multiple builds happening simultaneously.
+
+[docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/
+[docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities
diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md
index bd748f1b986..a849905ac6b 100644
--- a/doc/ci/docker/using_docker_images.md
+++ b/doc/ci/docker/using_docker_images.md
@@ -23,7 +23,7 @@ To use GitLab Runner with docker you need to register a new runner to use the
 `docker` executor:
 
 ```bash
-gitlab-runner register \
+gitlab-ci-multi-runner register \
   --url "https://gitlab.com/" \
   --registration-token "PROJECT_REGISTRATION_TOKEN" \
   --description "docker-ruby-2.1" \
@@ -64,7 +64,7 @@ You can see some widely used services examples in the relevant documentation of
 ### How is service linked to the build
 
 To better understand how the container linking works, read
-[Linking containers together](https://docs.docker.com/userguide/dockerlinks/).
+[Linking containers together][linking-containers].
 
 To summarize, if you add `mysql` as service to your application, the image will
 then be used to create a container that is linked to the build container.
@@ -239,8 +239,8 @@ is specific to your project.
 Then create some service containers:
 
 ```
-docker run -d -n service-mysql mysql:latest
-docker run -d -n service-postgres postgres:latest
+docker run -d --name service-mysql mysql:latest
+docker run -d --name service-postgres postgres:latest
 ```
 
 This will create two service containers, named `service-mysql` and
@@ -273,7 +273,7 @@ creation.
 [Docker Fundamentals]: https://docs.docker.com/engine/understanding-docker/
 [hub]: https://hub.docker.com/
 [linking-containers]: https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/
-[tutum/wordpress]: https://registry.hub.docker.com/u/tutum/wordpress/
-[postgres-hub]: https://registry.hub.docker.com/u/library/postgres/
-[mysql-hub]: https://registry.hub.docker.com/u/library/mysql/
+[tutum/wordpress]: https://hub.docker.com/r/tutum/wordpress/
+[postgres-hub]: https://hub.docker.com/r/_/postgres/
+[mysql-hub]: https://hub.docker.com/r/_/mysql/
 [runner-priv-reg]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/blob/master/docs/configuration/advanced-configuration.md#using-a-private-docker-registry
diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md
index 20eeaad3fa3..27bc21c2922 100644
--- a/doc/ci/examples/README.md
+++ b/doc/ci/examples/README.md
@@ -11,6 +11,6 @@
 
 ## 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/deployment/README.md b/doc/ci/examples/deployment/README.md
index 7d91ce6710f..7d91ce6710f 100644
--- a/doc/ci/deployment/README.md
+++ b/doc/ci/examples/deployment/README.md
diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md
index aeadd6a448e..17e1c64bb8a 100644
--- a/doc/ci/examples/php.md
+++ b/doc/ci/examples/php.md
@@ -40,7 +40,7 @@ repository with the following content:
 #!/bin/bash
 
 # We need to install dependencies only for Docker
-[[ ! -e /.dockerinit ]] && exit 0
+[[ ! -e /.dockerenv ]] && [[ ! -e /.dockerinit ]] && exit 0
 
 set -xe
 
@@ -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:
@@ -263,10 +263,10 @@ terminal execute:
 
 ```bash
 # Check using docker executor
-gitlab-runner exec docker test:app
+gitlab-ci-multi-runner exec docker test:app
 
 # Check using shell executor
-gitlab-runner exec shell test:app
+gitlab-ci-multi-runner exec shell test:app
 ```
 
 ## Example project
@@ -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.
diff --git a/doc/ci/examples/test-scala-application.md b/doc/ci/examples/test-scala-application.md
index 58947f0f9f4..7412fdbbc78 100644
--- a/doc/ci/examples/test-scala-application.md
+++ b/doc/ci/examples/test-scala-application.md
@@ -1,15 +1,21 @@
 ## Test a Scala application
 
-This example demonstrates the integration of Gitlab CI with Scala applications using SBT. Checkout the example [project](https://gitlab.com/gitlab-examples/scala-sbt) and [build status](https://gitlab.com/gitlab-examples/scala-sbt/builds).
+This example demonstrates the integration of Gitlab CI with Scala
+applications using SBT. Checkout the example
+[project](https://gitlab.com/gitlab-examples/scala-sbt) and
+[build status](https://gitlab.com/gitlab-examples/scala-sbt/builds).
 
 ### Add `.gitlab-ci.yml` file to project
 
-The following `.gitlab-ci.yml` should be added in the root of your repository to trigger CI:
+The following `.gitlab-ci.yml` should be added in the root of your
+repository to trigger CI:
 
-```yaml
+``` yaml
 image: java:8
 
 before_script:
+  - apt-get update -y
+  - apt-get install apt-transport-https -y
   # Install SBT
   - echo "deb http://dl.bintray.com/sbt/debian /" | tee -a /etc/apt/sources.list.d/sbt.list
   - apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 642AC823
@@ -22,9 +28,20 @@ test:
     - sbt clean coverage test coverageReport
 ```
 
-The `before_script` installs [SBT](http://www.scala-sbt.org/) and displays the version that is being used. The `test` stage executes SBT to compile and test the project. [scoverage](https://github.com/scoverage/sbt-scoverage) is used as a SBT plugin to measure test coverage.
+The `before_script` installs [SBT](http://www.scala-sbt.org/) and
+displays the version that is being used. The `test` stage executes SBT
+to compile and test the project.
+[scoverage](https://github.com/scoverage/sbt-scoverage) is used as an SBT
+plugin to measure test coverage.
 
-You can use other versions of Scala and SBT by defining them in `build.sbt`.
+You can use other versions of Scala and SBT by defining them in
+`build.sbt`.
 
 ### Display test coverage in build
-Add the `Coverage was \[\d+.\d+\%\]` regular expression in the `Continuous Integration > Test coverage parsing` project setting to retrieve the test coverage rate from the build trace and have it displayed with your builds.
+
+Add the `Coverage was \[\d+.\d+\%\]` regular expression in the
+**Settings > Edit Project > Test coverage parsing** project setting to
+retrieve the test coverage rate from the build trace and have it
+displayed with your builds.
+
+**Builds** must be enabled for this option to appear.
diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md
index 9aba4326e11..386b8e29fcf 100644
--- a/doc/ci/quick_start/README.md
+++ b/doc/ci/quick_start/README.md
@@ -13,7 +13,7 @@ GitLab offers a [continuous integration][ci] service. If you
 and configure your GitLab project to use a [Runner], then each merge request or
 push triggers a build.
 
-The `.gitlab-ci.yml` file tells the GitLab runner what do to. By default it
+The `.gitlab-ci.yml` file tells the GitLab runner what to do. By default it
 runs three [stages]: `build`, `test`, and `deploy`.
 
 If everything runs OK (no non-zero return values), you'll get a nice green
@@ -212,8 +212,8 @@ If you want to receive e-mail notifications about the result status of the
 builds, you should explicitly enable the **Builds Emails** service under your
 project's settings.
 
-For more information read the [Builds emails service documentation]
-(../../project_services/builds_emails.md).
+For more information read the
+[Builds emails service documentation](../../project_services/builds_emails.md).
 
 ## Builds badge
 
diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md
index 295d953db11..400784da617 100644
--- a/doc/ci/runners/README.md
+++ b/doc/ci/runners/README.md
@@ -7,6 +7,10 @@ through the coordinator API of GitLab CI.
 A runner can be specific to a certain project or serve any project
 in GitLab CI. A runner that serves all projects is called a shared runner.
 
+Ideally, GitLab Runner should not be installed on the same machine as GitLab.
+Read the [requirements documentation](../../install/requirements.md#gitlab-runner)
+for more information.
+
 ## Shared vs. Specific Runners
 
 A runner that is specific only runs for the specified project. A shared runner
@@ -19,7 +23,7 @@ many projects, you can have a single or a small number of runners that handle
 multiple projects. This makes it easier to maintain and update runners.
 
 **Specific runners** are useful for jobs that have special requirements or for
-projects with a very demand. If a job has certain requirements, you can set
+projects with a specific demand. If a job has certain requirements, you can set
 up the specific runner with this in mind, while not having to do this for all
 runners. For example, if you want to deploy a certain project, you can setup
 a specific runner to have the right credentials for this.
@@ -59,10 +63,10 @@ instance.
 Now simply register the runner as any runner:
 
 ```
-sudo gitlab-runner register
+sudo gitlab-ci-multi-runner register
 ```
 
-Shared runners are enabled by default as of GitLab 8.2, but can be disabled with the 
+Shared runners are enabled by default as of GitLab 8.2, but can be disabled with the
 `DISABLE SHARED RUNNERS` button. Previous versions of GitLab defaulted shared runners to
 disabled.
 
@@ -89,7 +93,7 @@ setup a specific runner for this project.
 To register the runner, run the command below and follow instructions:
 
 ```
-sudo gitlab-runner register
+sudo gitlab-ci-multi-runner register
 ```
 
 ###  Making an existing Shared Runner Specific
@@ -121,7 +125,13 @@ shared runners will only run the jobs they are equipped to run.
 For instance, at GitLab we have runners tagged with "rails" if they contain
 the appropriate dependencies to run Rails test suites.
 
-### Be Careful with Sensitive Information
+### Prevent runner with tags from picking jobs without tags
+
+You can configure a runner to prevent it from picking jobs with tags when
+the runnner does not have tags assigned. This setting is available on each
+runner in *Project Settings* > *Runners*.
+
+### Be careful with sensitive information
 
 If you can run a build on a runner, you can get access to any code it runs
 and get the token of the runner. With shared runners, this means that anyone
@@ -140,7 +150,7 @@ to it. This means that if you have shared runners setup for a project and
 someone forks that project, the shared runners will also serve jobs of this
 project.
 
-# Attack vectors in runners
+## Attack vectors in Runners
 
 Mentioned briefly earlier, but the following things of runners can be exploited.
 We're always looking for contributions that can mitigate these [Security Considerations](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/blob/master/docs/security/index.md).
diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md
index c66d77122b2..aaf3aa77837 100644
--- a/doc/ci/services/mysql.md
+++ b/doc/ci/services/mysql.md
@@ -16,7 +16,7 @@ services:
   - mysql:latest
 
 variables:
-  # Configure mysql environment variables (https://hub.docker.com/_/mysql/)
+  # Configure mysql environment variables (https://hub.docker.com/r/_/mysql/)
   MYSQL_DATABASE: el_duderino
   MYSQL_ROOT_PASSWORD: mysql_strong_password
 ```
@@ -114,5 +114,5 @@ available [shared runners](../runners/README.md).
 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.
 
-[hub-mysql]: https://hub.docker.com/_/mysql/
+[hub-mysql]: https://hub.docker.com/r/_/mysql/
 [mysql-example-repo]: https://gitlab.com/gitlab-examples/mysql
diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md
index 17d21dbda1c..f787cc0a124 100644
--- a/doc/ci/services/postgres.md
+++ b/doc/ci/services/postgres.md
@@ -110,5 +110,5 @@ available [shared runners](../runners/README.md).
 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.
 
-[hub-pg]: https://hub.docker.com/_/postgres/
+[hub-pg]: https://hub.docker.com/r/_/postgres/
 [postgres-example-repo]: https://gitlab.com/gitlab-examples/postgres
diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md
index b281e8f9f60..80705024d2f 100644
--- a/doc/ci/services/redis.md
+++ b/doc/ci/services/redis.md
@@ -65,5 +65,5 @@ 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.
 
-[hub-redis]: https://hub.docker.com/_/redis/
+[hub-redis]: https://hub.docker.com/r/_/redis/
 [redis-example-repo]: https://gitlab.com/gitlab-examples/redis
diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md
index 210f9c3e849..7c0fb225dac 100644
--- a/doc/ci/ssh_keys/README.md
+++ b/doc/ci/ssh_keys/README.md
@@ -30,7 +30,7 @@ This is the universal solution which works with any type of executor
 ## SSH keys when using the Docker executor
 
 You will first need to create an SSH key pair. For more information, follow the
-instructions to [generate an SSH key](../ssh/README.md).
+instructions to [generate an SSH key](../../ssh/README.md).
 
 Then, create a new **Secret Variable** in your project settings on GitLab
 following **Settings > Variables**. As **Key** add the name `SSH_PRIVATE_KEY`
@@ -57,13 +57,13 @@ before_script:
   # WARNING: Use this only with the Docker executor, if you use it with shell
   # you will overwrite your user's SSH config.
   - mkdir -p ~/.ssh
-  - '[[ -f /.dockerinit ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config`
+  - '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config'
 ```
 
 As a final step, add the _public_ key from the one you created earlier to the
 services that you want to have an access to from within the build environment.
 If you are accessing a private GitLab repository you need to add it as a
-[deploy key](../ssh/README.md#deploy-keys).
+[deploy key](../../ssh/README.md#deploy-keys).
 
 That's it! You can now have access to private servers or repositories in your
 build environment.
@@ -79,12 +79,12 @@ on, and use that key for all projects that are run on this machine.
 First, you need to login to the server that runs your builds.
 
 Then from the terminal login as the `gitlab-runner` user and generate the SSH
-key pair as described in the [SSH keys documentation](../ssh/README.md).
+key pair as described in the [SSH keys documentation](../../ssh/README.md).
 
 As a final step, add the _public_ key from the one you created earlier to the
 services that you want to have an access to from within the build environment.
 If you are accessing a private GitLab repository you need to add it as a
-[deploy key](../ssh/README.md#deploy-keys).
+[deploy key](../../ssh/README.md#deploy-keys).
 
 Once done, try to login to the remote server in order to accept the fingerprint:
 
diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md
index 9f7c1bfe6a0..5c316510d0e 100644
--- a/doc/ci/triggers/README.md
+++ b/doc/ci/triggers/README.md
@@ -33,7 +33,7 @@ POST /projects/:id/trigger/builds
 
 The required parameters are the trigger's `token` and the Git `ref` on which
 the trigger will be performed. Valid refs are the branch, the tag or the commit
-SHA. The `:id` of a project can be found by [querying the API](../api/projects.md)
+SHA. The `:id` of a project can be found by [querying the API](../../api/projects.md)
 or by visiting the **Triggers** page which provides self-explanatory examples.
 
 When a rebuild is triggered, the information is exposed in GitLab's UI under
@@ -85,6 +85,12 @@ curl -X POST \
 
 In this case, the project with ID `9` will get rebuilt on `master` branch.
 
+Alternatively, you can pass the `token` and `ref` arguments in the query string:
+
+```bash
+curl -X POST \
+    "https://gitlab.example.com/api/v3/projects/9/trigger/builds?token=TOKEN&ref=master"
+```
 
 ### Triggering a build within `.gitlab-ci.yml`
 
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index b0e53cbc261..137b080a8f7 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -1,17 +1,20 @@
 ## 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**
 
 The variables can be overwritten. They take precedence over each other in this order:
+1. Trigger variables
 1. Secure variables
-1. YAML-defined variables
+1. YAML-defined job-level variables
+1. YAML-defined global variables
 1. Predefined variables
 
 For example, if you define:
-1. API_TOKEN=SECURE as Secure Variable
-1. API_TOKEN=YAML as YAML-defined variable
+1. `API_TOKEN=SECURE` as Secure Variable
+1. `API_TOKEN=YAML` as YAML-defined variable
 
-The API_TOKEN will take the Secure Variable value: `SECURE`.
+The `API_TOKEN` will take the Secure Variable value: `SECURE`.
 
 ### Predefined variables (Environment Variables)
 
@@ -31,6 +34,7 @@ The API_TOKEN will take the Secure Variable value: `SECURE`.
 | **CI_BUILD_ID**         | all | The unique id of the current build that GitLab CI uses internally |
 | **CI_BUILD_REPO**       | all | The URL to clone the Git repository |
 | **CI_BUILD_TRIGGERED**  | 0.5 | The flag to indicate that build was [triggered] |
+| **CI_BUILD_TOKEN**      | 1.2 | Token used for authenticating with the GitLab Container Registry |
 | **CI_PROJECT_ID**       | all | The unique id of the current project that GitLab CI uses internally |
 | **CI_PROJECT_DIR**      | all | The full path where the repository is cloned and where the build is ran |
 
@@ -47,6 +51,7 @@ export CI_BUILD_TAG="1.0.0"
 export CI_BUILD_NAME="spec:other"
 export CI_BUILD_STAGE="test"
 export CI_BUILD_TRIGGERED="true"
+export CI_BUILD_TOKEN="abcde-1234ABCD5678ef"
 export CI_PROJECT_DIR="/builds/gitlab-org/gitlab-ce"
 export CI_PROJECT_ID="34"
 export CI_SERVER="yes"
@@ -70,15 +75,20 @@ 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 at a global level, but also at 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
+the 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.
+The variables are securely passed to GitLab Runner and are available in the
+build environment.
+It's desired method to use them for storing passwords, secret keys or whatever
+you want.
 
 **The value of the variable can be shown in build log if explicitly asked to do so.**
 If your project is public or internal you can make the builds private.
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index a9b79bbdb1b..9c98f9c98c6 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -1,5 +1,53 @@
 # Configuration of your builds with .gitlab-ci.yml
 
+This document describes the usage of `.gitlab-ci.yml`, the file that is used by
+GitLab Runner to manage your project's builds.
+
+If you want a quick introduction to GitLab CI, follow our
+[quick start guide](../quick_start/README.md).
+
+---
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [.gitlab-ci.yml](#gitlab-ci-yml)
+    - [image and services](#image-and-services)
+    - [before_script](#before_script)
+    - [after_script](#after_script)
+    - [stages](#stages)
+    - [types](#types)
+    - [variables](#variables)
+    - [cache](#cache)
+        - [cache:key](#cache-key)
+- [Jobs](#jobs)
+    - [script](#script)
+    - [stage](#stage)
+    - [job variables](#job-variables)
+    - [only and except](#only-and-except)
+    - [tags](#tags)
+    - [when](#when)
+    - [environment](#environment)
+    - [artifacts](#artifacts)
+        - [artifacts:name](#artifacts-name)
+        - [artifacts:when](#artifacts-when)
+        - [artifacts:expire_in](#artifacts-expire_in)
+    - [dependencies](#dependencies)
+    - [before_script and after_script](#before_script-and-after_script)
+- [Hidden jobs](#hidden-jobs)
+- [Special YAML features](#special-yaml-features)
+    - [Anchors](#anchors)
+- [Validate the .gitlab-ci.yml](#validate-the-gitlab-ci-yml)
+- [Skipping builds](#skipping-builds)
+- [Examples](#examples)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+---
+
+## .gitlab-ci.yml
+
 From version 7.12, GitLab CI uses a [YAML](https://en.wikipedia.org/wiki/YAML)
 file (`.gitlab-ci.yml`) for the project configuration. It is placed in the root
 of your repository and contains definitions of how your project should be built.
@@ -23,12 +71,10 @@ Of course a command can execute code directly (`./configure;make;make install`)
 or run a script (`test.sh`) in the repository.
 
 Jobs are used to create builds, which are then picked up by
-[runners](../runners/README.md) and executed within the environment of the
-runner. What is important, is that each job is run independently from each
+[Runners](../runners/README.md) and executed within the environment of the
+Runner. What is important, is that each job is run independently from each
 other.
 
-## .gitlab-ci.yml
-
 The YAML syntax allows for using more complex job specifications than in the
 above example:
 
@@ -38,7 +84,10 @@ services:
   - postgres
 
 before_script:
-  - bundle_install
+  - bundle install
+
+after_script:
+  - rm secrets
 
 stages:
   - build
@@ -64,6 +113,7 @@ There are a few reserved `keywords` that **cannot** be used as job names:
 | stages        | no | Define build stages |
 | types         | no | Alias for `stages` |
 | before_script | no | Define commands that run before each job's script |
+| after_script  | no | Define commands that run after each job's script |
 | variables     | no | Define build variables |
 | cache         | no | Define list of files that should be cached between subsequent runs |
 
@@ -71,13 +121,21 @@ There are a few reserved `keywords` that **cannot** be used as job names:
 
 This allows to specify a custom Docker image and a list of services that can be
 used for time of the build. The configuration of this feature is covered in
-separate document: [Use Docker](../docker/README.md).
+[a separate document](../docker/README.md).
 
 ### before_script
 
 `before_script` is used to define the command that should be run before all
 builds, including deploy builds. This can be an array or a multi-line string.
 
+### after_script
+
+>**Note:**
+Introduced in GitLab 8.7 and requires Gitlab Runner v1.2 (not yet released)
+
+`after_script` is used to define the command that will be run after for all
+builds. This has to be an array or a multi-line string.
+
 ### stages
 
 `stages` is used to define build stages that can be used by jobs.
@@ -86,7 +144,8 @@ The specification of `stages` allows for having flexible multi stage pipelines.
 The ordering of elements in `stages` defines the ordering of builds' execution:
 
 1. Builds of the same stage are run in parallel.
-1. Builds of next stage are run after success.
+1. Builds of the next stage are run after the jobs from the previous stage
+   complete successfully.
 
 Let's consider the following example, which defines 3 stages:
 
@@ -98,9 +157,9 @@ stages:
 ```
 
 1. First all jobs of `build` are executed in parallel.
-1. If all jobs of `build` succeeds, the `test` jobs are executed in parallel.
-1. If all jobs of `test` succeeds, the `deploy` jobs are executed in parallel.
-1. If all jobs of `deploy` succeeds, the commit is marked as `success`.
+1. If all jobs of `build` succeed, the `test` jobs are executed in parallel.
+1. If all jobs of `test` succeed, the `deploy` jobs are executed in parallel.
+1. If all jobs of `deploy` succeed, the commit is marked as `success`.
 1. If any of the previous jobs fails, the commit is marked as `failed` and no
    jobs of further stage are executed.
 
@@ -133,6 +192,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:**
@@ -278,21 +339,27 @@ job_name:
 
 | Keyword       | Required | Description |
 |---------------|----------|-------------|
-| script        | yes | Defines a shell script which is executed by runner |
+| script        | yes | Defines a shell script which is executed by Runner |
+| image         | no | Use docker image, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) |
+| 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 |
+| tags          | no | Defines a list of tags which are used to select Runner |
 | allow_failure | no | Allow build to fail. Failed build doesn't contribute to commit status |
 | when          | no | Define when to run build. Can be `on_success`, `on_failure` or `always` |
 | dependencies  | no | Define other builds that a build depends on so that you can pass artifacts between them|
-| artifacts     | no | Define list build artifacts |
+| artifacts     | no | Define list of build artifacts |
 | cache         | no | Define list of files that should be cached between subsequent runs |
+| before_script | no | Override a set of commands that are executed before build |
+| after_script  | no | Override a set of commands that are executed after build |
+| environment   | no | Defines a name of environment to which deployment is done by this build |
 
 ### script
 
-`script` is a shell script which is executed by the runner. For example:
+`script` is a shell script which is executed by the Runner. For example:
 
 ```yaml
 job:
@@ -329,7 +396,7 @@ There are a few rules that apply to the usage of refs policy:
 * `only` and `except` are inclusive. If both `only` and `except` are defined
    in a job specification, the ref is filtered by `only` and `except`.
 * `only` and `except` allow the use of regular expressions.
-* `only` and `except` allow the use of special keywords: `branches` and `tags`.
+* `only` and `except` allow the use of special keywords: `branches`, `tags`, and `triggers`.
 * `only` and `except` allow to specify a repository path to filter jobs for
    forks.
 
@@ -346,6 +413,17 @@ job:
     - branches
 ```
 
+In this example, `job` will run only for refs that are tagged, or if a build is explicitly requested
+via an API trigger.
+
+```yaml
+job:
+  # use special keywords
+  only:
+    - tags
+    - triggers
+```
+
 The repository path can be used to have jobs executed only for the parent
 repository and not forks:
 
@@ -360,15 +438,27 @@ 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 as its global-level equivalent but
+allows you to define job-specific build variables.
+
+When the `variables` keyword is used on a job level, it overrides global YAML
+build variables and predefined variables.
+
+Build variables priority is defined in
+[variables documentation](../variables/README.md).
+
 ### tags
 
-`tags` is used to select specific runners from the list of all runners that are
+`tags` is used to select specific Runners from the list of all Runners that are
 allowed to run this project.
 
-During the registration of a runner, you can specify the runner's tags, for
+During the registration of a Runner, you can specify the Runner's tags, for
 example `ruby`, `postgres`, `development`.
 
-`tags` allow you to run builds with runners that have the specified tags
+`tags` allow you to run builds with Runners that have the specified tags
 assigned to them:
 
 ```yaml
@@ -378,7 +468,7 @@ job:
     - postgres
 ```
 
-The specification above, will make sure that `job` is built by a runner that
+The specification above, will make sure that `job` is built by a Runner that
 has both `ruby` AND `postgres` tags defined.
 
 ### when
@@ -437,6 +527,31 @@ The above script will:
 1. Execute `cleanup_build_job` only when `build_job` fails
 2. Always execute `cleanup_job` as the last step in pipeline.
 
+### environment
+
+>**Note:**
+Introduced in GitLab v8.9.0.
+
+`environment` is used to define that job does deployment to specific environment.
+This allows to easily track all deployments to your environments straight from GitLab.
+
+If `environment` is specified and no environment under that name does exist a new one will be created automatically.
+
+The `environment` name must contain only letters, digits, '-' and '_'.
+
+---
+
+**Example configurations**
+
+```
+deploy to production:
+  stage: deploy
+  script: git push production HEAD:master
+  environment: production
+```
+
+The `deploy to production` job will be marked as doing deployment to `production` environment.
+
 ### artifacts
 
 >**Notes:**
@@ -565,6 +680,66 @@ 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
+```
+
+#### artifacts:expire_in
+
+>**Note:**
+Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
+
+`artifacts:expire_in` is used to remove uploaded artifacts after specified time.
+By default artifacts are stored on GitLab forver.
+`expire_in` allows to specify after what time the artifacts should be removed.
+The artifacts will expire counting from the moment when they are uploaded and stored on GitLab.
+
+After artifacts uploading you can use the **Keep** button on build page to keep the artifacts forever.
+
+Artifacts are removed every hour, but they are not accessible after expire date.
+
+The value of `expire_in` is a elapsed time. The example of parsable values:
+- '3 mins 4 sec'
+- '2 hrs 20 min'
+- '2h20min'
+- '6 mos 1 day'
+- '47 yrs 6 mos and 4d'
+- '3 weeks and 2 days'
+
+---
+
+**Example configurations**
+
+To expire artifacts after 1 week from the moment that they are uploaded:
+
+```yaml
+job:
+  artifacts:
+    expire_in: 1 week
+```
+
 ### dependencies
 
 >**Note:**
@@ -622,6 +797,23 @@ deploy:
   script: make deploy
 ```
 
+### before_script and after_script
+
+It's possible to overwrite globally defined `before_script` and `after_script`:
+
+```yaml
+before_script
+- global before script
+
+job:
+  before_script:
+  - execute this instead of global before script
+  script:
+  - my command
+  after_script:
+  - execute this after my script
+```
+
 ## Hidden jobs
 
 >**Note:**