Merge branch 'master' into notification-levels

29 files changed, 1689 insertions, 0 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
new file mode 100644
index 00000000000..97325069ceb
--- /dev/null
+++ b/doc/ci/README.md
@@ -0,0 +1,23 @@
+## GitLab CI Documentation
+
+### User documentation
+
++ [Quick Start](quick_start/README.md)
++ [Configuring project (.gitlab-ci.yml)](yaml/README.md)
++ [Configuring runner](runners/README.md)
++ [Configuring deployment](deployment/README.md)
++ [Using Docker Images](docker/using_docker_images.md)
++ [Using Docker Build](docker/using_docker_build.md)
++ [Using Variables](variables/README.md)
+
+### Examples
+
++ [Test and deploy Ruby applications to Heroku](examples/test-and-deploy-ruby-application-to-heroku.md)
++ [Test and deploy Python applications to Heroku](examples/test-and-deploy-python-application-to-heroku.md)
++ [Test Clojure applications](examples/test-clojure-application.md)
++ Help your favorite programming language and GitLab by sending a merge request with a guide for that language.
+
+### Administrator documentation
+
++ [User permissions](permissions/README.md)
++ [API](api/README.md)
diff --git a/doc/ci/api/README.md b/doc/ci/api/README.md
new file mode 100644
index 00000000000..e47e5c46732
--- /dev/null
+++ b/doc/ci/api/README.md
@@ -0,0 +1,87 @@
+# GitLab CI API
+
+## Resources
+
+- [Projects](projects.md)
+- [Runners](runners.md)
+- [Commits](commits.md)
+- [Builds](builds.md)
+- [Forks](forks.md)
+
+
+## Authentication
+
+GitLab CI API uses different types of authentication depends on what API you use.
+Each API document has section with information about authentication you need to use.
+
+GitLab CI API has 4 authentication methods:
+
+* GitLab user token & GitLab url
+* GitLab CI project token
+* GitLab CI runners registration token
+* GitLab CI runner token
+
+
+### Authentication #1: GitLab user token & GitLab url
+
+Authentication is done by
+sending the `private-token` of a valid user and the `url` of an
+authorized Gitlab instance via a query string along with the API
+request:
+
+    GET http://gitlab.example.com/ci/api/v1/projects?private_token=QVy1PB7sTxfy4pqfZM1U&url=http://demo.gitlab.com/
+
+If preferred, you may instead send the `private-token` as a header in
+your request:
+
+    curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://gitlab.example.com/ci/api/v1/projects?url=http://demo.gitlab.com/"
+
+
+### Authentication #2: GitLab CI project token
+
+Each project in GitLab CI has it own token. 
+It can be used to get project commits and builds information.
+You can use project token only for certain project.
+
+### Authentication #3: GitLab CI runners registration token
+
+This token is not persisted and is generated on each application start.
+It can be used only for registering new runners in system. You can find it on 
+GitLab CI Runners web page https://gitlab-ci.example.com/admin/runners
+
+### Authentication #4: GitLab CI runner token
+
+Every GitLab CI runner has it own token that allow it to receive and update 
+GitLab CI builds. This token exists of internal purposes and should be used only 
+by runners
+
+## JSON
+
+All API requests are serialized using JSON.  You don't need to specify
+`.json` at the end of API URL.
+
+## Status codes
+
+The API is designed to return different status codes according to context and action. In this way if a request results in an error the caller is able to get insight into what went wrong, e.g. status code `400 Bad Request` is returned if a required attribute is missing from the request. The following list gives an overview of how the API functions generally behave.
+
+API request types:
+
+- `GET` requests access one or more resources and return the result as JSON
+- `POST` requests return `201 Created` if the resource is successfully created and return the newly created resource as JSON
+- `GET`, `PUT` and `DELETE` return `200 OK` if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON
+- `DELETE` requests are designed to be idempotent, meaning a request a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind it is the user is not really interested if the resource existed before or not.
+
+The following list shows the possible return codes for API requests.
+
+Return values:
+
+- `200 OK` - The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON
+- `201 Created` - The `POST` request was successful and the resource is returned as JSON
+- `400 Bad Request` - A required attribute of the API request is missing, e.g. the title of an issue is not given
+- `401 Unauthorized` - The user is not authenticated, a valid user token is necessary, see above
+- `403 Forbidden` - The request is not allowed, e.g. the user is not allowed to delete a project
+- `404 Not Found` - A resource could not be accessed, e.g. an ID for a resource could not be found
+- `405 Method Not Allowed` - The request is not supported
+- `409 Conflict` - A conflicting resource already exists, e.g. creating a project with a name that already exists
+- `422 Unprocessable` - The entity could not be processed
+- `500 Server Error` - While handling the request something went wrong on the server side
diff --git a/doc/ci/api/builds.md b/doc/ci/api/builds.md
new file mode 100644
index 00000000000..3b5008ccdb4
--- /dev/null
+++ b/doc/ci/api/builds.md
@@ -0,0 +1,41 @@
+# Builds API
+
+This API used by runners to receive and update builds.
+
+__Authentication is done by runner token__
+
+## Builds
+
+### Runs oldest pending build by runner
+
+    POST /ci/builds/register
+
+Parameters:
+
+  * `token` (required) - The unique token of runner
+
+Returns:
+
+```json
+{
+  "id" : 79,
+  "commands" : "",
+  "path" : "",
+  "ref" : "",
+  "sha" : "",
+  "project_id" : 6,
+  "repo_url" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
+  "before_sha" : ""
+}
+```
+
+
+### Update details of an existing build
+
+    PUT /ci/builds/:id
+
+Parameters:
+
+  * `id` (required) - The ID of a project
+  * `state` (optional) - The state of a build
+  * `trace` (optional) - The trace of a build
diff --git a/doc/ci/api/commits.md b/doc/ci/api/commits.md
new file mode 100644
index 00000000000..4df7afc6c52
--- /dev/null
+++ b/doc/ci/api/commits.md
@@ -0,0 +1,101 @@
+# Commits API
+
+__Authentication is done by GitLab CI project token__
+
+## Commits
+
+### Retrieve all commits per project
+
+Get list of commits per project
+
+    GET /ci/commits
+
+Parameters:
+
+  * `project_id` (required) - The ID of a project
+  * `project_token` (requires) - Project token
+  * `page` (optional)
+  * `per_page` (optional) - items per request (default is 20)
+
+Returns:
+
+```json
+[{
+  "id": 3,
+  "ref": "master",
+  "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
+  "project_id": 2,
+  "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
+  "created_at": "2014-11-05T09:46:35.247Z",
+  "status": "success",
+  "finished_at": "2014-11-05T09:46:44.254Z",
+  "duration": 5.062692165374756,
+  "git_commit_message": "wow\n",
+  "git_author_name": "Administrator",
+  "git_author_email": "admin@example.com",
+  "builds": [{
+    "id": 7,
+    "project_id": 2,
+    "ref": "master",
+    "status": "success",
+    "finished_at": "2014-11-05T09:46:44.254Z",
+    "created_at": "2014-11-05T09:46:35.259Z",
+    "updated_at": "2014-11-05T09:46:44.255Z",
+    "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
+    "started_at": "2014-11-05T09:46:39.192Z",
+    "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
+    "runner_id": 1,
+    "coverage": null,
+    "commit_id": 3
+  }]
+}]
+```
+
+### Create commit
+
+Inform GitLab CI about new commit you want it to build.
+
+__If commit already exists in GitLab CI it will not be created__
+
+
+    POST /ci/commits
+
+Parameters:
+
+  * `project_id` (required) - The ID of a project
+  * `project_token` (requires) - Project token
+  * `data` (required) -  Push data. For example see comment in `lib/api/commits.rb`
+
+Returns:
+
+```json
+{
+  "id": 3,
+  "ref": "master",
+  "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
+  "project_id": 2,
+  "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
+  "created_at": "2014-11-05T09:46:35.247Z",
+  "status": "success",
+  "finished_at": "2014-11-05T09:46:44.254Z",
+  "duration": 5.062692165374756,
+  "git_commit_message": "wow\n",
+  "git_author_name": "Administrator",
+  "git_author_email": "admin@example.com",
+  "builds": [{
+    "id": 7,
+    "project_id": 2,
+    "ref": "master",
+    "status": "success",
+    "finished_at": "2014-11-05T09:46:44.254Z",
+    "created_at": "2014-11-05T09:46:35.259Z",
+    "updated_at": "2014-11-05T09:46:44.255Z",
+    "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
+    "started_at": "2014-11-05T09:46:39.192Z",
+    "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
+    "runner_id": 1,
+    "coverage": null,
+    "commit_id": 3
+  }]
+}
+```
diff --git a/doc/ci/api/forks.md b/doc/ci/api/forks.md
new file mode 100644
index 00000000000..8f32e2d3b40
--- /dev/null
+++ b/doc/ci/api/forks.md
@@ -0,0 +1,23 @@
+# Forks API
+
+This API is intended to aid in the setup and configuration of
+forked projects on Gitlab CI. 
+
+__Authentication is done by GitLab user token & GitLab project token__
+
+## Forks
+
+### Create fork for project
+
+
+
+```
+POST /ci/forks
+```
+
+Parameters:
+
+    project_id (required) - The ID of a project
+    project_token (requires) - Project token
+    private_token(required) - User private token
+    data (required) - GitLab project data (name_with_namespace, web_url, default_branch, ssh_url_to_repo)
diff --git a/doc/ci/api/projects.md b/doc/ci/api/projects.md
new file mode 100644
index 00000000000..54584db0938
--- /dev/null
+++ b/doc/ci/api/projects.md
@@ -0,0 +1,154 @@
+# Projects API
+
+This API is intended to aid in the setup and configuration of
+projects on Gitlab CI. 
+
+__Authentication is done by GitLab user token & GitLab url__
+
+## Projects
+
+### List Authorized Projects
+
+Lists all projects that the authenticated user has access to.
+
+```
+GET /ci/projects
+```
+
+Returns:
+
+```json
+    [
+  {
+    "id" : 271,
+    "name" : "gitlabhq",
+    "timeout" : 1800,
+    "token" : "iPWx6WM4lhHNedGfBpPJNP",
+    "default_ref" : "master",
+    "gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell",
+    "path" : "gitlab/gitlab-shell",
+    "always_build" : false,
+    "polling_interval" : null,
+    "public" : false,
+    "ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
+    "gitlab_id" : 3
+  },
+  {
+    "id" : 272,
+    "name" : "gitlab-ci",
+    "timeout" : 1800,
+    "token" : "iPWx6WM4lhHNedGfBpPJNP",
+    "default_ref" : "master",
+    "gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell",
+    "path" : "gitlab/gitlab-shell",
+    "always_build" : false,
+    "polling_interval" : null,
+    "public" : false,
+    "ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
+    "gitlab_id" : 4
+  }
+]
+```
+
+### List Owned Projects
+
+Lists all projects that the authenticated user owns.
+
+```
+GET /ci/projects/owned
+```
+
+Returns:
+
+```json
+[
+  {
+    "id" : 272,
+    "name" : "gitlab-ci",
+    "timeout" : 1800,
+    "token" : "iPWx6WM4lhHNedGfBpPJNP",
+    "default_ref" : "master",
+    "gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell",
+    "path" : "gitlab/gitlab-shell",
+    "always_build" : false,
+    "polling_interval" : null,
+    "public" : false,
+    "ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
+    "gitlab_id" : 4
+  }
+]
+```
+
+### Single Project
+
+Returns information about a single project for which the user is
+authorized.
+
+    GET /ci/projects/:id
+
+Parameters:
+
+  * `id` (required) - The ID of the Gitlab CI project
+
+### Create Project
+
+Creates a Gitlab CI project using Gitlab project details.
+
+    POST /ci/projects
+
+Parameters:
+
+  * `name` (required) - The name of the project
+  * `gitlab_id` (required) - The ID of the project on the Gitlab instance
+  * `path` (required) - The gitlab project path
+  * `ssh_url_to_repo` (required) - The gitlab SSH url to the repo
+  * `default_ref` (optional) - The branch to run on (default to `master`)
+
+### Update Project
+
+Updates a Gitlab CI project using Gitlab project details that the
+authenticated user has access to.
+
+    PUT /ci/projects/:id
+
+Parameters:
+
+  * `name` - The name of the project
+  * `gitlab_id` - The ID of the project on the Gitlab instance
+  * `path` - The gitlab project path
+  * `ssh_url_to_repo` - The gitlab SSH url to the repo
+  * `default_ref` - The branch to run on (default to `master`)
+
+### Remove Project
+
+Removes a Gitlab CI project that the authenticated user has access to.
+
+    DELETE /ci/projects/:id
+
+Parameters:
+
+  * `id` (required) - The ID of the Gitlab CI project
+
+### Link Project to Runner
+
+Links a runner to a project so that it can make builds (only via
+authorized user).
+
+    POST /ci/projects/:id/runners/:runner_id
+
+Parameters:
+
+  * `id` (required) - The ID of the Gitlab CI project
+  * `runner_id` (required) - The ID of the Gitlab CI runner
+
+### Remove Project from Runner
+
+Removes a runner from a project so that it can not make builds (only
+via authorized user).
+
+    DELETE /ci/projects/:id/runners/:runner_id
+
+Parameters:
+
+  * `id` (required) - The ID of the Gitlab CI project
+  * `runner_id` (required) - The ID of the Gitlab CI runner
\ No newline at end of file
diff --git a/doc/ci/api/runners.md b/doc/ci/api/runners.md
new file mode 100644
index 00000000000..e9f88ee066e
--- /dev/null
+++ b/doc/ci/api/runners.md
@@ -0,0 +1,77 @@
+# Runners API
+
+## Runners
+
+### Retrieve all runners
+
+__Authentication is done by GitLab user token & GitLab url__
+
+Used to get information about all runners registered on the Gitlab CI
+instance.
+
+    GET /ci/runners
+
+Returns:
+
+```json
+[
+  {
+    "id" : 85,
+    "token" : "12b68e90394084703135"
+  },
+  {
+    "id" : 86,
+    "token" : "76bf894e969364709864"
+  },
+]
+```
+
+### Register a new runner
+
+
+__Authentication is done with a Shared runner registration token or a project Specific runner registration token__
+
+Used to make Gitlab CI aware of available runners.
+
+    POST /ci/runners/register
+
+Parameters:
+
+  * `token` (required) - The registration token. It is 2 types of token you can pass here. 
+
+1. Shared runner registration token
+2. Project specific registration token
+
+Returns:
+
+```json
+{
+  "id" : 85,
+  "token" : "12b68e90394084703135"
+}
+```
+
+### Delete a runner
+
+
+__Authentication is done by runner token__
+
+Used to removing runners.
+
+    DELETE /ci/runners/delete
+
+Parameters:
+
+  * `token` (required) - The runner token.
+
+Returns:
+
+```json
+{
+  "id" : 1,
+  "token" : "d14963981a428f70121777e50643d1",
+  "created_at" : "2015-02-26T11:39:39.232Z",
+  "updated_at" : "2015-02-26T11:39:39.232Z",
+  "description" : "awesome runner"
+}
+```
\ No newline at end of file
diff --git a/doc/ci/deployment/README.md b/doc/ci/deployment/README.md
new file mode 100644
index 00000000000..ffd841ca9e7
--- /dev/null
+++ b/doc/ci/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 send 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/docker/README.md b/doc/ci/docker/README.md
new file mode 100644
index 00000000000..84eaf29efd1
--- /dev/null
+++ b/doc/ci/docker/README.md
@@ -0,0 +1,4 @@
+# Docker integration
+
++ [Using Docker Images](using_docker_images.md)
++ [Using Docker Build](using_docker_build.md)
\ No newline at end of file
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md
new file mode 100644
index 00000000000..a698fbc8184
--- /dev/null
+++ b/doc/ci/docker/using_docker_build.md
@@ -0,0 +1,112 @@
+# Using Docker Build
+
+GitLab CI can allows you to use Docker Engine to build and test docker-based projects.
+
+**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:
+
+1. create application image,
+1. run test against created image,
+1. push image to remote registry, 
+1. deploy server from pushed image
+
+It's also useful in case when your application already has the `Dockerfile` that can be used to create and test image:
+```bash
+$ docker build -t my-image dockerfiles/
+$ docker run my-docker-image /script/to/run/tests
+$ 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.**
+
+There are two methods to enable the use of `docker build` and `docker run` during build.
+
+## 1. 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.
+
+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 \
+      --url http://gitlab.com/ci \
+      --token RUNNER_TOKEN \
+      --executor shell
+      --description "My Runner"
+    ```
+
+2. Install Docker on server.
+
+    For more information how to install Docker on different systems checkout the [Supported installations](https://docs.docker.com/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 .
+        - docker run my-docker-image /script/to/run/tests
+    ```
+
+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).
+
+## 2. 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:
+
+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:
+
+    ```bash
+    $ sudo gitlab-runner register -n \
+      --url http://gitlab.com/ci \
+      --token RUNNER_TOKEN \
+      --executor docker \
+      --description "My Docker Runner" \
+      --docker-image "gitlab/dind: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:
+    
+    ```yaml
+    before_script:
+      - docker info
+    
+    build_image:
+      script:
+        - docker build -t my-docker-image .
+        - docker run my-docker-image /script/to/run/tests
+    ```
+
+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 you could be interested in checking out [Runtime privilege](https://docs.docker.com/reference/run/#runtime-privilege-linux-capabilities-and-lxc-configuration).
+
diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md
new file mode 100644
index 00000000000..191e3a8144d
--- /dev/null
+++ b/doc/ci/docker/using_docker_images.md
@@ -0,0 +1,203 @@
+# Using Docker Images
+GitLab CI can use [Docker Engine](https://www.docker.com/) to build projects. 
+
+Docker is an open-source project that allows to use predefined images to run applications 
+in independent "containers" that are run within a single Linux instance. 
+[Docker Hub](https://registry.hub.docker.com/) have rich database of  built images that can be used to build applications.
+
+Docker when used with GitLab CI runs each build in separate and isolated container using predefined image and always from scratch.
+It makes it easier to have simple and reproducible build environment that can also be run on your workstation.
+This allows you to test all commands from your shell, rather than having to test them on a CI server.
+
+### Register Docker runner
+To use GitLab Runner with Docker you need to register new runner to use `docker` executor:
+
+```bash
+gitlab-ci-multi-runner register \
+  --url "https://gitlab.com/" \
+  --registration-token "PROJECT_REGISTRATION_TOKEN" \
+  --description "docker-ruby-2.1" \
+  --executor "docker" \
+  --docker-image ruby:2.1 \
+  --docker-postgres latest \
+  --docker-mysql latest
+```
+
+**The registered runner will use `ruby:2.1` image and will run two services (`postgres:latest` and `mysql:latest`) that will be accessible for time of the build.**
+
+### What is image?
+The image is the name of any repository that is present in local Docker Engine or any repository that can be found at [Docker Hub](https://registry.hub.docker.com/). 
+For more information about the image and Docker Hub please read the [Docker Fundamentals](https://docs.docker.com/introduction/understanding-docker/).
+
+### What is service?
+Service is just another image that is run for time of your build and is linked to your build. This allows you to access the service image during build time. 
+The service image can run any application, but most common use case is to run some database container, ie.: `mysql`. 
+It's easier and faster to use existing image, run it as additional container than install `mysql` every time project is built.
+
+#### How is service linked to the build?
+There's good document that describes how Docker linking works: [Linking containers together](https://docs.docker.com/userguide/dockerlinks/). 
+To summarize: if you add `mysql` as service to your application, the image will be used to create container that is linked to build container. 
+The service container for MySQL will be accessible under hostname `mysql`.
+So, **to access your database service you have to connect to host: `mysql` instead of socket or `localhost`**.
+
+### How to use other images as services?
+You are not limited to have only database services. 
+You can hand modify `config.toml` to add any image as service found at [Docker Hub](https://registry.hub.docker.com/). 
+Look for `[runners.docker]` section:
+```
+[runners.docker]
+  image = "ruby:2.1"
+  services = ["mysql:latest", "postgres:latest"]
+```
+
+For example you need `wordpress` instance to test some API integration with `Wordpress`. 
+You can for example use this image: [tutum/wordpress](https://registry.hub.docker.com/u/tutum/wordpress/). 
+This is image that have fully preconfigured `wordpress` and have `MySQL` server built-in:
+```
+[runners.docker]
+  image = "ruby:2.1"
+  services = ["mysql:latest", "postgres:latest", "tutum/wordpress:latest"]
+```
+
+Next time when you run your application the `tutum/wordpress` will be started 
+and you will have access to it from your build container under hostname: `tutum_wordpress`.
+
+Alias hostname for the service is made from the image name:
+1. Everything after `:` is stripped,
+2. '/' is replaced to `_`.
+
+### Configuring services
+Many services accept environment variables, which allow you to easily change database names or set account names depending on the environment.
+
+GitLab Runner 0.5.0 and up 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 other 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
+be used instead of the ones that were specified during runner's registration.
+```
+image: ruby:2.2
+services:
+  - postgres:9.3
+before_install:
+  - bundle install
+  
+test:
+  script:
+  - bundle exec rake spec
+```
+
+It's possible to define image and service per-job:
+```
+before_install:
+  - bundle install
+
+test:2.1:
+  image: ruby:2.1
+  services:
+  - postgres:9.3
+  script:
+  - bundle exec rake spec
+
+test:2.2:
+  image: ruby:2.2
+  services:
+  - postgres:9.4
+  script:
+  - bundle exec rake spec
+```
+
+#### How to enable overwriting?
+To enable overwriting you have to **enable it first** (it's disabled by default for security reasons). 
+You can do that by hand modifying runner configuration: `config.toml`. 
+Please go to section where is `[runners.docker]` definition for your runner. 
+Add `allowed_images` and `allowed_services` to specify what images are allowed to be picked from `.gitlab-ci.yml`:
+```
+[runners.docker]
+  image = "ruby:2.1"
+  allowed_images = ["ruby:*", "python:*"]
+  allowed_services = ["mysql:*", "redis:*"]
+```
+This enables you to use in your `.gitlab-ci.yml` any image that matches above wildcards. 
+You will be able to pick only `ruby` and `python` images. 
+The same rule can be applied to limit services. 
+
+If you are courageous enough, you can make it fully open and accept everything:
+```
+[runners.docker]
+  image = "ruby:2.1"
+  allowed_images = ["*", "*/*"]
+  allowed_services = ["*", "*/*"]
+```
+
+**It the feature is not enabled, or image isn't allowed the error message will be put into the build log.**
+
+### How Docker integration works
+1. Create any service container: `mysql`, `postgresql`, `mongodb`, `redis`.
+1. Create cache container to store all volumes as defined in `config.toml` and `Dockerfile` of build image (`ruby:2.1` as in above example).
+1. Create build container and link any service container to build container.
+1. Start build container and send build script to the container.
+1. Run build script.
+1. Checkout code in: `/builds/group-name/project-name/`.
+1. Run any step defined in `.gitlab-ci.yml`.
+1. Check exit status of build script.
+1. Remove build container and all created service containers.
+
+### How to debug a build locally
+1. Create a file with build script:
+```bash
+$ cat <<EOF > build_script
+git clone https://gitlab.com/gitlab-org/gitlab-ci-multi-runner.git /builds/gitlab-org/gitlab-ci-multi-runner
+cd /builds/gitlab-org/gitlab-ci-multi-runner
+make <- or any other build step
+EOF
+```
+
+1. Create service containers:
+```
+$ docker run -d -n service-mysql mysql:latest
+$ docker run -d -n service-postgres postgres:latest
+```
+This will create two service containers (MySQL and PostgreSQL).
+
+1. Create a build container and execute script in its context:
+```
+$ cat build_script | docker run -n build -i -l mysql:service-mysql -l postgres:service-postgres ruby:2.1 /bin/bash
+```
+This will create build container that has two service containers linked.
+The build_script is piped using STDIN to bash interpreter which executes the build script in container. 
+
+1. At the end remove all containers:
+```
+docker rm -f -v build service-mysql service-postgres
+```
+This will forcefully (the `-f` switch) remove build container and service containers 
+and all volumes (the `-v` switch) that were created with the container creation.
diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md
new file mode 100644
index 00000000000..e0b9fa0e25d
--- /dev/null
+++ b/doc/ci/examples/README.md
@@ -0,0 +1,5 @@
+# Build script examples
+
++ [Test and deploy Ruby Application to Heroku](test-and-deploy-ruby-application-to-heroku.md)
++ [Test and deploy Python Application to Heroku](test-and-deploy-python-application-to-heroku.md)
++ [Test Clojure applications](examples/test-clojure-application.md)
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
new file mode 100644
index 00000000000..036b03dd6b9
--- /dev/null
+++ b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md
@@ -0,0 +1,72 @@
+## Test and Deploy a python application
+This example will guide you how to run tests in your Python application and deploy it automatically as Heroku application.
+
+You can checkout the example [source](https://gitlab.com/ayufan/python-getting-started) and check [CI status](https://ci.gitlab.com/projects/4080).
+
+### Configure project
+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
+  - export DATABASE_URL=postgres://postgres:@postgres:5432/python-test-app
+  - apt-get update -qy
+  - apt-get install -y python-dev python-pip
+  - pip install -r requirements.txt
+  - python manage.py test
+
+staging:
+  type: deploy
+  script:
+  - apt-get update -qy
+  - apt-get install -y ruby-dev
+  - gem install dpl
+  - dpl --provider=heroku --app=gitlab-ci-python-test-staging --api-key=$HEROKU_STAGING_API_KEY
+  only:
+  - master
+
+production:
+  type: deploy
+  script:
+  - apt-get update -qy
+  - apt-get install -y ruby-dev
+  - gem install dpl
+  - dpl --provider=heroku --app=gitlab-ci-python-test-prod --api-key=$HEROKU_PRODUCTION_API_KEY
+  only:
+  - tags
+```
+
+This project has three jobs:
+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
+
+### Store API keys
+You'll need to create two variables in `Project > 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.
+
+Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/account).
+
+### Create Heroku application
+For each of your environments, you'll need to create a new Heroku application.
+You can do this through the [Dashboard](https://dashboard.heroku.com/).
+
+### Create runner
+First install [Docker Engine](https://docs.docker.com/installation/).
+To build this project you also need to have [GitLab Runner](https://about.gitlab.com/gitlab-ci/#gitlab-runner). 
+You can use public runners available on `gitlab.com/ci`, but you can register your own:
+```
+gitlab-ci-multi-runner register \
+  --non-interactive \
+  --url "https://gitlab.com/ci/" \
+  --registration-token "PROJECT_REGISTRATION_TOKEN" \
+  --description "python-3.2" \
+  --executor "docker" \
+  --docker-image python:3.2 \
+  --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.
+
+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
new file mode 100644
index 00000000000..d2a872f1934
--- /dev/null
+++ b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md
@@ -0,0 +1,67 @@
+## Test and Deploy a ruby application
+This example will guide you how to run tests in your Ruby application and deploy it automatiacally as Heroku application.
+
+You can checkout the example [source](https://gitlab.com/ayufan/ruby-getting-started) and check [CI status](https://ci.gitlab.com/projects/4050).
+
+### Configure project
+This is what the `.gitlab-ci.yml` file looks like for this project:
+```yaml
+test:
+  script:
+  - apt-get update -qy
+  - apt-get install -y nodejs
+  - bundle install --path /cache
+  - bundle exec rake db:create RAILS_ENV=test
+  - bundle exec rake test
+
+staging:
+  type: deploy
+  script:
+  - gem install dpl
+  - dpl --provider=heroku --app=gitlab-ci-ruby-test-staging --api-key=$HEROKU_STAGING_API_KEY
+  only:
+  - master
+
+production:
+  type: deploy
+  script:
+  - gem install dpl
+  - dpl --provider=heroku --app=gitlab-ci-ruby-test-prod --api-key=$HEROKU_PRODUCTION_API_KEY
+  only:
+  - tags
+```
+
+This project has three jobs:
+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
+
+### Store API keys
+You'll need to create two variables in `Project > 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.
+
+Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/account).
+
+### Create Heroku application
+For each of your environments, you'll need to create a new Heroku application.
+You can do this through the [Dashboard](https://dashboard.heroku.com/).
+
+### Create runner
+First install [Docker Engine](https://docs.docker.com/installation/).
+To build this project you also need to have [GitLab Runner](https://about.gitlab.com/gitlab-ci/#gitlab-runner).
+You can use public runners available on `gitlab.com/ci`, but you can register your own:
+```
+gitlab-ci-multi-runner register \
+  --non-interactive \
+  --url "https://gitlab.com/ci/" \
+  --registration-token "PROJECT_REGISTRATION_TOKEN" \
+  --description "ruby-2.1" \
+  --executor "docker" \
+  --docker-image ruby:2.1 \
+  --docker-postgres latest
+```
+
+With the command above, you create a runner that uses [ruby:2.1](https://registry.hub.docker.com/u/library/ruby/) image and uses [postgres](https://registry.hub.docker.com/u/library/postgres/) database.
+
+To access PostgreSQL database you need to connect to `host: postgres` as user `postgres` without password.
\ No newline at end of file
diff --git a/doc/ci/examples/test-clojure-application.md b/doc/ci/examples/test-clojure-application.md
new file mode 100644
index 00000000000..eaee94a10f1
--- /dev/null
+++ b/doc/ci/examples/test-clojure-application.md
@@ -0,0 +1,35 @@
+## Test Clojure applications
+
+This example will guide you how to run tests in your Clojure application.
+
+You can checkout the example [source](https://gitlab.com/dzaporozhets/clojure-web-application) and check [CI status](https://ci.gitlab.com/projects/6306).
+
+### Configure project
+
+This is what the `.gitlab-ci.yml` file looks like for this project:
+
+```yaml
+variables:
+  POSTGRES_DB: sample-test
+  DATABASE_URL: "postgresql://postgres@postgres:5432/sample-test"
+
+before_script:
+  - apt-get update -y
+  - apt-get install default-jre postgresql-client -y
+  - wget https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein
+  - chmod a+x lein
+  - export LEIN_ROOT=1
+  - PATH=$PATH:.
+  - lein deps
+  - lein migratus migrate
+
+test: 
+  script: 
+    - lein test
+```
+
+In before script we install JRE and [Leiningen](http://leiningen.org/). 
+Sample project uses [migratus](https://github.com/yogthos/migratus) library to manage database migrations. 
+So we added database migration as last step of `before_script` section
+
+You can use public runners available on `gitlab.com` for testing your application with such configuration.
diff --git a/doc/ci/permissions/README.md b/doc/ci/permissions/README.md
new file mode 100644
index 00000000000..d77061c14cd
--- /dev/null
+++ b/doc/ci/permissions/README.md
@@ -0,0 +1,24 @@
+# Users Permissions
+
+GitLab CI relies on user's role on the GitLab. There are three permissions levels on GitLab CI: admin, master, developer, other.
+
+Admin user can perform any actions on GitLab CI in scope of instance and project. Also user with admin permission can use admin interface.
+
+
+
+
+| Action                                | Guest, Reporter | Developer   | Master   | Admin  |
+|---------------------------------------|-----------------|-------------|----------|--------|
+| See commits and builds                | ✓               | ✓           | ✓        | ✓      |
+| Retry or cancel build                 |                 | ✓           | ✓        | ✓      |
+| Remove project                        |                 |             | ✓        | ✓      |
+| Create project                        |                 |             | ✓        | ✓      |
+| Change project configuration          |                 |             | ✓        | ✓      |
+| Add specific runners                  |                 |             | ✓        | ✓      |
+| Add shared runners                    |                 |             |          | ✓      |
+| See events in the system              |                 |             |          | ✓      |
+| Admin interface                       |                 |             |          | ✓      |
+
+
+
+
diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md
new file mode 100644
index 00000000000..a87a1f806fc
--- /dev/null
+++ b/doc/ci/quick_start/README.md
@@ -0,0 +1,119 @@
+# Quick Start
+
+To start building projects with GitLab CI a few steps needs to be done.
+
+## 1. Install GitLab and CI
+
+First you need to have a working GitLab and GitLab CI instance.
+
+You can omit this step if you use [GitLab.com](http://GitLab.com/).
+
+## 2. Create repository on GitLab
+
+Once you login on your GitLab add a new repository where you will store your source code.
+Push your application to that repository.
+
+## 3. Add project to CI
+
+The next part is to login to GitLab CI.
+Point your browser to the URL you have set GitLab or use [gitlab.com/ci](http://gitlab.com/ci/).
+
+On the first screen you will see a list of GitLab's projects that you have access to:
+
+![Projects](projects.png)
+
+Click **Add Project to CI**.
+This will create project in CI and authorize GitLab CI to fetch sources from GitLab.
+
+> GitLab CI creates unique token that is used to configure GitLab CI service in GitLab.
+> This token allows to access GitLab's repository and configures GitLab to trigger GitLab CI webhook on **Push events** and **Tag push events**.
+> You can see that token by going to Project's Settings > Services > GitLab CI.
+> You will see there token, the same token is assigned in GitLab CI settings of project.
+
+## 4. Create project's configuration - .gitlab-ci.yml
+
+The next: You have to define how your project will be built.
+GitLab CI uses [YAML](https://en.wikipedia.org/wiki/YAML) file to store build configuration.
+You need to create `.gitlab-ci.yml` in root directory of your repository:
+
+```yaml
+before_script:
+  - bundle install
+
+rspec:
+  script:
+    - bundle exec rspec
+
+rubocop:
+  script:
+    - bundle exec rubocop
+```
+
+This is the simplest possible build configuration that will work for most Ruby applications:
+1. Define two jobs `rspec` and `rubocop` with two different commands to be executed.
+1. Before every job execute commands defined by `before_script`.
+
+The `.gitlab-ci.yml` defines set of jobs with constrains how and when they should be run.
+The jobs are defined as top-level elements with name and always have to contain the `script`.
+Jobs are used to create builds, which are then picked by [runners](../runners/README.md) and executed within environment of the runner.
+What is important that each job is run independently from each other. 
+
+For more information and complete `.gitlab-ci.yml` syntax, please check the [Configuring project (.gitlab-ci.yml)](../yaml/README.md).
+
+## 5. Add file and push .gitlab-ci.yml to repository
+
+Once you created `.gitlab-ci.yml` you should add it to git repository and push it to GitLab.
+
+```bash
+git add .gitlab-ci.yml
+git commit
+git push origin master
+```
+
+If you refresh the project's page on GitLab CI you will notice a one new commit:
+
+![](new_commit.png)
+
+However the commit has status **pending** which means that commit was not yet picked by runner.
+
+## 6. Configure runner
+
+In GitLab CI, Runners run your builds.
+A runner is a machine (can be virtual, bare-metal or VPS) that picks up builds 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.
+More information about different runner types can be found in [Configuring runner](../runners/README.md).
+
+To check if you have runners assigned to your project go to **Runners**. You will find there information how to setup project specific runner:
+
+1. Install GitLab Runner software. Checkout the [GitLab Runner](https://about.gitlab.com/gitlab-ci/#gitlab-runner) section to install it.
+1. Specify following URL during runner setup: https://gitlab.com/ci/
+1. Use the following registration token during setup: TOKEN
+
+If you do it correctly your runner should be shown under **Runners activated for this project**:
+
+![](runners_activated.png)
+
+### Shared runners
+
+If you use [gitlab.com/ci](http://gitlab.com/ci/) you can use **Shared runners** provided by GitLab Inc.
+These are special virtual machines that are run on GitLab's infrastructure that can build any project.
+To enable **Shared runners** you have to go to **Runners** and click **Enable shared runners** for this project.
+
+## 7. Check status of commit
+
+If everything went OK and you go to commit, the status of the commit should change from **pending** to either **running**, **success** or **failed**.
+
+![](commit_status.png)
+
+You can click **Build ID** to view build log for specific job.
+
+## 8. Congratulations!
+
+You managed to build your first project using GitLab CI.
+You may need to tune your `.gitlab-ci.yml` file to implement build plan for your project.
+A few examples how it can be done you can find on [Examples](../examples/README.md) page.
+
+GitLab CI also offers **the Lint** tool to verify validity of your `.gitlab-ci.yml` which can be useful to troubleshoot potential problems.
+The Lint is available from project's settings or by adding `/lint` to GitLab CI url.
diff --git a/doc/ci/quick_start/build_status.png b/doc/ci/quick_start/build_status.png
new file mode 100644
index 00000000000..333259e6acd
--- /dev/null
+++ b/doc/ci/quick_start/build_status.png
diff --git a/doc/ci/quick_start/commit_status.png b/doc/ci/quick_start/commit_status.png
new file mode 100644
index 00000000000..725b79e6f91
--- /dev/null
+++ b/doc/ci/quick_start/commit_status.png
diff --git a/doc/ci/quick_start/new_commit.png b/doc/ci/quick_start/new_commit.png
new file mode 100644
index 00000000000..3839e893c17
--- /dev/null
+++ b/doc/ci/quick_start/new_commit.png
diff --git a/doc/ci/quick_start/projects.png b/doc/ci/quick_start/projects.png
new file mode 100644
index 00000000000..0b3430a69db
--- /dev/null
+++ b/doc/ci/quick_start/projects.png
diff --git a/doc/ci/quick_start/runners.png b/doc/ci/quick_start/runners.png
new file mode 100644
index 00000000000..25b4046bc00
--- /dev/null
+++ b/doc/ci/quick_start/runners.png
diff --git a/doc/ci/quick_start/runners_activated.png b/doc/ci/quick_start/runners_activated.png
new file mode 100644
index 00000000000..c934bd12f41
--- /dev/null
+++ b/doc/ci/quick_start/runners_activated.png
diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md
new file mode 100644
index 00000000000..68dcfe23ffb
--- /dev/null
+++ b/doc/ci/runners/README.md
@@ -0,0 +1,145 @@
+# Runners
+
+In GitLab CI, Runners run your [yaml](../yaml/README.md).
+A runner is an isolated (virtual) machine that picks up builds
+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.
+
+## Shared vs. Specific Runners
+
+A runner that is specific only runs for the specified project. A shared runner
+can run jobs for every project that has enabled the option
+`Allow shared runners`.
+
+**Shared runners** are useful for jobs that have similar requirements,
+between multiple projects. Rather than having multiple runners idling for
+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
+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.
+
+Projects with high demand of CI activity can also benefit from using specific runners.
+By having dedicated runners you are guaranteed that the runner is not being held
+up by another project's jobs.
+
+You can set up a specific runner to be used by multiple projects. The difference
+with a shared runner is that you have to enable each project explicitly for
+the runner to be able to run its jobs.
+
+Specific runners do not get shared with forked projects automatically.
+A fork does copy the CI settings (jobs, allow shared, etc) of the cloned repository.
+
+# Creating and Registering a Runner
+
+There are several ways to create a runner. Only after creation, upon
+registration its status as Shared or Specific is determined.
+
+[See the documentation for](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/#installation)
+the different methods of installing a Runner instance.
+
+After installing the runner, you can either register it as `Shared` or as `Specific`.
+You can only register a Shared Runner if you have admin access to the GitLab instance.
+
+## Registering a Shared Runner
+
+You can only register a shared runner if you are an admin on the linked
+GitLab instance.
+
+Grab the shared-runner token on the `admin/runners` page of your GitLab CI
+instance.
+
+![shared token](shared_runner.png)
+
+Now simply register the runner as any runner:
+
+```
+sudo gitlab-runner register
+```
+
+Note that you will have to enable `Allows shared runners` for each project
+that you want to make use of a shared runner. This is by default `off`.
+
+## Registering a Specific Runner
+
+Registering a specific can be done in two ways:
+
+1. Creating a runner with the project registration token
+1. Converting a shared runner into a specific runner (one-way, admin only)
+
+There are several ways to create a runner instance. The steps below only
+concern registering the runner on GitLab CI.
+
+###  Registering a Specific Runner with a Project Registration token
+
+To create a specific runner without having admin rights to the GitLab instance,
+visit the project you want to make the runner work for in GitLab CI.
+
+Click on the runner tab and use the registration token you find there to
+setup a specific runner for this project.
+
+![project runners in GitLab CI](project_specific.png)
+
+To register the runner, run the command below and follow instructions:
+
+```
+sudo gitlab-runner register
+```
+
+###  Making an existing Shared Runner Specific
+
+If you are an admin on your GitLab instance,
+you can make any shared runner a specific runner, _but you can not
+make a specific runner a shared runner_.
+
+To make a shared runner specific, go to the runner page (`/admin/runners`)
+and find your runner. Add any projects on the left to make this runner
+run exclusively for these projects, therefore making it a specific runner.
+
+![making a shared runner specific](shared_to_specific_admin.png)
+
+## Using Shared Runners Effectively
+
+If you are planning to use shared runners, there are several things you
+should keep in mind.
+
+### Use Tags
+
+You must setup a runner to be able to run all the different types of jobs
+that it may encounter on the projects it's shared over. This would be
+problematic for large amounts of projects, if it wasn't for tags.
+
+By tagging a Runner for the types of jobs it can handle, you can make sure
+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
+
+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
+that runs jobs on the runner, can access anyone else's code that runs on the runner.
+
+In addition, because you can get access to the runner token, it is possible
+to create a clone of a runner and submit false builds, for example.
+
+The above is easily avoided by restricting the usage of shared runners
+on large public GitLab instances and controlling access to your GitLab instance.
+
+### Forks
+
+Whenever a project is forked, it copies the settings of the jobs that relate
+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
+
+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/runners/project_specific.png b/doc/ci/runners/project_specific.png
new file mode 100644
index 00000000000..f51ea694e78
--- /dev/null
+++ b/doc/ci/runners/project_specific.png
diff --git a/doc/ci/runners/shared_runner.png b/doc/ci/runners/shared_runner.png
new file mode 100644
index 00000000000..9755144eb08
--- /dev/null
+++ b/doc/ci/runners/shared_runner.png
diff --git a/doc/ci/runners/shared_to_specific_admin.png b/doc/ci/runners/shared_to_specific_admin.png
new file mode 100644
index 00000000000..44a4bef22f7
--- /dev/null
+++ b/doc/ci/runners/shared_to_specific_admin.png
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
new file mode 100644
index 00000000000..04c6bf1e3a3
--- /dev/null
+++ b/doc/ci/variables/README.md
@@ -0,0 +1,95 @@
+## 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. Secure variables
+1. YAML-defined variables
+1. Predefined variables
+
+For example, if you define:
+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`.
+
+### Predefined variables (Environment Variables)
+
+| Variable                | Description |
+|-------------------------|-------------|
+| **CI**                  | Mark that build is executed in CI environment |
+| **GITLAB_CI**           | Mark that build is executed in GitLab CI environment |
+| **CI_SERVER**           | Mark that build is executed in CI environment |
+| **CI_SERVER_NAME**      | CI server that is used to coordinate builds |
+| **CI_SERVER_VERSION**   | Not yet defined |
+| **CI_SERVER_REVISION**  | Not yet defined |
+| **CI_BUILD_REF**        | The commit revision for which project is built |
+| **CI_BUILD_BEFORE_SHA** | The first commit that were included in push request |
+| **CI_BUILD_REF_NAME**   | The branch or tag name for which project is built |
+| **CI_BUILD_ID**         | The unique id of the current build that GitLab CI uses internally |
+| **CI_BUILD_REPO**       | The URL to clone the Git repository |
+| **CI_PROJECT_ID**       | The unique id of the current project that GitLab CI uses internally |
+| **CI_PROJECT_DIR**      | The full path where the repository is cloned and where the build is ran |
+
+Example values:
+
+```bash
+export CI_BUILD_BEFORE_SHA="9df57456fa9de2a6d335ca5edf9750ed812b9df0"
+export CI_BUILD_ID="50"
+export CI_BUILD_REF="1ecfd275763eff1d6b4844ea3168962458c9f27a"
+export CI_BUILD_REF_NAME="master"
+export CI_BUILD_REPO="https://gitlab.com/gitlab-org/gitlab-ce.git"
+export CI_PROJECT_DIR="/builds/gitlab-org/gitlab-ce"
+export CI_PROJECT_ID="34"
+export CI_SERVER="yes"
+export CI_SERVER_NAME="GitLab CI"
+export CI_SERVER_REVISION=""
+export CI_SERVER_VERSION=""
+```
+
+### YAML-defined variables
+**This feature requires GitLab Runner 0.5.0 or higher**
+
+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 0.4.0 or higher**
+
+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`).
+These variables are securely stored in GitLab CI database and are hidden in the build log.
+It's desired method to use them for storing passwords, secret keys or whatever you want.
+
+Secure Variables can added by going to `Project > Variables > Add Variable`.
+
+They will be available for all subsequent builds.
+
+### Use variables
+The variables are set as environment variables in build environment and are accessible with normal methods that are used to access such variables.
+In most cases the **bash** is used to execute build script.
+To access variables (predefined and user-defined) in bash environment, prefix the variable name with `$`:
+```
+job_name:
+  script:
+    - echo $CI_BUILD_ID
+```
+
+You can also list all environment variables with `export` command,
+but be aware that this will also expose value of all **Secure Variables** in build log:
+```
+job_name:
+  script:
+    - export
+```
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
new file mode 100644
index 00000000000..4caeccacb7f
--- /dev/null
+++ b/doc/ci/yaml/README.md
@@ -0,0 +1,204 @@
+# Configuration of your builds with .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.
+
+The YAML file defines a set of jobs with constraints stating when they should be run.
+The jobs are defined as top-level elements with a name and always have to contain the `script` clause:
+
+```yaml
+job1:
+  script: "execute-script-for-job1"
+
+job2:
+  script: "execute-script-for-job2"
+```
+
+The above example is the simplest possible CI configuration with two separate jobs,
+where each of the jobs executes a different command.
+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 other.
+
+## .gitlab-ci.yml
+The YAML syntax allows for using more complex job specifications than in the above example:
+
+```yaml
+image: ruby:2.1
+services:
+  - postgres
+
+before_script:
+  - bundle_install
+
+stages:
+  - build
+  - test
+  - deploy
+
+job1:
+  stage: build
+  script:
+    - execute-script-for-job1
+  only:
+    - master
+  tags:
+    - docker
+```
+
+There are a few `keywords` that can't be used as job names:
+
+| keyword       | required | description |
+|---------------|----------|-------------|
+| image         | optional | Use docker image, covered in [Use Docker](../docker/README.md) |
+| services      | optional | Use docker services, covered in [Use Docker](../docker/README.md) |
+| 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.
+The configuration of this feature is covered in separate document: [Use Docker](../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 multiline string.
+
+### stages
+`stages` is used to define build stages that can be used by jobs.
+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.
+
+Let's consider the following example, which defines 3 stages:
+```
+stages:
+  - build
+  - test
+  - deploy
+```
+
+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 any of the previous jobs fails, the commit is marked as `failed` and no jobs of further stage are executed.
+
+There are also two edge cases worth mentioning:
+
+1. If no `stages` is defined in `.gitlab-ci.yml`, then by default the `build`, `test` and `deploy` are allowed to be used as job's stage by default.
+2. If a job doesn't specify `stage`, the job is assigned the `test` stage.
+
+### 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.
+A job is defined by a list of parameters that define the build behaviour.
+
+```yaml
+job_name:
+  script:
+    - rake spec
+    - coverage
+  stage: test
+  only:
+    - master
+  except:
+    - develop
+  tags:
+    - ruby
+    - postgres
+  allow_failure: true
+```
+
+| keyword       | required | description |
+|---------------|----------|-------------|
+| script        | required | Defines a shell script which is executed by runner |
+| stage         | optional (default: test) | Defines a build stage |
+| type          | optional | Alias for `stage` |
+| only          | optional | Defines a list of git refs for which build is created |
+| except        | optional | Defines a list of git refs for which build is not created |
+| tags          | optional | Defines a list of tags which are used to select runner |
+| allow_failure | optional | Allow build to fail. Failed build doesn't contribute to commit status |
+
+### script
+`script` is a shell script which is executed by runner. The shell script is prepended with `before_script`.
+
+```yaml
+job:
+  script: "bundle exec rspec"
+```
+
+This parameter can also contain several commands using an array:
+```yaml
+job:
+  script:
+    - uname -a
+    - bundle exec rspec
+```
+
+### stage
+`stage` allows to group build into different stages. Builds of the same `stage` are executed in `parallel`.
+For more info about the use of `stage` please check the [stages](#stages).
+
+### only and except
+This are two parameters that allow for setting a refs policy to limit when jobs are built:
+1. `only` defines the names of branches and tags for which job will be built.
+2. `except` defines the names of branches and tags for which the job wil **not** be built.
+
+There are a few rules that apply to usage of refs policy:
+
+1. `only` and `except` are exclusive. If both `only` and `except` are defined in job specification only `only` is taken into account.
+1. `only` and `except` allow for using the regexp expressions.
+1. `only` and `except` allow for using special keywords: `branches` and `tags`.
+These names can be used for example to exclude all tags and all branches.
+
+```yaml
+job:
+  only:
+    - /^issue-.*$/ # use regexp
+  except:
+    - branches # use special keyword
+```
+
+### tags
+`tags` is used to select specific runners from the list of all runners that are allowed to run this project.
+
+During registration of a runner, you can specify the runner's tags, ie.: `ruby`, `postgres`, `development`.
+`tags` allow you to run builds with runners that have the specified tags assigned:
+
+```
+job:
+  tags:
+    - ruby
+    - postgres
+```
+
+The above specification will make sure that `job` is built by a runner that have `ruby` AND `postgres` tags defined.
+
+## Validate the .gitlab-ci.yml
+Each instance of GitLab CI has an embedded debug tool called Lint.
+You can find the link to the Lint in the project's settings page or use short url `/lint`.
+
+## Skipping builds
+There is one more way to skip all builds, if your commit message contains tag [ci skip]. In this case, commit will be created but builds will be skipped
\ No newline at end of file